[gtk-doc] tests: add more cases to the tests and fix some issues

From: Stefan Kost <stefkost src gnome org>
To: svn-commits-list gnome org
Cc:
Subject: [gtk-doc] tests: add more cases to the tests and fix some issues
Date: Wed, 30 Dec 2009 22:26:38 +0000 (UTC)
commit 056a26b21e3ac64bea1f2673228675f4cf0b982a
Author: Stefan Kost <ensonic users sf net>
Date:   Thu Dec 31 00:22:11 2009 +0200

    tests: add more cases to the tests and fix some issues
    
    Add missing docs here and there. Add cases to test handling of missing,
    incomplete and unexisting docs.

 tests/annotations/src/tester.c              |    2 +-
 tests/bugs/docs/tester-sections.txt         |    4 +
 tests/bugs/src/tester.c                     |   23 ++++++
 tests/bugs/src/tester.h                     |   10 ++-
 tests/fail.sh                               |    4 +-
 tests/fail/docs/tester-docs.xml             |    3 +
 tests/fail/docs/tester-sections.txt         |   27 +++++---
 tests/fail/src/tester.c                     |   57 +++++++++++++++
 tests/fail/src/tester.h                     |  100 +++++++++++++++++++++++++--
 tests/gobject/docs-tmpl/tester-sections.txt |    1 +
 tests/gobject/docs/tester-sections.txt      |    1 +
 tests/gobject/src/gobject.c                 |   16 ++++-
 tests/gobject/src/gobject.h                 |    4 +-
 13 files changed, 230 insertions(+), 22 deletions(-)
---
diff --git a/tests/annotations/src/tester.c b/tests/annotations/src/tester.c
index 8df6936..71dad7f 100644
--- a/tests/annotations/src/tester.c
+++ b/tests/annotations/src/tester.c
@@ -12,7 +12,7 @@
 
 /**
  * annotation_array_length:
- * @store: a #GtkListStore
+ * @list: a #GtkListStore
  * @n_columns: number of columns
  * @types: (array length=n_columns): list of types
  *
diff --git a/tests/bugs/docs/tester-sections.txt b/tests/bugs/docs/tester-sections.txt
index 7308123..e29e7bc 100644
--- a/tests/bugs/docs/tester-sections.txt
+++ b/tests/bugs/docs/tester-sections.txt
@@ -29,6 +29,10 @@ bug_552602
 bug_554833
 bug_574654a
 bug_574654b
+bug_580300a_get_type
+bug_580300b_get_type
+bug_580300c_get_type
+bug_580300d_get_type
 bug_602518a
 bug_602518b
 bug_602518c
diff --git a/tests/bugs/src/tester.c b/tests/bugs/src/tester.c
index b8e361a..f79483b 100644
--- a/tests/bugs/src/tester.c
+++ b/tests/bugs/src/tester.c
@@ -142,12 +142,35 @@ int bug_574654a(void) {
 void bug_574654b(double offset) { }
 
 
+/**
+ * bug_580300a_get_type:
+ *
+ * http://bugzilla.gnome.org/show_bug.cgi?id=580300
+ */
 void bug_580300a_get_type(void) { }
 
+/**
+ * bug_580300b_get_type:
+ * @a: value
+ *
+ * http://bugzilla.gnome.org/show_bug.cgi?id=580300
+ */
 void bug_580300b_get_type(gint a) { }
 
+/**
+ * bug_580300c_get_type:
+ *
+ * http://bugzilla.gnome.org/show_bug.cgi?id=580300
+ */
 void bug_580300c_get_type() { }
 
+/**
+ * bug_580300d_get_type:
+ *
+ * http://bugzilla.gnome.org/show_bug.cgi?id=580300
+ *
+ * Returns: result
+ */
 int bug_580300d_get_type() { }
 
 
diff --git a/tests/bugs/src/tester.h b/tests/bugs/src/tester.h
index 488f4f3..10266a3 100644
--- a/tests/bugs/src/tester.h
+++ b/tests/bugs/src/tester.h
@@ -125,6 +125,9 @@ typedef int
 
 /**
  * bug_512155b_function_pointer_t:
+ * @arg1: param 1
+ * @arg2: param 1
+ * @arg3: param 1
  *
  * http://bugzilla.gnome.org/show_bug.cgi?id=512155
  */
