q66 pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=8ed6417196c6d69fd546049c717cd182125bacca
commit 8ed6417196c6d69fd546049c717cd182125bacca
Author: Daniel Kolesa <d.kol...@osg.samsung.com>
Date: Tue Jul 14 14:30:41 2015 +0100
eolian/generator: generate @ingroup in doc comments properly
---
src/bin/eolian/docs_generator.c | 66 ++++++++++++++++++++-----
src/bin/eolian/docs_generator.h | 3 +-
src/bin/eolian/eo_generator.c | 4 +-
src/bin/eolian/legacy_generator.c | 2 +-
src/bin/eolian/types_generator.c | 11 +++--
src/tests/eolian/data/class_simple_ref_eo.h | 11 ++++-
src/tests/eolian/data/class_simple_ref_legacy.h | 11 ++++-
src/tests/eolian/data/docs_ref.h | 27 ++++++++--
src/tests/eolian/data/docs_ref_legacy.h | 22 ++++++++-
src/tests/eolian/data/struct_ref.c | 2 +
10 files changed, 132 insertions(+), 27 deletions(-)
diff --git a/src/bin/eolian/docs_generator.c b/src/bin/eolian/docs_generator.c
index 2999c33..2404127 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
+_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, int indent,
- Eina_Strbuf *buf, Eina_Bool use_legacy)
+_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 0f4424a..8286f7d 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 b60b429..20a058d 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 6f49d6b..1a0f0a9 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 7a032ef..5fee46b 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 75d8c0c..3ac3049 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 b116d9f..1c11281 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 c549bcb..44ea78f 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 39c0655..eeddd9f 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 ab3e531..af162a8 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);
--
