possible patches

[Havoc Pennington <hp redhat com>]

Hi,

My current gtk-doc is hacked up a bit, three changes:
 
 - print a message on what percent of symbols are documented,
   and write a file module-undocumented.txt listing the work 
   you have left to do
 - avoid scanning dotfiles
 - print module-symbols.txt with the list of all symbols in the 
   module (this is kind of a bad/useless feature I think, I 
   was using it to make the GTK deprecation list)

Patch appended. The first two changes are maybe worth making.

Havoc

Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/gtk-doc/ChangeLog,v
retrieving revision 1.48
diff -u -u -r1.48 ChangeLog
--- ChangeLog	2000/12/10 16:39:58	1.48
+++ ChangeLog	2000/12/11 18:13:43
@@ -1,3 +1,13 @@
+2000-11-20  Havoc Pennington  <hp redhat com>
+
+	* gtkdoc-mkdb.in (MergeSourceDocumentation): Keep track of which
+	symbols are documented and which aren't
+	(OutputMissingDocumentation): print message about completeness
+	percentage, and write MODULE-undocumented.txt file listing 
+	undocumented symbols
+	(OutputAllSymbols): write MODULE-symbols.txt file with all the 
+	symbols known to gtk-doc
+
 2000-12-10  Damon Chaplin  <damon helixcode com>
 
 	* gtk-doc.spec.in: added spec.in file from John Gotts
Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.18
diff -u -u -r1.18 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in	2000/11/03 07:01:50	1.18
+++ gtkdoc-mkdb.in	2000/12/11 18:13:43
@@ -91,6 +91,10 @@
 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;
@@ -227,6 +231,8 @@
 	    $DeclarationOutput{"${title}Class"} = 1;
 
 	} elsif (m/^<FILE>(.*)<\/FILE>/) {
+            my $sym;
+
 	    $file = $1;
 	    %SymbolDocs = ();
 	    %SymbolTypes = ();
@@ -300,6 +306,8 @@
     close (INPUT);
 
     &OutputBook ($book_top, $book_bottom);
+    &OutputMissingDocumentation;
+    &OutputAllSymbols;
 }
 
 
@@ -1570,6 +1578,70 @@
     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";
+
+     foreach $symbol (sort (keys (%AllSymbols))) {
+          if (defined ($Declarations{$symbol})) {
+               my $type = $DeclarationTypes{$symbol};
+               if ($type eq 'FUNCTION') {
+                    $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 (("%.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 and non-functions.\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
@@ -1586,6 +1658,7 @@
 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};
@@ -1593,6 +1666,10 @@
 	    $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.
@@ -1658,8 +1735,17 @@
 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;
+            }
+       }
+   }
 }
 
 
Index: gtkdoc-scan.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-scan.in,v
retrieving revision 1.10
diff -u -u -r1.10 gtkdoc-scan.in
--- gtkdoc-scan.in	2000/10/06 22:00:13	1.10
+++ gtkdoc-scan.in	2000/12/11 18:13:43
@@ -114,7 +114,7 @@
 	|| 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);
@@ -128,6 +128,7 @@
     my $dir;
     foreach $dir (@subdirs) {
 	next if ($IGNORE_HEADERS =~ m/\b\Q${dir}\E\b/);
+        next if ($dir =~ /^\./);
 	&ScanHeaders ("$source_dir/$dir", $object_list, $main_list);
     }
 }