Documentation coverage patch.

[Joakim Ziegler <joakim ximian com>]

As requested by Chema and others, we need a way to track the coverage of
embedded API documentation, and put that on a web page. The first step
towards that is this patch for gtk-doc, which adds two output files, one a
list of the undocumented functions and macros in the module, and the other
containing the counts and percentages. It's based on a patch HP sent me.

Please review this patch and tell me if it's ok to commit. gtk-doc doesn't
have a HACKING file, and Owen suggested I send it here for review.

-- 
   Joakim Ziegler - Ximian Web Monkey - joakim ximian com - Radagast IRC
 FIX sysop - Free Software Coder - Writer - FIDEL & Conglomerate developer
http://www.avmaria.com/ - http://www.ximian.com/ - http://www.sinthetic.org/

Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.23
diff -u -5 -r1.23 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in	2001/03/26 21:27:14	1.23
+++ gtkdoc-mkdb.in	2001/05/03 01:57:50
@@ -101,10 +101,14 @@
 
 # These global hashes store documentation scanned from the source files.
 my %SourceSymbolDocs;
 my %SourceSymbolParams;
 
+# all documentation goes in here, so we can do coverage analysis
+my %AllSymbols;
+my %AllDocumentedSymbols;
+
 # These global arrays store GtkObject and subclasses and the hierarchy.
 my @Objects;
 my @ObjectLevels;
 
 
@@ -252,10 +256,12 @@
 	    # We don't want warnings if object & class structs aren't used.
 	    $DeclarationOutput{$title} = 1;
 	    $DeclarationOutput{"${title}Class"} = 1;
 
 	} elsif (m/^<FILE>(.*)<\/FILE>/) {
+            my $sym;
+
 	    $file = $1;
 	    %SymbolDocs = ();
 	    %SymbolTypes = ();
 	    %SymbolParams = ();
 	    &ReadTemplateFile ("$TMPL_DIR/$file.sgml", 1);
@@ -328,10 +334,13 @@
 	    $num_symbols++;
 	}
     }
     close (INPUT);
 
+    &OutputMissingDocumentation;
+    &OutputAllSymbols;
+
     return $changed;
 }
 
 
 #############################################################################
@@ -1656,12 +1665,85 @@
 	}
     }
     close (SRCFILE);
 }
 
+#############################################################################
+# Function    : OutputMissingDocumentation
+# Description : Outputs report of documentation coverage to a file
+#
+# Arguments   : none
+#############################################################################
 