@@ -134,6 +137,9 @@ int (*bug_512155b_function_pointer_t) (unsigned int arg1, unsigned int arg2,
 
 /**
  * bug_512155c_function_pointer_t:
+ * @arg1: param 1
+ * @arg2: param 1
+ * @arg3: param 1
  *
  * http://bugzilla.gnome.org/show_bug.cgi?id=512155
  */
@@ -213,8 +219,8 @@ struct _bug_554833 {
 struct _bug_554833 *
                 bug_554833_new (void);
 
-#define GTKDOC_GNUC_CONST
-int bug_574654a(void) GTKDOC_GNUC_CONST;
+#define _GTKDOC_GNUC_CONST
+int bug_574654a(void) _GTKDOC_GNUC_CONST;
 void bug_574654b(double offset);
 
 
diff --git a/tests/fail.sh b/tests/fail.sh
index 6139ed9..0e2077a 100755
--- a/tests/fail.sh
+++ b/tests/fail.sh
@@ -27,8 +27,8 @@ grep >/dev/null "tester_noshortdesc:Short_Description" $DOC_MODULE-undocumented.
 if test $? = 1 ; then failed=$(($failed + 1)); fi
 tested=$(($tested + 1))
 
-# check incomplete enum
-grep >/dev/null "Bug568711 (<items>)" $DOC_MODULE-undocumented.txt
+# check enums
+grep >/dev/null "EnumNoItemDocs (<items>)" $DOC_MODULE-undocumented.txt
 if test $? = 1 ; then failed=$(($failed + 1)); fi
 tested=$(($tested + 1))
 
diff --git a/tests/fail/docs/tester-docs.xml b/tests/fail/docs/tester-docs.xml
index 0166307..d7ceb6c 100644
--- a/tests/fail/docs/tester-docs.xml
+++ b/tests/fail/docs/tester-docs.xml
@@ -16,9 +16,12 @@
 
   <chapter>
     <title>Tests</title>
+    <!--
     <xi:include href="xml/tester_nodocs.xml"/>
     <xi:include href="xml/tester_nolongdesc.xml"/>
     <xi:include href="xml/tester_noshortdesc.xml"/>
+    -->
+    <xi:include href="xml/tester_brokendocs.xml"/>
   </chapter>
 
   <index id="api-index">
diff --git a/tests/fail/docs/tester-sections.txt b/tests/fail/docs/tester-sections.txt
index a3fe1b5..a931f70 100644
--- a/tests/fail/docs/tester-sections.txt
+++ b/tests/fail/docs/tester-sections.txt
@@ -1,22 +1,29 @@
 <SECTION>
 <FILE>tester_nodocs</FILE>
-<TITLE>GtkdocTesterNodocs</TITLE>
-Bug568711
-<SUBSECTION Standard>
-<SUBSECTION Private>
 </SECTION>
 
 <SECTION>
 <FILE>tester_nolongdesc</FILE>
-<TITLE>GtkdocTesterNoLongDesc</TITLE>
-<SUBSECTION Standard>
-<SUBSECTION Private>
 </SECTION>
 
 <SECTION>
 <FILE>tester_noshortdesc</FILE>
-<TITLE>GtkdocTesterNoShortDesc</TITLE>
-<SUBSECTION Standard>
-<SUBSECTION Private>
+</SECTION>
+
+<SECTION>
+<FILE>tester_brokendocs</FILE>
+MACRO_NO_ITEM_DOCS
+MACRO_INCOMPLETE_DOCS
+MACRO_UNUSED_DOCS
+EnumNoItemDocs
+EnumIncompleteDocs
+EnumUnusedDocs
+StructNoItemDocs
+StructIncompleteDocs
+StructUnusedDocs
+func_no_docs
+func_no_item_docs
+func_incomplete_docs
+func_unused_docs
 </SECTION>
 
diff --git a/tests/fail/src/tester.c b/tests/fail/src/tester.c
index f2ab66c..f569fee 100644
--- a/tests/fail/src/tester.c
+++ b/tests/fail/src/tester.c
@@ -1,9 +1,25 @@
+/*
+ * SECTION:tester_nodocs
+ * @short_description: module for gtk-doc unit test
+ * @title: GtkdocTesterNoDocs
+ *
+ * This file contains non-sense code for the sole purpose of testing the docs.
+ */
 /**
  * SECTION:tester_nolongdesc
  * @short_description: module for gtk-doc unit test
+ * @title: GtkdocTesterNoLongDesc
  */
 /**
  * SECTION:tester_noshortdesc
+ * @title: GtkdocTesterNoShortDesc
+ *
+ * This file contains non-sense code for the sole purpose of testing the docs.
+ */
+/**
+ * SECTION:tester_brokendocs
+ * @short_description: module for gtk-doc unit test
+ * @title: GtkdocTesterBrokenDocs
  *
  * This file contains non-sense code for the sole purpose of testing the docs.
  */
@@ -12,4 +28,45 @@
 
 #include "tester.h"
 
+/**
+ * func_no_docs:
+ */
+void
+func_no_docs(void)
+{
+}
+
+/**
+ * func_no_item_docs:
+ *
+ * Here we document the function but not the parameters.
+ */
+void
+func_no_item_docs(int a, char b)
+{
+}
+
+/**
+ * func_incomplete_docs:
+ * @a: a value
+ *
+ * Here we document the function but not all the parameters.
+ */
+void
+func_incomplete_docs(int a, char b)
+{
+}
+
+/**
+ * func_unused_docs:
+ * @a: a value
+ * @b: a value
+ * @c: an unexisting value
+ *
+ * Here we document the function and more than the actual parameters.
+ */
+void
+func_unused_docs(int a, char b)
+{
+}
 
diff --git a/tests/fail/src/tester.h b/tests/fail/src/tester.h
index 0b94fd4..70ff7da 100644
--- a/tests/fail/src/tester.h
+++ b/tests/fail/src/tester.h
@@ -4,16 +4,106 @@
 #include <glib.h>
 
 /**
- * Bug568711:
+ * MACRO_NO_ITEM_DOCS:
+ *
+ * Here we document the macro but not the parameters.
+ */
+#define MACRO_NO_ITEM_DOCS(a,b) (a+b)
+
+/**
+ * MACRO_INCOMPLETE_DOCS:
+ * @a: a value
+ *
+ * Here we document the macro but not all the parameters.
+ */
+#define MACRO_INCOMPLETE_DOCS(a,b) (a+b)
+
+/**
+ * MACRO_UNUSED_DOCS:
+ * @a: a value
+ * @b: a value
+ * @c: an unexisting value
+ *
+ * Here we document the macro and more than the actual parameters.
+ */
+#define MACRO_UNUSED_DOCS(a,b) (a+b)
+
+
+/**
+ * EnumNoItemDocs:
  *
  * Here we document the enum but not the values.
- **/
+ * http://bugzilla.gnome.org/show_bug.cgi?id=568711
+ */
+typedef enum {
+    ENUM_NO_ITEM_DOCS_1,
+    ENUM_NO_ITEM_DOCS_2
+} EnumNoItemDocs;
+
+/**
+ * EnumIncompleteDocs:
+ * @ENUM_INCOMPLETE_DOCS_1: a value
+ *
+ * Here we document the enum but not all the values.
+ */
 typedef enum {
-    BUG_568711_ENUM_1,
-    BUG_568711_ENUM_2,
-} Bug568711;
+    ENUM_INCOMPLETE_DOCS_1,
+    ENUM_INCOMPLETE_DOCS_2
+} EnumIncompleteDocs;
+
+/**
+ * EnumUnusedDocs:
+ * @ENUM_UNUSED_DOCS_1: a value
+ * @ENUM_UNUSED_DOCS_2: a value
+ * @ENUM_UNUSED_DOCS_3: an unexisting value
+ *
+ * Here we document the enum and more than the actual values.
+ */
+typedef enum {
+    ENUM_UNUSED_DOCS_1,
+    ENUM_UNUSED_DOCS_2
+} EnumUnusedDocs;
+
+
+/**
+ * StructNoItemDocs:
+ *
+ * Here we document the struct but not the values.
+ */
+typedef struct {
+    int a;
+    char b;
+} StructNoItemDocs;
+
+/**
+ * StructIncompleteDocs:
+ * @a: a value
+ *
+ * Here we document the struct but not all the values.
+ */
+typedef struct {
+    int a;
+    char b;
+} StructIncompleteDocs;
+
+/**
+ * StructUnusedDocs:
+ * @a: a value
+ * @b: a value
+ * @c: an unexisting value
+ *
+ * Here we document the struct and more than the actual values.
+ */
+typedef struct {
+    int a;
+    char b;
+} StructUnusedDocs;
 
 
+void func_no_docs(void);
+void func_no_item_docs(int a, char b);
+void func_incomplete_docs(int a, char b);
+void func_unused_docs(int a, char b);
 
 #endif // GTKDOC_TESTER_H
 
diff --git a/tests/gobject/docs-tmpl/tester-sections.txt b/tests/gobject/docs-tmpl/tester-sections.txt
index 7e96f5b..ee6e874 100644
--- a/tests/gobject/docs-tmpl/tester-sections.txt
+++ b/tests/gobject/docs-tmpl/tester-sections.txt
@@ -5,6 +5,7 @@ GtkdocObjectClass
 gtkdoc_object_new
 gtkdoc_object_set_otest
 gtkdoc_object_frobnicate
+gtkdoc_object_fooify
 GTKDOC_OBJECT_MACRO_DUMMY
 GTKDOC_OBJECT_MACRO_SUM
 <SUBSECTION Standard>
diff --git a/tests/gobject/docs/tester-sections.txt b/tests/gobject/docs/tester-sections.txt
index 7e96f5b..ee6e874 100644
--- a/tests/gobject/docs/tester-sections.txt
+++ b/tests/gobject/docs/tester-sections.txt
@@ -5,6 +5,7 @@ GtkdocObjectClass
 gtkdoc_object_new
 gtkdoc_object_set_otest
 gtkdoc_object_frobnicate
+gtkdoc_object_fooify
 GTKDOC_OBJECT_MACRO_DUMMY
 GTKDOC_OBJECT_MACRO_SUM
 <SUBSECTION Standard>
diff --git a/tests/gobject/src/gobject.c b/tests/gobject/src/gobject.c
index 8c4471b..f004d6d 100644
--- a/tests/gobject/src/gobject.c
+++ b/tests/gobject/src/gobject.c
@@ -66,6 +66,8 @@ GtkdocObject *gtkdoc_object_new (void) {
   return(NULL);
 }
 
+/* methods */
+
 /**
  * gtkdoc_object_set_otest:
  * @self: the object
@@ -99,7 +101,19 @@ void gtkdoc_object_set_otest (GObject *self, const gchar *value) {
 void gtkdoc_object_frobnicate (GObject *self, gint n) {
   
 }
-/* methods */
+
+/**
+ * gtkdoc_object_fooify:
+ * @self: the object
+ * @...: a NULL terminated list of arguments
+ *
+ * Fooify the content of @self.
+ *
+ * Returns: %TRUE for success
+ */
+gboolean gtkdoc_object_fooify (GObject *self, ...) {
+  return TRUE;
+}
 
 /* class internals */
 
diff --git a/tests/gobject/src/gobject.h b/tests/gobject/src/gobject.h
index 1404626..316da46 100644
--- a/tests/gobject/src/gobject.h
+++ b/tests/gobject/src/gobject.h
@@ -20,7 +20,8 @@ typedef struct _GtkdocObjectClass GtkdocObjectClass;
 
 /* in gtkdoc-scan::ScanHeader() we currently skip the enums, but output a decl
 * to -decl.txt and -decl-list.txt for the struct
-* If the symbol has no docs, we get a warning in -unused.txt
+* If the symbol has no docs, we get a warning in -unused.txt for the struct, but
+* not the enum
 */
 typedef struct GtkdocHelperStruct GtkdocHelperStruct;
 typedef enum GtkdocHelperEnum GtkdocHelperEnum;
@@ -67,6 +68,7 @@ GtkdocObject *gtkdoc_object_new(void);
 void gtkdoc_object_set_otest (GObject *self, const gchar *value);
 #endif
 void gtkdoc_object_frobnicate (GObject *self, gint n);
+gboolean gtkdoc_object_fooify (GObject *self, ...);
 
 /**
  * GTKDOC_OBJECT_MACRO_DUMMY:
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]