timer23
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

eolian/generator: generate @ingroup in doc comments properly

This commit is contained in:
Daniel Kolesa 2015-07-14 14:30:41 +01:00
parent 74ad947ded
commit 8ed6417196
10 changed files with 132 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
src/bin/eolian/docs_generator.c
View File

@ -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
eina_strbuf_append(buf, " */");
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;

3
src/bin/eolian/docs_generator.h
View File

@ -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

4
src/bin/eolian/eo_generator.c
View File

@ -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);

2
src/bin/eolian/legacy_generator.c
View File

@ -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));

11
src/bin/eolian/types_generator.c
View File

@ -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));

11
src/tests/eolian/data/class_simple_ref_eo.h
View File

@ -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

11
src/tests/eolian/data/class_simple_ref_legacy.h
View File

@ -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);

27
src/tests/eolian/data/docs_ref.h
View File

@ -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

22
src/tests/eolian/data/docs_ref_legacy.h
View File

@ -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);

2
src/tests/eolian/data/struct_ref.c
View File

@ -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);