gtk-doc r666 - in trunk: . tests tests/bugs/src tests/fail/docs tests/fail/src

[stefkost svn gnome org]

Author: stefkost
Date: Mon Jan 26 16:44:56 2009
New Revision: 666
URL: http://svn.gnome.org/viewvc/gtk-doc?rev=666&view=rev

Log:
	* gtkdoc-mkdb.in:
	* tests/bugs/src/tester.h:
	* tests/fail.sh:
	* tests/fail/docs/tester-docs.xml:
	* tests/fail/docs/tester-sections.txt:
	* tests/fail/src/tester.c:
	  Add public symbols from section file when doing the -undocumented.txt
	  report. Also add the special symbols for the section docs when reading
	  the section-file. Extend test suite to check for it. Fixes #568732



Modified:
   trunk/ChangeLog
   trunk/gtkdoc-mkdb.in
   trunk/tests/bugs/src/tester.h
   trunk/tests/fail.sh
   trunk/tests/fail/docs/tester-docs.xml
   trunk/tests/fail/docs/tester-sections.txt
   trunk/tests/fail/src/tester.c

Modified: trunk/gtkdoc-mkdb.in
==============================================================================
--- trunk/gtkdoc-mkdb.in	(original)
+++ trunk/gtkdoc-mkdb.in	Mon Jan 26 16:44:56 2009
@@ -1043,6 +1043,8 @@
             next;
 
 	} elsif (m/^<FILE>(.*)<\/FILE>/) {
+            $KnownSymbols{"$TMPL_DIR/$1:Long_Description"} = 1;
+            $KnownSymbols{"$TMPL_DIR/$1:Short_Description"} = 1;
             next;
 
 	} elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
