gtk-doc r683 - in trunk: . tests/annotations/docs tests/annotations/src

[stefkost svn gnome org]

Author: stefkost
Date: Sat Feb 21 14:58:20 2009
New Revision: 683
URL: http://svn.gnome.org/viewvc/gtk-doc?rev=683&view=rev

Log:
	* TODO:
	  Planning.
	* gtkdoc-mkdb.in:
	  Update annotations and fix matching to support parameters.
	* tests/annotations/docs/tester-sections.txt:
	* tests/annotations/src/tester.c:
	* tests/annotations/src/tester.h:
	  Update annotation example and add one more.



Modified:
   trunk/ChangeLog
   trunk/TODO
   trunk/gtkdoc-mkdb.in
   trunk/tests/annotations/docs/tester-sections.txt
   trunk/tests/annotations/src/tester.c
   trunk/tests/annotations/src/tester.h

Modified: trunk/TODO
==============================================================================
--- trunk/TODO	(original)
+++ trunk/TODO	Sat Feb 21 14:58:20 2009
@@ -207,9 +207,6 @@
 
 
 = styling =
-== warnings ==
-xsl produces inline style tag for warnings (e.g. deprecation). We could add a
-colored frame and a warning sign /!\.
 == source code examples==
 http://bugzilla.gnome.org/show_bug.cgi?id=536928
 We could also run a postprocessing script in gtkdoc-mkhtml/gtkdoc-fixxref
@@ -247,6 +244,14 @@
 
 
 
+= syntax =
+== wildcards in symbol names ==
+Somtimes one defines a set of function and macros with very simillar purpose, e.g.
+READ_INT8, READ_INT16, READ_INT32. It would be great to allow documenting a symbol
+READ_INT* instead of 3 docs which are copy'n'pasted anyway. In the output we will have
+all matching declarations in one source listing. Multiple wildcards are okay.
+
+
 = documentation best practises #518427 =
 * we'd like offer a more complete skelleton
   * structure

Modified: trunk/gtkdoc-mkdb.in
==============================================================================
--- trunk/gtkdoc-mkdb.in	(original)
+++ trunk/gtkdoc-mkdb.in	Sat Feb 21 14:58:20 2009
@@ -269,18 +269,19 @@
 my %AnnotationsUsed;
 
 my %AnnotationDefinition = (
+    'allow-none' => "NULL is ok, both for passing and for returning.",
     'array' => "Parameter points to an array of items.",
     'default' => "Default parameter value (for in case the <acronym>shadows</acronym>-to function has less parameters).",
     'element-type' => "Generics and defining elements of containers and arrays.",
-    'error-domain' => "Typed errors. Similar to throws in Java.",
-    'in' => "Parameter for input. Default is <acronym>transfer-none</acronym>.",
-    'inout' => "Parameter for input and for returning results. Default is <acronym>transfer-full</acronym>.",
+    'error-domains' => "Typed errors. Similar to throws in Java.",
+    'in' => "Parameter for input. Default is <acronym>transfer none</acronym>.",
+    'inout' => "Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.",
+    'in-out' => "Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.",
     'not-error' => "A GError parameter is not to be handled like a normal GError.",
-    'null-ok' => "NULL is ok, both for passing and for returning.",
-    'out' => "Parameter for returning results. Default is <acronym>transfer-full</acronym>.",
-    'transfer-container' => "Free data container after the code is done.",
-    'transfer-full' => "Free data after the code is done.",
-    'transfer-none' => "Don't free data after the code is done."
+    'out' => "Parameter for returning results. Default is <acronym>transfer full</acronym>.",
+    'transfer container' => "Free data container after the code is done.",
+    'transfer full' => "Free data after the code is done.",
+    'transfer none' => "Don't free data after the code is done."
 );
 
 # Create the root DocBook output directory if it doens't exist.
@@ -1795,7 +1796,26 @@
                         $annotation_extra = " $2";
                     }
                     $param_annotations .= "<acronym>$annotation</acronym>$annotation_extra. ";
-                    $AnnotationsUsed{$annotation} = 1;
+
+                    # need to search for the longest key-match in %AnnotationDefinition
+                    my $match_length=0;
+                    my $match_annotation="";
+                    my $annotationdef;
+                    foreach $annotationdef (keys %AnnotationDefinition) {
+                        if ($annotationdef =~ m/^$annotation/) {
+                            if (length($annotationdef)>$match_length) {
+                                $match_length=length($annotationdef);
+                                $match_annotation=$annotationdef;
+                            }
+                        }
+                    }
+                    if ($match_annotation ne "") {
+                      $AnnotationsUsed{$match_annotation} = 1;
+                    }
+                    else {
+                      &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
+                          "unknown annotation \"$annotation\" in documentation for $symbol.");
+                    }
                 }
                 chomp($param_desc);
                 $param_desc =~ m/^(.*)\.*\s*$/;

Modified: trunk/tests/annotations/docs/tester-sections.txt
==============================================================================
--- trunk/tests/annotations/docs/tester-sections.txt	(original)
+++ trunk/tests/annotations/docs/tester-sections.txt	Sat Feb 21 14:58:20 2009
@@ -3,6 +3,7 @@
 <TITLE>GtkdocTester</TITLE>
 annotation_array_length
 annotation_nullable
+annotation_elementtype
 <SUBSECTION Standard>
 <SUBSECTION Private>
 </SECTION>

Modified: trunk/tests/annotations/src/tester.c
==============================================================================
--- trunk/tests/annotations/src/tester.c	(original)
+++ trunk/tests/annotations/src/tester.c	Sat Feb 21 14:58:20 2009
@@ -29,11 +29,11 @@
 /**
  * annotation_nullable:
  * @uri: a uri
- * @label: (null-ok): an optional string
+ * @label: (allow-none): an optional string
  *
  * Document optional parameters.
  *
- * Returns: (transfer-full) (null-ok): Returns stuff which you have to free after use
+ * Returns: (transfer full) (allow-none): Returns stuff which you have to free after use
  */
 gchar *
 annotation_nullable (const gchar *uri,
@@ -42,4 +42,17 @@
    return NULL;
 }
 
+/**
+ * annotation_elementtype:
+ * @list: (element-type GObject): list of #GObject instances to search
+ *
+ * Document optional parameters.
+ *
+ * Returns: %TRUE for success
+ */
+gboolean
+annotation_elementtype (const GList *list)
+{
+   return TRUE;
+}
 

Modified: trunk/tests/annotations/src/tester.h
==============================================================================
--- trunk/tests/annotations/src/tester.h	(original)
+++ trunk/tests/annotations/src/tester.h	Sat Feb 21 14:58:20 2009
@@ -8,5 +8,7 @@
 
 extern gchar * annotation_nullable (const gchar *uri, const gchar *label);
 
+extern gboolean annotation_elementtype (const GList *list);
+
 #endif // GTKDOC_TESTER_H