Re: gtk-doc 1.4 changes
- From: Stefan Kost <kost imn htwk-leipzig de>
- To: Matthias Clasen <mclasen redhat com>
- Cc: gtk-doc-list gnome org
- Subject: Re: gtk-doc 1.4 changes
- Date: Sun, 16 Jan 2005 16:14:17 +0100
Hi Matthias,
Matthias Clasen wrote:
> On Sat, 2005-01-15 at 22:46 +0100, Stefan Kost wrote:
>
>> 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";
>
> I think you want $total - $n_documented - $n_incomplete here.
That becomes a matter of view.
$n_documented -> have docs at all
$n_incomplete -> are parts of $n_documented, but the docs neew some update
($total - $n_documented) -> need to be documented at all
attached is a new patch, that finally adds the incomplete docs from templates to
the undocumented.txt file as well.
I am quite happy with the change. This helped my to spot 600! symbols the need
update in the gstreamer API docs. I'd be curious about what happens running this
against glib/gtk - althoughtheir docs are quite nice ;).
Next thing I will look into is the Short/Long Section stuff.
Ciao
Stefan
--
\|/ Stefan Kost
<@ @> private business
+-oOO-(_)-OOo------------------------------------------------------ - - - - -
| __ Address Simildenstr. 5 HTWK Leipzig, Fb IMN, Postfach 301166
| /// 04277 Leipzig 04251 Leipzig
| __ /// Germany Germany
| \\\/// Phone +49341 2253538 +49341 30766101
| \__/ EMail st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
| WWW www.sonicpulse.de www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - - - -
--- gtkdoc-mkdb.in.orig 2005-01-15 19:35:37.000000000 +0100
+++ gtkdoc-mkdb.in 2005-01-16 16:06:27.113462648 +0100
@@ -184,6 +184,7 @@
# all documentation goes in here, so we can do coverage analysis
my %AllSymbols;
+my %AllIncompleteSymbols;
my %AllDocumentedSymbols;
# These global arrays store GtkObject and subclasses and the hierarchy.
@@ -1360,7 +1361,7 @@
# will be overriden by the title in the template file.
# $section_id - the SGML id to use for the toplevel tag.
# $includes - comma-separates list of include files added at top
-# of synopsis, with '<' '>' around them.
+# of synopsis, with '<' '>' around them (if not already enclosed in "").
# $synopsis - reference to the DocBook for the Synopsis part.
# $details - reference to the DocBook for the Details part.
# $signal_synop - reference to the DocBook for the Signal Synopsis part
@@ -1418,7 +1419,12 @@
my $include_output = "";
my $include;
foreach $include (split (/,/, $includes)) {
- $include_output .= "#include <${include}>\n";
+ if ($include =~ m/^\".+\"$/) {
+ $include_output .= "#include ${include}\n";
+ }
+ else {
+ $include_output .= "#include <${include}>\n";
+ }
}
my $old_sgml_file = "$SGML_OUTPUT_DIR/$file.$OUTPUT_FORMAT";
@@ -2524,12 +2530,14 @@
sub OutputMissingDocumentation {
my $n_documented = 0;
+ my $n_incomplete = 0;
my $total = 0;
my $symbol;
my $percent;
my $msg;
my $buffer = "";
- my $buffer2 = "";
+ my $buffer_deprecated = "";
+ my $buffer_descriptions = "";
open (UNDOCUMENTED, ">$ROOT_DIR/$MODULE-undocumented.txt")
|| die "Can't create $ROOT_DIR/$MODULE-undocumented.txt";
@@ -2537,18 +2545,43 @@
foreach $symbol (sort (keys (%AllSymbols))) {
if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also)/) {
$total++;
- if (exists ($AllDocumentedSymbols{$symbol})) {
+ if (exists ($AllDocumentedSymbols{$symbol})) {
$n_documented++;
+ if (exists ($AllIncompleteSymbols{$symbol})) {
+ $n_incomplete++;
+ $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
+ }
} elsif (exists $Deprecated{$symbol}) {
- $buffer2 .= $symbol . "\n";
- }
- else {
- $buffer .= $symbol . "\n";
+ 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" . $buffer2;
+ $buffer .= "\n" . $buffer_deprecated . "\n" . $buffer_descriptions;
if ($total == 0) {
$percent = 100;
@@ -2558,13 +2591,14 @@
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, " . ($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);
+ 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);
}
@@ -2679,6 +2713,9 @@
my $tmpl_param_name = $$tmpl_params[$j];
my $tmpl_param_desc = $$tmpl_params[$j + 1];
+ chomp($tmpl_param_desc);
+ $tmpl_param_desc =~ s/^\s*(.*)\s*$/$1/;
+
# Try to find the param in the source comment documentation.
my $found = 0;
my $k;
@@ -2700,8 +2737,15 @@
}
}
- # Output a warning if the parameter is not found.
- if (!$found) {
+ # Output a warning if the parameter is not found or docs are
+ # empty. Remember for stats.
+ if ((!$found) || (length ($tmpl_param_desc) == 0)) {
+ if (exists ($AllIncompleteSymbols{$symbol})) {
+ $AllIncompleteSymbols{$symbol}.=", ".$tmpl_param_name;
+ }
+ else {
+ $AllIncompleteSymbols{$symbol}=$tmpl_param_name;
+ }
print <<EOF;
WARNING: $item description missing in source code comment block -
$type: $symbol $item: $tmpl_param_name.
@@ -3026,6 +3070,7 @@
}
}
$SymbolParams{$current_symbol} = [ @params ];
+ #print "#### Found params for symbol : '$current_symbol'= " . @params . "\n";
} else {
# Delete any existing params in case we are overriding a
# previously read template.
@@ -3050,25 +3095,25 @@
next;
} else {
- # Check if param found
- if (s/^\@(\S+):\040?//) {
- my $param_name = $1;
- # Allow variations of 'Returns'
- if ($param_name =~ m/^[Rr]eturns?$/) {
- $param_name = "Returns";
- }
-# print "Found param: $param_name\n";
- push (@params, $param_name);
- push (@params, $_);
- $current_param += 2;
- next;
- }
-
- if ($current_param >= 0) {
- $params[$current_param] .= $_;
- } else {
- $symbol_doc .= $_;
- }
+ # Check if param found
+ if (s/^\@(\S+):\040?//) {
+ my $param_name = $1;
+
+ # Allow variations of 'Returns'
+ if ($param_name =~ m/^[Rr]eturns?$/) {
+ $param_name = "Returns";
+ }
+ #print "^^^^ Found param for symbol $current_symbol : '$param_name'= '$_'\n";
+ push (@params, $param_name);
+ push (@params, $_);
+ $current_param += 2;
+ next;
+ }
+ if ($current_param >= 0) {
+ $params[$current_param] .= $_;
+ } else {
+ $symbol_doc .= $_;
+ }
}
}
begin:vcard
fn:Stefan Kost
n:Kost;Stefan
org:HTWK Leipzig;FB. IMN
adr:;;Postfach 301166;Leipzig;;04251;Germany
email;internet:kost imn htwk-leipzig de
title:Dipl. Informatiker
tel;work:+49341 30766440
tel;home:+49341 2253538
tel;cell:+49178 3183742
x-mozilla-html:FALSE
url:http://www.imn.htwk-leipzig.de/~kost/about.html
version:2.1
end:vcard
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