+sub OutputMissingDocumentation {
+     my $n_documented = 0;
+     my $total = 0;
+     my $symbol;
+     my $percent;
+     my $msg;
+
+     open (UNDOCUMENTED, ">$ROOT_DIR/$MODULE-undocumented.txt")
+          || die "Can't create $ROOT_DIR/$MODULE-undocumented.txt";
+
+     open (DOC_PERCENTAGE, ">$ROOT_DIR/$MODULE-doc_percentage.txt")
+          || die "Can't create $ROOT_DIR/$MODULE-doc_percentage.txt";
+
+     foreach $symbol (sort (keys (%AllSymbols))) {
+          if (defined ($Declarations{$symbol})) {
+               my $type = $DeclarationTypes{$symbol};
+               if (($type eq 'FUNCTION') or ($type eq 'MACRO')) {
+                    $total++;
+                    if (exists ($AllDocumentedSymbols{$symbol})) {
+                         $n_documented++;
+                    } else {
+                         print UNDOCUMENTED $symbol . "\n"
+                    }
+               } elsif ($type eq 'STRUCT') {
+               }
+          }
+     }
+
+     close (UNDOCUMENTED);
+     
+     $percent = ($n_documented / $total) * 100.0;
+
+     printf DOC_PERCENTAGE "%.2g%% function docs coverage.\n", $percent;
+     print DOC_PERCENTAGE "$n_documented functions documented.\n";
+     print DOC_PERCENTAGE ($total - $n_documented) . " not documented.\n";
+
+     close (DOC_PERCENTAGE);
+
+     printf (("%.2g%% function docs coverage ($n_documented functions documented, " . ($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);
+}
+
+
 #############################################################################
+# Function    : OutputAllSymbols
+# Description : Outputs list of all symbols to a file
+#
+# Arguments   : none
+#############################################################################
+
+sub OutputAllSymbols {
+     my $n_documented = 0;
+     my $total = 0;
+     my $symbol;
+     my $percent;
+     my $msg;
+
+     open (SYMBOLS, ">$ROOT_DIR/$MODULE-symbols.txt")
+          || die "Can't create $ROOT_DIR/$MODULE-symbols.txt";
+
+     foreach $symbol (sort (keys (%AllSymbols))) {
+          print SYMBOLS $symbol . "\n"
+     }
+
+     close (SYMBOLS);
+}
+
+
+#############################################################################
 # Function    : MergeSourceDocumentation
 # Description : This merges documentation read from a source file into the
 #		documentation read in from a template file.
 #		
 #		Parameter descriptions override any in the template files.
@@ -1672,17 +1754,22 @@
 #############################################################################
 
 sub MergeSourceDocumentation {
     my $symbol;
     foreach $symbol (keys (%SymbolDocs)) {
+        $AllSymbols{$symbol} = 1;
 	if (exists ($SourceSymbolDocs{$symbol})) {
 	    my $src_doc = $SourceSymbolDocs{$symbol};
 	    my $tmpl_doc = $SymbolDocs{$symbol};
 	    $tmpl_doc = defined ($tmpl_doc) ? $tmpl_doc : "";
 	    $src_doc =~ s/^\s+//;
 	    $src_doc =~ s/\s+$//;
 
+            if ($src_doc ne "") {
+                 $AllDocumentedSymbols{$symbol} = 1;
+            }
+
 	    # Convert special SGML characters. I'm not sure if we want to do
 	    # this but currently there are a couple of '&'s in the source code
 	    # comment blocks which mess up the HTML output badly.
 	    $src_doc = &CreateValidSGML ($src_doc);
 
@@ -1744,12 +1831,21 @@
 WARNING: Parameter described in source code comment block but does not exist -
          Func: $symbol Param: $param_name.
 EOF
 		}
 	    }
-	}
-    }
+       } else {
+            ## See if the symbol is documented out-of-line
+	    my $tmpl_doc = $SymbolDocs{$symbol};
+	    $tmpl_doc = defined ($tmpl_doc) ? $tmpl_doc : "";
+            $tmpl_doc =~ s/<\/?[a-z]+>//g;
+            $tmpl_doc =~ s/\s//g;
+            if ($tmpl_doc ne "") {
+                 $AllDocumentedSymbols{$symbol} = 1;
+            }
+       }
+   }
 }
 
 
 #############################################################################
 # LIBRARY FUNCTIONS -	These functions are used in both gtkdoc-mkdb and
Index: gtkdoc-scan.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-scan.in,v
retrieving revision 1.16
diff -u -5 -r1.16 gtkdoc-scan.in
--- gtkdoc-scan.in	2001/03/03 22:51:38	1.16
+++ gtkdoc-scan.in	2001/05/03 01:57:58
@@ -129,11 +129,11 @@
     
     opendir (SRCDIR, $source_dir)
 	|| die "Can't open source directory $source_dir: $!";
     my $file;
     foreach $file (readdir (SRCDIR)) {
-	if ($file eq '.' || $file eq '..') {
+	if ($file eq '.' || $file eq '..' || $file =~ /^\./) {
 	    next;
 	} elsif (-d "$source_dir/$file") {
 	    push (@subdirs, $file);
 	} elsif ($file =~ m/\.h$/) {
 	    &ScanHeader ("$source_dir/$file", $object_list, $main_list);