forked from enlightenment/efl
eolian/generator: generate @ingroup in doc comments properly
This commit is contained in:
parent
74ad947ded
commit
8ed6417196
|
@ -206,9 +206,30 @@ _append_since(const char *since, int indent, int curl, Eina_Strbuf *buf)
|
|||
return curl;
|
||||
}
|
||||
|
||||
static char *
|
||||
_sanitize_group(const char *group)
|
||||
{
|
||||
if (!group) return NULL;
|
||||
char *ret = strdup(group);
|
||||
char *p;
|
||||
while ((p = strchr(ret, '.'))) *p = '_';
|
||||
return ret;
|
||||
}
|
||||
|
||||
static void
|
||||
_gen_doc_brief(const char *summary, const char *since, int indent,
|
||||
Eina_Strbuf *buf, Eina_Bool use_legacy)
|
||||
_append_group(Eina_Strbuf *buf, char *sgrp, int indent)
|
||||
{
|
||||
if (!sgrp) return;
|
||||
eina_strbuf_append(buf, " * @ingroup ");
|
||||
eina_strbuf_append(buf, sgrp);
|
||||
eina_strbuf_append_char(buf, '\n');
|
||||
_indent_line(buf, indent);
|
||||
free(sgrp);
|
||||
}
|
||||
|
||||
static void
|
||||
_gen_doc_brief(const char *summary, const char *since, const char *group,
|
||||
int indent, Eina_Strbuf *buf, Eina_Bool use_legacy)
|
||||
{
|
||||
int curl = 4 + indent;
|
||||
Eina_Strbuf *wbuf = eina_strbuf_new();
|
||||
|
@ -216,19 +237,25 @@ _gen_doc_brief(const char *summary, const char *since, int indent,
|
|||
curl = _append_section(summary, indent, curl, buf, wbuf, use_legacy);
|
||||
eina_strbuf_free(wbuf);
|
||||
curl = _append_since(since, indent, curl, buf);
|
||||
if ((curl + 3) > DOC_LIMIT(indent))
|
||||
char *sgrp = _sanitize_group(group);
|
||||
if (((curl + 3) > DOC_LIMIT(indent)) || sgrp)
|
||||
{
|
||||
eina_strbuf_append_char(buf, '\n');
|
||||
_indent_line(buf, indent);
|
||||
eina_strbuf_append(buf, " */");
|
||||
if (sgrp) eina_strbuf_append(buf, " *");
|
||||
}
|
||||
else
|
||||
if (sgrp)
|
||||
{
|
||||
eina_strbuf_append_char(buf, '\n');
|
||||
_indent_line(buf, indent);
|
||||
}
|
||||
_append_group(buf, sgrp, indent);
|
||||
eina_strbuf_append(buf, " */");
|
||||
}
|
||||
|
||||
static void
|
||||
_gen_doc_full(const char *summary, const char *description, const char *since,
|
||||
int indent, Eina_Strbuf *buf, Eina_Bool use_legacy)
|
||||
const char *group, int indent, Eina_Strbuf *buf, Eina_Bool use_legacy)
|
||||
{
|
||||
int curl = 0;
|
||||
Eina_Strbuf *wbuf = eina_strbuf_new();
|
||||
|
@ -246,13 +273,20 @@ _gen_doc_full(const char *summary, const char *description, const char *since,
|
|||
curl = _append_since(since, indent, curl, buf);
|
||||
eina_strbuf_append_char(buf, '\n');
|
||||
_indent_line(buf, indent);
|
||||
char *sgrp = _sanitize_group(group);
|
||||
if (sgrp)
|
||||
{
|
||||
eina_strbuf_append(buf, " *\n");
|
||||
_indent_line(buf, indent);
|
||||
}
|
||||
_append_group(buf, sgrp, indent);
|
||||
eina_strbuf_append(buf, " */");
|
||||
eina_strbuf_free(wbuf);
|
||||
}
|
||||
|
||||
Eina_Strbuf *
|
||||
docs_generate_full(const Eolian_Documentation *doc, int indent,
|
||||
Eina_Bool use_legacy)
|
||||
docs_generate_full(const Eolian_Documentation *doc, const char *group,
|
||||
int indent, Eina_Bool use_legacy)
|
||||
{
|
||||
if (!doc) return NULL;
|
||||
|
||||
|
@ -262,9 +296,9 @@ docs_generate_full(const Eolian_Documentation *doc, int indent,
|
|||
|
||||
Eina_Strbuf *buf = eina_strbuf_new();
|
||||
if (!desc)
|
||||
_gen_doc_brief(sum, since, indent, buf, use_legacy);
|
||||
_gen_doc_brief(sum, since, group, indent, buf, use_legacy);
|
||||
else
|
||||
_gen_doc_full(sum, desc, since, indent, buf, use_legacy);
|
||||
_gen_doc_full(sum, desc, since, group, indent, buf, use_legacy);
|
||||
return buf;
|
||||
}
|
||||
|
||||
|
@ -288,6 +322,8 @@ docs_generate_function(const Eolian_Function *fid, Eolian_Function_Type ftype,
|
|||
|
||||
int curl = 0;
|
||||
|
||||
const char *group = eolian_class_full_name_get(eolian_function_class_get(fid));
|
||||
|
||||
if (ftype == EOLIAN_UNRESOLVED)
|
||||
ftype = EOLIAN_METHOD;
|
||||
|
||||
|
@ -382,8 +418,8 @@ docs_generate_function(const Eolian_Function *fid, Eolian_Function_Type ftype,
|
|||
/* only summary, nothing else; generate standard brief doc */
|
||||
if (!desc && !par && !vpar && !rdoc && (ftype == EOLIAN_METHOD || !pdoc))
|
||||
{
|
||||
_gen_doc_brief(sum ? sum : "No description supplied.", since, indent,
|
||||
buf, use_legacy);
|
||||
_gen_doc_brief(sum ? sum : "No description supplied.", since, group,
|
||||
indent, buf, use_legacy);
|
||||
return buf;
|
||||
}
|
||||
|
||||
|
@ -525,6 +561,10 @@ docs_generate_function(const Eolian_Function *fid, Eolian_Function_Type ftype,
|
|||
}
|
||||
|
||||
_indent_line(buf, indent);
|
||||
eina_strbuf_append(buf, " *\n");
|
||||
|
||||
_indent_line(buf, indent);
|
||||
_append_group(buf, _sanitize_group(group), indent);
|
||||
eina_strbuf_append(buf, " */");
|
||||
eina_strbuf_free(wbuf);
|
||||
return buf;
|
||||
|
|
|
@ -8,13 +8,14 @@
|
|||
* @brief Generate standard documentation
|
||||
*
|
||||
* @param[in] doc the documentation
|
||||
* @param[in] group the group to use (can be NULL)
|
||||
* @param[in] indent by how many spaces to indent the comment from second line
|
||||
* @param[in] use_legacy whether to use legacy names
|
||||
*
|
||||
* @return A documentation comment
|
||||
*
|
||||
*/
|
||||
Eina_Strbuf *docs_generate_full(const Eolian_Documentation *doc, int indent, Eina_Bool use_legacy);
|
||||
Eina_Strbuf *docs_generate_full(const Eolian_Documentation *doc, const char *group, int indent, Eina_Bool use_legacy);
|
||||
|
||||
/*
|
||||
* @brief Generate function documentation
|
||||
|
|
|
@ -251,7 +251,7 @@ eo_header_generate(const Eolian_Class *class, Eina_Strbuf *buf)
|
|||
|
||||
if (doc)
|
||||
{
|
||||
Eina_Strbuf *cdoc = docs_generate_full(doc, 0, EINA_FALSE);
|
||||
Eina_Strbuf *cdoc = docs_generate_full(doc, eolian_class_full_name_get(class), 0, EINA_FALSE);
|
||||
if (cdoc)
|
||||
{
|
||||
eina_strbuf_append(buf, eina_strbuf_string_get(cdoc));
|
||||
|
@ -309,7 +309,7 @@ eo_header_generate(const Eolian_Class *class, Eina_Strbuf *buf)
|
|||
|
||||
if (evdoc)
|
||||
{
|
||||
Eina_Strbuf *evdbuf = docs_generate_full(evdoc, 0, EINA_FALSE);
|
||||
Eina_Strbuf *evdbuf = docs_generate_full(evdoc, eolian_class_full_name_get(class), 0, EINA_FALSE);
|
||||
eina_strbuf_append(str_ev, eina_strbuf_string_get(evdbuf));
|
||||
eina_strbuf_append_char(str_ev, '\n');
|
||||
eina_strbuf_free(evdbuf);
|
||||
|
|
|
@ -387,7 +387,7 @@ legacy_header_generate(const Eolian_Class *class, Eina_Strbuf *buf)
|
|||
const Eolian_Documentation *doc = eolian_class_documentation_get(class);
|
||||
if (doc)
|
||||
{
|
||||
Eina_Strbuf *cdoc = docs_generate_full(doc, 0, EINA_TRUE);
|
||||
Eina_Strbuf *cdoc = docs_generate_full(doc, eolian_class_full_name_get(class), 0, EINA_TRUE);
|
||||
if (cdoc)
|
||||
{
|
||||
eina_strbuf_append(buf, eina_strbuf_string_get(cdoc));
|
||||
|
|
|
@ -36,7 +36,12 @@ _concat_name(const Eolian_Type *tp)
|
|||
static Eina_Strbuf *
|
||||
_type_generate(const Eolian_Type *tp, Eina_Bool full, Eina_Bool use_legacy)
|
||||
{
|
||||
Eina_Strbuf *buf = docs_generate_full(eolian_type_documentation_get(tp), 0, use_legacy);
|
||||
char *grp = strdup(eolian_type_full_name_get(tp));
|
||||
char *p = strrchr(grp, '.');
|
||||
if (p) *p = '\0';
|
||||
Eina_Strbuf *buf = docs_generate_full(eolian_type_documentation_get(tp),
|
||||
grp, 0, use_legacy);
|
||||
free(grp);
|
||||
if (!buf) buf = eina_strbuf_new();
|
||||
else eina_strbuf_append_char(buf, '\n');
|
||||
Eolian_Type_Type tp_type = eolian_type_type_get(tp);
|
||||
|
@ -79,7 +84,7 @@ _type_generate(const Eolian_Type *tp, Eina_Bool full, Eina_Bool use_legacy)
|
|||
const char *nl = strrchr(eina_strbuf_string_get(buf), '\n');
|
||||
if (nl)
|
||||
{
|
||||
Eina_Strbuf *fbuf = docs_generate_full(fdoc, strlen(nl), use_legacy);
|
||||
Eina_Strbuf *fbuf = docs_generate_full(fdoc, NULL, strlen(nl), use_legacy);
|
||||
if (fbuf)
|
||||
eina_strbuf_append_printf(buf, " %s",
|
||||
eina_strbuf_string_get(fbuf));
|
||||
|
@ -145,7 +150,7 @@ _type_generate(const Eolian_Type *tp, Eina_Bool full, Eina_Bool use_legacy)
|
|||
const char *nl = strrchr(eina_strbuf_string_get(buf), '\n');
|
||||
if (nl)
|
||||
{
|
||||
Eina_Strbuf *fbuf = docs_generate_full(fdoc, strlen(nl), use_legacy);
|
||||
Eina_Strbuf *fbuf = docs_generate_full(fdoc, NULL, strlen(nl), use_legacy);
|
||||
if (fbuf)
|
||||
eina_strbuf_append_printf(buf, " %s",
|
||||
eina_strbuf_string_get(fbuf));
|
||||
|
|
|
@ -13,7 +13,10 @@ typedef Eo Class_Simple;
|
|||
|
||||
|
||||
#endif
|
||||
/** Class Desc Simple */
|
||||
/** Class Desc Simple
|
||||
*
|
||||
* @ingroup Class_Simple
|
||||
*/
|
||||
#define CLASS_SIMPLE_CLASS class_simple_class_get()
|
||||
|
||||
EAPI const Eo_Class *class_simple_class_get(void) EINA_CONST;
|
||||
|
@ -27,6 +30,8 @@ EAPI const Eo_Class *class_simple_class_get(void) EINA_CONST;
|
|||
* @param[in] value Value description
|
||||
*
|
||||
* @return comment for property set return
|
||||
*
|
||||
* @ingroup Class_Simple
|
||||
*/
|
||||
EOAPI Eina_Bool evas_obj_simple_a_set(int value);
|
||||
#endif
|
||||
|
@ -36,6 +41,8 @@ EOAPI Eina_Bool evas_obj_simple_a_set(int value);
|
|||
* @brief Common desc for a
|
||||
*
|
||||
* @return Value description
|
||||
*
|
||||
* @ingroup Class_Simple
|
||||
*/
|
||||
EOAPI int evas_obj_simple_a_get(void);
|
||||
#endif
|
||||
|
@ -53,6 +60,8 @@ EOAPI void evas_obj_simple_b_set(void);
|
|||
* @param[out] c
|
||||
*
|
||||
* @return comment for method return
|
||||
*
|
||||
* @ingroup Class_Simple
|
||||
*/
|
||||
EOAPI char * evas_obj_simple_foo(int a, char *b, double *c);
|
||||
#endif
|
||||
|
|
|
@ -13,7 +13,10 @@ typedef Eo Class_Simple;
|
|||
|
||||
|
||||
#endif
|
||||
/** Class Desc Simple */
|
||||
/** Class Desc Simple
|
||||
*
|
||||
* @ingroup Class_Simple
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Common desc for a
|
||||
|
@ -23,6 +26,8 @@ typedef Eo Class_Simple;
|
|||
* @param[in] value Value description
|
||||
*
|
||||
* @return comment for property set return
|
||||
*
|
||||
* @ingroup Class_Simple
|
||||
*/
|
||||
EAPI Eina_Bool evas_object_simple_a_set(Class_Simple *obj, int value);
|
||||
|
||||
|
@ -30,6 +35,8 @@ EAPI Eina_Bool evas_object_simple_a_set(Class_Simple *obj, int value);
|
|||
* @brief Common desc for a
|
||||
*
|
||||
* @return Value description
|
||||
*
|
||||
* @ingroup Class_Simple
|
||||
*/
|
||||
EAPI int evas_object_simple_a_get(const Class_Simple *obj);
|
||||
|
||||
|
@ -45,6 +52,8 @@ EAPI void evas_object_simple_b_set(Class_Simple *obj);
|
|||
* @param[out] c
|
||||
*
|
||||
* @return comment for method return
|
||||
*
|
||||
* @ingroup Class_Simple
|
||||
*/
|
||||
EAPI char *evas_object_simple_foo(Class_Simple *obj, int a, char *b, double *c);
|
||||
|
||||
|
|
|
@ -19,6 +19,8 @@ typedef Eo Docs;
|
|||
* This is another paragraph.
|
||||
*
|
||||
* @since 1.66
|
||||
*
|
||||
* @ingroup Foo
|
||||
*/
|
||||
typedef struct _Foo
|
||||
{
|
||||
|
@ -27,7 +29,10 @@ typedef struct _Foo
|
|||
short field3; /** Another field documentation. */
|
||||
} Foo;
|
||||
|
||||
/** Docs for enum Bar. */
|
||||
/** Docs for enum Bar.
|
||||
*
|
||||
* @ingroup Bar
|
||||
*/
|
||||
typedef enum
|
||||
{
|
||||
BAR_BLAH = 0,
|
||||
|
@ -41,10 +46,15 @@ typedef enum
|
|||
* More docs for typedef. See @ref Bar.
|
||||
*
|
||||
* @since 2.0
|
||||
*
|
||||
* @ingroup Alias
|
||||
*/
|
||||
typedef Bar Alias;
|
||||
|
||||
/** Opaque struct docs. See @ref Foo for another struct. */
|
||||
/** Opaque struct docs. See @ref Foo for another struct.
|
||||
*
|
||||
* @ingroup Opaque
|
||||
*/
|
||||
typedef struct _Opaque Opaque;
|
||||
|
||||
|
||||
|
@ -55,6 +65,8 @@ typedef struct _Opaque Opaque;
|
|||
* More docs for class. Testing references now. @ref Foo @ref Bar @ref Alias
|
||||
* @ref pants @ref docs_meth @ref docs_prop_get @ref docs_prop_get
|
||||
* @ref docs_prop_set @ref Foo.field1 @ref Bar.BAR_FOO @ref Docs
|
||||
*
|
||||
* @ingroup Docs
|
||||
*/
|
||||
#define DOCS_CLASS docs_class_get()
|
||||
|
||||
|
@ -68,6 +80,8 @@ EAPI const Eo_Class *docs_class_get(void) EINA_CONST;
|
|||
* @param[in] val Value documentation.
|
||||
*
|
||||
* @since 1.18
|
||||
*
|
||||
* @ingroup Docs
|
||||
*/
|
||||
EOAPI void docs_prop_set(int val);
|
||||
|
||||
|
@ -79,6 +93,8 @@ EOAPI void docs_prop_set(int val);
|
|||
* @return Value documentation.
|
||||
*
|
||||
* @since 1.18
|
||||
*
|
||||
* @ingroup Docs
|
||||
*/
|
||||
EOAPI int docs_prop_get(void);
|
||||
|
||||
|
@ -89,12 +105,17 @@ EOAPI int docs_prop_get(void);
|
|||
* @param[out] c Another param documentation.
|
||||
*
|
||||
* @return Return documentation.
|
||||
*
|
||||
* @ingroup Docs
|
||||
*/
|
||||
EOAPI int docs_meth(int a, float *b, long *c);
|
||||
|
||||
EOAPI extern const Eo_Event_Description _DOCS_EVENT_CLICKED;
|
||||
|
||||
/** Event docs. */
|
||||
/** Event docs.
|
||||
*
|
||||
* @ingroup Docs
|
||||
*/
|
||||
#define DOCS_EVENT_CLICKED (&(_DOCS_EVENT_CLICKED))
|
||||
|
||||
#endif
|
||||
|
|
|
@ -19,6 +19,8 @@ typedef Eo Docs;
|
|||
* This is another paragraph.
|
||||
*
|
||||
* @since 1.66
|
||||
*
|
||||
* @ingroup Foo
|
||||
*/
|
||||
typedef struct _Foo
|
||||
{
|
||||
|
@ -27,7 +29,10 @@ typedef struct _Foo
|
|||
short field3; /** Another field documentation. */
|
||||
} Foo;
|
||||
|
||||
/** Docs for enum Bar. */
|
||||
/** Docs for enum Bar.
|
||||
*
|
||||
* @ingroup Bar
|
||||
*/
|
||||
typedef enum
|
||||
{
|
||||
BAR_BLAH = 0,
|
||||
|
@ -41,10 +46,15 @@ typedef enum
|
|||
* More docs for typedef. See @ref Bar.
|
||||
*
|
||||
* @since 2.0
|
||||
*
|
||||
* @ingroup Alias
|
||||
*/
|
||||
typedef Bar Alias;
|
||||
|
||||
/** Opaque struct docs. See @ref Foo for another struct. */
|
||||
/** Opaque struct docs. See @ref Foo for another struct.
|
||||
*
|
||||
* @ingroup Opaque
|
||||
*/
|
||||
typedef struct _Opaque Opaque;
|
||||
|
||||
|
||||
|
@ -55,6 +65,8 @@ typedef struct _Opaque Opaque;
|
|||
* More docs for class. Testing references now. @ref Foo @ref Bar @ref Alias
|
||||
* @ref pants @ref docs_meth @ref docs_prop_get @ref docs_prop_get
|
||||
* @ref docs_prop_set @ref Foo.field1 @ref Bar.BAR_FOO @ref Docs
|
||||
*
|
||||
* @ingroup Docs
|
||||
*/
|
||||
|
||||
/**
|
||||
|
@ -65,6 +77,8 @@ typedef struct _Opaque Opaque;
|
|||
* @param[in] val Value documentation.
|
||||
*
|
||||
* @since 1.18
|
||||
*
|
||||
* @ingroup Docs
|
||||
*/
|
||||
EAPI void docs_prop_set(Docs *obj, int val);
|
||||
|
||||
|
@ -76,6 +90,8 @@ EAPI void docs_prop_set(Docs *obj, int val);
|
|||
* @return Value documentation.
|
||||
*
|
||||
* @since 1.18
|
||||
*
|
||||
* @ingroup Docs
|
||||
*/
|
||||
EAPI int docs_prop_get(const Docs *obj);
|
||||
|
||||
|
@ -86,6 +102,8 @@ EAPI int docs_prop_get(const Docs *obj);
|
|||
* @param[out] c Another param documentation.
|
||||
*
|
||||
* @return Return documentation.
|
||||
*
|
||||
* @ingroup Docs
|
||||
*/
|
||||
EAPI int docs_meth(Docs *obj, int a, float *b, long *c);
|
||||
|
||||
|
|
|
@ -34,6 +34,8 @@ EAPI const Eo_Class *struct_class_get(void) EINA_CONST;
|
|||
* @brief Foo docs. This is @c monospace. This is alone-standing $.
|
||||
*
|
||||
* @param[in] idx
|
||||
*
|
||||
* @ingroup Struct
|
||||
*/
|
||||
EOAPI char * struct_foo(int idx);
|
||||
|
||||
|
|
Loading…
Reference in New Issue