diff --git a/src/bin/eolian/docs_generator.c b/src/bin/eolian/docs_generator.c index 2999c334a2..2404127140 100644 --- a/src/bin/eolian/docs_generator.c +++ b/src/bin/eolian/docs_generator.c @@ -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; diff --git a/src/bin/eolian/docs_generator.h b/src/bin/eolian/docs_generator.h index 0f4424a3f2..8286f7db97 100644 --- a/src/bin/eolian/docs_generator.h +++ b/src/bin/eolian/docs_generator.h @@ -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 diff --git a/src/bin/eolian/eo_generator.c b/src/bin/eolian/eo_generator.c index b60b4299d8..20a058d37f 100644 --- a/src/bin/eolian/eo_generator.c +++ b/src/bin/eolian/eo_generator.c @@ -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); diff --git a/src/bin/eolian/legacy_generator.c b/src/bin/eolian/legacy_generator.c index 6f49d6b3cd..1a0f0a9bd6 100644 --- a/src/bin/eolian/legacy_generator.c +++ b/src/bin/eolian/legacy_generator.c @@ -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)); diff --git a/src/bin/eolian/types_generator.c b/src/bin/eolian/types_generator.c index 7a032ef27e..5fee46b729 100644 --- a/src/bin/eolian/types_generator.c +++ b/src/bin/eolian/types_generator.c @@ -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)); diff --git a/src/tests/eolian/data/class_simple_ref_eo.h b/src/tests/eolian/data/class_simple_ref_eo.h index 75d8c0ccfd..3ac3049f8f 100644 --- a/src/tests/eolian/data/class_simple_ref_eo.h +++ b/src/tests/eolian/data/class_simple_ref_eo.h @@ -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 diff --git a/src/tests/eolian/data/class_simple_ref_legacy.h b/src/tests/eolian/data/class_simple_ref_legacy.h index b116d9fc49..1c112814b1 100644 --- a/src/tests/eolian/data/class_simple_ref_legacy.h +++ b/src/tests/eolian/data/class_simple_ref_legacy.h @@ -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); diff --git a/src/tests/eolian/data/docs_ref.h b/src/tests/eolian/data/docs_ref.h index c549bcbaea..44ea78f11c 100644 --- a/src/tests/eolian/data/docs_ref.h +++ b/src/tests/eolian/data/docs_ref.h @@ -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 diff --git a/src/tests/eolian/data/docs_ref_legacy.h b/src/tests/eolian/data/docs_ref_legacy.h index 39c06555f2..eeddd9faae 100644 --- a/src/tests/eolian/data/docs_ref_legacy.h +++ b/src/tests/eolian/data/docs_ref_legacy.h @@ -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); diff --git a/src/tests/eolian/data/struct_ref.c b/src/tests/eolian/data/struct_ref.c index ab3e531fe1..af162a831f 100644 --- a/src/tests/eolian/data/struct_ref.c +++ b/src/tests/eolian/data/struct_ref.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);