eolian/generator: generate @ingroup in doc comments properly

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,
+_append_group(Eina_Strbuf *buf, char *sgrp, int indent)
-               Eina_Strbuf *buf, Eina_Bool use_legacy)
+{
+   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(buf, " */");
+     {
+        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,
+docs_generate_full(const Eolian_Documentation *doc, const char *group,
-                   Eina_Bool use_legacy)
+                   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,
+        _gen_doc_brief(sum ? sum : "No description supplied.", since, group,
-                       buf, use_legacy);
+                       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;

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

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

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

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

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

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

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

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

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