@@ -3631,76 +3633,88 @@
 #############################################################################
 
 sub OutputMissingDocumentation {
-     my $n_documented = 0;
-     my $n_incomplete = 0;
-     my $total = 0;
-     my $symbol;
-     my $percent;
-     my $msg;
-     my $buffer = "";
-     my $buffer_deprecated = "";
-     my $buffer_descriptions = "";
-
-     open (UNDOCUMENTED, ">$ROOT_DIR/$MODULE-undocumented.txt")
-          || die "Can't create $ROOT_DIR/$MODULE-undocumented.txt: $!";
-
-     foreach $symbol (sort (keys (%AllSymbols))) {
-          if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also|Stability_Level|Include)/) {
-	      $total++;
-              if (exists ($AllDocumentedSymbols{$symbol})) {
-		  $n_documented++;
-                  if (exists ($AllIncompleteSymbols{$symbol})) {
-                      $n_incomplete++;
-                      $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
-                  }
-	      } elsif (exists $Deprecated{$symbol}) {
-                  if (exists ($AllIncompleteSymbols{$symbol})) {
-                      $n_incomplete++;
-                      $buffer_deprecated .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
-                  } else {
-                      $buffer_deprecated .= $symbol . "\n";
-                  }
-	      } else {
-                  if (exists ($AllIncompleteSymbols{$symbol})) {
-                      $n_incomplete++;
-                      $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
-                  } else {
-                      $buffer .= $symbol . "\n";
-                  }
-	      }
-          } elsif ($symbol =~ /:(Long_Description|Short_Description)/) {
-              $total++;
-              #my $len1=(exists($SymbolDocs{$symbol}))?length($SymbolDocs{$symbol}):-1;
-              #my $len2=(exists($AllDocumentedSymbols{$symbol}))?length($AllDocumentedSymbols{$symbol}):-1;
-              #print "%%%% $symbol : $len1,$len2\n";
-              if (((exists ($SymbolDocs{$symbol})) && (length ($SymbolDocs{$symbol}) > 0))
-              || ((exists ($AllDocumentedSymbols{$symbol})) && (length ($AllDocumentedSymbols{$symbol}) > 0))) {
-                  $n_documented++;
-              } else {
-                  $symbol =~ m/^.*\/(.*)$/;
-                  $buffer_descriptions .= $1 . "\n";
-              }
-          }
-     }
-
-     $buffer .= "\n" . $buffer_deprecated . "\n" . $buffer_descriptions;
-
-     if ($total == 0) {
-	  $percent = 100;
-     } else {
-          $percent = ($n_documented / $total) * 100.0;
-     }
-
-     printf UNDOCUMENTED "%.0f%% symbol docs coverage.\n", $percent;
-     print UNDOCUMENTED "$n_documented symbols documented.\n";
-     print UNDOCUMENTED "$n_incomplete symbols incomplete.\n";
-     print UNDOCUMENTED ($total - $n_documented) . " not documented.\n\n\n";
-
-     print UNDOCUMENTED $buffer;
-
-     close (UNDOCUMENTED);
-
-     printf (("%.0f%% symbol docs coverage ($n_documented symbols documented, $n_incomplete symbols incomplete, " . ($total - $n_documented) . " not documented)\nSee $MODULE-undocumented.txt for a list of missing docs.\nThe doc coverage percentage doesn't include intro sections.\n"), $percent);
+    my $n_documented = 0;
+    my $n_incomplete = 0;
+    my $total = 0;
+    my $symbol;
+    my $percent;
+    my $msg;
+    my $buffer = "";
+    my $buffer_deprecated = "";
+    my $buffer_descriptions = "";
+    
+    open (UNDOCUMENTED, ">$ROOT_DIR/$MODULE-undocumented.txt")
+      || die "Can't create $ROOT_DIR/$MODULE-undocumented.txt: $!";
+    
+    foreach $symbol (sort (keys (%AllSymbols))) {
+        # FIXME: should we print LogWarnings for undocumented stuff?
+        # DEBUG
+        #my $ssfile = &GetSymbolSourceFile($symbol);
+        #my $ssline = &GetSymbolSourceLine($symbol);
+        #my $location = "defined at " . (defined($ssfile)?$ssfile:"?") . ":" . (defined($ssline)?$ssline:"0") . "\n";
+        # DEBUG
+        if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also|Stability_Level|Include|Section_Id)/) {
+            $total++;
+            if (exists ($AllDocumentedSymbols{$symbol})) {
+                $n_documented++;
+                if (exists ($AllIncompleteSymbols{$symbol})) {
+                    $n_incomplete++;
+                    $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
+                    #$buffer .= "\t0: ".$location;
+                }
+            } elsif (exists $Deprecated{$symbol}) {
+                if (exists ($AllIncompleteSymbols{$symbol})) {
+                    $n_incomplete++;
+                    $buffer_deprecated .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
+                    #$buffer .= "\t1a: ".$location;
+                } else {
+                    $buffer_deprecated .= $symbol . "\n";
+                    #$buffer .= "\t1b: ".$location;
+                }
+            } else {
+                if (exists ($AllIncompleteSymbols{$symbol})) {
+                    $n_incomplete++;
+                    $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
+                    #$buffer .= "\t2a: ".$location;
+                } else {
+                    $buffer .= $symbol . "\n";
+                    #$buffer .= "\t2b: ".$location;
+                }
+            }
+        } elsif ($symbol =~ /:(Long_Description|Short_Description)/) {
+            $total++;
+            #my $len1=(exists($SymbolDocs{$symbol}))?length($SymbolDocs{$symbol}):-1;
+            #my $len2=(exists($AllDocumentedSymbols{$symbol}))?length($AllDocumentedSymbols{$symbol}):-1;
+            #print "%%%% $symbol : $len1,$len2\n";
+            if (((exists ($SymbolDocs{$symbol})) && (length ($SymbolDocs{$symbol}) > 0))
+            || ((exists ($AllDocumentedSymbols{$symbol})) && (length ($AllDocumentedSymbols{$symbol}) > 0))) {
+              $n_documented++;
+            } else {
+              # cut off the leading namespace ($TMPL_DIR)
+              $symbol =~ m/^.*\/(.*)$/;
+              $buffer_descriptions .= $1 . "\n";
+            }
+        }
+    }
+    
+    $buffer .= "\n" . $buffer_deprecated . "\n" . $buffer_descriptions;
+    
+    if ($total == 0) {
+      $percent = 100;
+    } else {
+      $percent = ($n_documented / $total) * 100.0;
+    }
+    
+    printf UNDOCUMENTED "%.0f%% symbol docs coverage.\n", $percent;
+    print UNDOCUMENTED "$n_documented symbols documented.\n";
+    print UNDOCUMENTED "$n_incomplete symbols incomplete.\n";
+    print UNDOCUMENTED ($total - $n_documented) . " not documented.\n\n\n";
+    
+    print UNDOCUMENTED $buffer;
+    
+    close (UNDOCUMENTED);
+    
+    printf (("%.0f%% symbol docs coverage ($n_documented symbols documented, $n_incomplete symbols incomplete, " . ($total - $n_documented) . " not documented)\nSee $MODULE-undocumented.txt for a list of missing docs.\nThe doc coverage percentage doesn't include intro sections.\n"), $percent);
 }
 
 
