Re: gtk-doc 1.4 changes

[Stefan Kost <kost imn htwk-leipzig de>]

hi hi,

attached is a first patch, that does points 1.-3.
I run it over my project and against gstreamer.
There is currently one issue with it, it seems that it does not pick up
incomplete symbols from templstes (another reason to document in the source).
I'll look into this tomorrow and send a refined patch.

Until then, any comments are very welcome ;-)

Stefan

Stefan Kost wrote:
> hi all,
> 
> I volunteer to dedicate the next weekend to do some gtk-doc patches. Please
> comment on the suggestions:
> 
> 1.) currently <INCLUDE> in sections.txt automatically adds '<>' around the
> include file name. I would like to change the behaviou that it does *not* do
> this, when the include file name is enclosed in '""'.
> I need this when documenting the object classes of an application. These
> includes don't get installed and are included as e.g. #include "bt-edit.h"
> 
> 2.) add symbols where members are undocumented to the undocumented file.
> 
> 3.) try to see if I can detect undocumented short and long descriptions. I would
> like to see those listed in the undocumented file as well.
> 
> 4.) a major point on my list is to add the possibillity to get rid of the
> template files. I would really like to add  short and longs descriptions in the
> sources. I do gtk-doc cleanup for gstreamer and there I learned - core
> developers edit code, but not template files :(.
> I repeat the thoughts here:
> We need a syntax for gtk-doc that it can detect that a comment is for the short
> and long-desc. Further Brian expressed the wish to specify things like an
> #define describing an envvar.
> So we need either a prefix and a delimiter
>  * ENVVAR=DISPLAY_ENV_VAR:
>  * SHORT_DESC=CLASSNAME:
> or something that uses a prefix like
>  * DISPLAY_ENV_VAR.ENVVAR:
>  * CLASSNAME.SHORT_DESC:
> or a new keyword like
>  * DISPLAY_ENV_VAR:
>  * Type: Envvar
> 
>  * Classname:
>  * Type: ShortDescription
> 
> Any comments?
> 
> Stefan
> PS.: I'll be away for the next two days, but will answer on friday.

-- 
      \|/            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.481878605 +0100
+++ gtkdoc-mkdb.in	2005-01-15 22:00:14.771409490 +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 &lt;${include}&gt;\n";
+        if ($include =~ m/^\".+\"$/) {
+            $include_output .= "#include ${include}\n";
+        }
+        else {
+            $include_output .= "#include &lt;${include}&gt;\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,6 +2591,7 @@
 
      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;
@@ -2700,8 +2734,14 @@
 			}
 		    }
 
-		    # Output a warning if the parameter is not found.
+		    # Output a warning if the parameter is not found and remember.
 		    if (!$found) {
+                        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.

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