Re: Documentation coverage patch.
- From: Joakim Ziegler <joakim ximian com>
- To: gtk-doc-list gnome org
- Subject: Re: Documentation coverage patch.
- Date: Thu, 3 May 2001 18:48:21 -0600
On Thu, May 03, 2001 at 07:38:02PM -0400, Damon Chaplin wrote:
> Joakim Ziegler wrote:
>>> I'd prefer it if it didn't output $MODULE-symbols.txt by default, unless
>>> there is a good reason. Maybe add a command-line option for that.
>> The only good reason I can see is that this is intended to be run
>> automatically on the web server to generate a web page with the overview.
>> This means it's run from the makefiles, which again means that every module
>> that we monitor in this way needs to have its makefiles patched to support
>> this option (unless I'm missing something fundamental here). That makes
>> deploying this page a lot more work. I don't know if that's a convincing
>> arugment or not.
> $MODULE-symbols.txt is just a long list of symbols, though, isn't it?
> What was the web server going to do with them?
Here's a new patch, which outputs both the percentages and the undocumented
symbols list to $MODULE-undocumented.txt, and takes the option
--outputallsymbols to output $MODULE-symbols.txt.
Let me know if it's ok to apply.
--
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/04 00:44:02
@@ -41,17 +41,19 @@
my $MODULE;
my $TMPL_DIR;
my $SGML_OUTPUT_DIR;
my @SOURCE_DIRS;
my $PRINT_VERSION;
+my $OUTPUT_ALL_SYMBOLS;
my %optctl = (module => \$MODULE,
'source-dir' => \ SOURCE_DIRS,
'output-dir' => \$SGML_OUTPUT_DIR,
'tmpl-dir' => \$TMPL_DIR,
- 'version' => \$PRINT_VERSION);
-GetOptions(\%optctl, "module=s", "source-dir:s", "output-dir:s", "version");
+ 'version' => \$PRINT_VERSION,
+ 'outputallsymbols' => \$OUTPUT_ALL_SYMBOLS);
+GetOptions(\%optctl, "module=s", "source-dir:s", "output-dir:s", "version", "outputallsymbols");
if ($PRINT_VERSION) {
print "@VERSION \n";
exit 0;
}
@@ -101,10 +103,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 +258,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 +336,16 @@
$num_symbols++;
}
}
close (INPUT);
+ &OutputMissingDocumentation;
+
+ if ($OUTPUT_ALL_SYMBOLS) {
+ &OutputAllSymbols;
+ }
+
return $changed;
}
#############################################################################
@@ -1656,10 +1670,82 @@
}
}
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;
+ my $buffer;
+
+ 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') or ($type eq 'MACRO')) {
+ $total++;
+ if (exists ($AllDocumentedSymbols{$symbol})) {
+ $n_documented++;
+ } else {
+ $buffer .= $symbol . "\n";
+ }
+ } elsif ($type eq 'STRUCT') {
+ }
+ }
+ }
+
+
+ $percent = ($n_documented / $total) * 100.0;
+
+ printf UNDOCUMENTED "%.2g%% function docs coverage.\n", $percent;
+ print UNDOCUMENTED "$n_documented functions documented.\n";
+ print UNDOCUMENTED ($total - $n_documented) . " not documented.\n\n\n";
+
+ print UNDOCUMENTED $buffer;
+
+ close (UNDOCUMENTED);
+
+ 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.
@@ -1672,17 +1758,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 +1835,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/04 00:44:03
@@ -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);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