@@ -3774,7 +3788,13 @@
         # filter scanned declarations, with what we suppress from -sections.txt
         my %tmp = ();
         foreach $symbol (keys (%Declarations)) {
-            if ($KnownSymbols{$symbol}) {
+            if (defined($KnownSymbols{$symbol}) && $KnownSymbols{$symbol} == 1) {
+                $tmp{$symbol}=1;
+            }
+        }
+        # , add the rest from -sections.txt
+        foreach $symbol (keys (%KnownSymbols)) {
+            if ($KnownSymbols{$symbol} == 1) {
                 $tmp{$symbol}=1;
             }
         }

Modified: trunk/tests/bugs/src/tester.h
==============================================================================
--- trunk/tests/bugs/src/tester.h	(original)
+++ trunk/tests/bugs/src/tester.h	Mon Jan 26 16:44:56 2009
@@ -157,18 +157,25 @@
  * http://bugzilla.gnome.org/show_bug.cgi?id=544172
  *
  * Returns: result or %NULL.
- **/
+ */
 typedef char const * (*bug_544172) (char const *self);
 
 /** 
  * bug_554833:
  *
  * http://bugzilla.gnome.org/show_bug.cgi?id=554833
- **/
+ */
 struct _bug_554833 {
   int i;
 };
 
+/** 
+ * bug_554833_new:
+ *
+ * http://bugzilla.gnome.org/show_bug.cgi?id=554833
+ *
+ * Returns: result
+ */
 struct _bug_554833 *
                 bug_554833_new (void);
 

Modified: trunk/tests/fail.sh
==============================================================================
--- trunk/tests/fail.sh	(original)
+++ trunk/tests/fail.sh	Mon Jan 26 16:44:56 2009
@@ -12,7 +12,17 @@
 
 # tests
 # check missing section description
-grep >/dev/null "tester:Long_Description" $DOC_MODULE-undocumented.txt
+grep >/dev/null "tester_nodocs:Long_Description" $DOC_MODULE-undocumented.txt
+if test $? = 1 ; then failed=$(($failed + 1)); fi
+tested=$(($tested + 1))
+
+# check missing section long description
+grep >/dev/null "tester_nolongdesc:Long_Description" $DOC_MODULE-undocumented.txt
+if test $? = 1 ; then failed=$(($failed + 1)); fi
+tested=$(($tested + 1))
+
+# check missing section short description
+grep >/dev/null "tester_noshortdesc:Short_Description" $DOC_MODULE-undocumented.txt
 if test $? = 1 ; then failed=$(($failed + 1)); fi
 tested=$(($tested + 1))
 
@@ -20,4 +30,6 @@
 echo "tested : $tested, failed : $failed"
 rate=$((100*($tested - $failed)/$tested));
 echo "$rate %: Checks $tested, Failures: $failed"
-exit `test $failed = 0`;
+
+test $failed = 0
+exit $?

Modified: trunk/tests/fail/docs/tester-docs.xml
==============================================================================
--- trunk/tests/fail/docs/tester-docs.xml	(original)
+++ trunk/tests/fail/docs/tester-docs.xml	Mon Jan 26 16:44:56 2009
@@ -16,7 +16,9 @@
 
   <chapter>
     <title>Tests</title>
-    <xi:include href="xml/tester.xml"/>
+    <xi:include href="xml/tester_nodocs.xml"/>
+    <xi:include href="xml/tester_nolongdesc.xml"/>
+    <xi:include href="xml/tester_noshortdesc.xml"/>
   </chapter>
 
   <index id="api-index">

Modified: trunk/tests/fail/docs/tester-sections.txt
==============================================================================
--- trunk/tests/fail/docs/tester-sections.txt	(original)
+++ trunk/tests/fail/docs/tester-sections.txt	Mon Jan 26 16:44:56 2009
@@ -1,8 +1,22 @@
 <SECTION>
-<FILE>tester</FILE>
-<TITLE>GtkdocTester</TITLE>
+<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>
+

Modified: trunk/tests/fail/src/tester.c
==============================================================================
--- trunk/tests/fail/src/tester.c	(original)
+++ trunk/tests/fail/src/tester.c	Mon Jan 26 16:44:56 2009
@@ -1,7 +1,12 @@
 /**
- * SECTION:tester
+ * SECTION:tester_nolongdesc
  * @short_description: module for gtk-doc unit test
  */
+/**
+ * SECTION:tester_noshortdesc
+ *
+ * This file contains non-sense code for the sole purpose of testing the docs.
+ */
 
 #include <glib.h>