gtk-doc r558 - trunk

[stefkost svn gnome org]

Author: stefkost
Date: Thu Apr 17 14:51:58 2008
New Revision: 558
URL: http://svn.gnome.org/viewvc/gtk-doc?rev=558&view=rev

Log:
	* gtkdoc-mkdb.in:
	  Add one more warning. Also trac location of section docs. Merge
	  source symbols once and then on demand (if we read a template).



Modified:
   trunk/ChangeLog
   trunk/gtkdoc-mkdb.in

Modified: trunk/gtkdoc-mkdb.in
==============================================================================
--- trunk/gtkdoc-mkdb.in	(original)
+++ trunk/gtkdoc-mkdb.in	Thu Apr 17 14:51:58 2008
@@ -377,8 +377,12 @@
     my $implementations = "";
     my $prerequisites = "";
     my $derived = "";
+    my $have_tmpl = 0;
     my @file_objects = ();
 
+    # merge the source docs, in case there are no templates
+    &MergeSourceDocumentation;
+
     while (<INPUT>) {
 	if (m/^#/) {
 	    next;
@@ -388,6 +392,7 @@
 	    $details = "";
 	    $num_symbols = 0;
 	    $in_section = 1;
+	    $have_tmpl = 0;
 	    @file_objects = ();
 
 	} elsif (m/^<SUBSECTION\s*(.*)>/i) {
@@ -408,12 +413,7 @@
             my $sym;
 
 	    $filename = $1;
-	    %SymbolDocs = ();
-	    %SymbolTypes = ();
-	    %SymbolParams = ();
-	    if (&ReadTemplateFile ("$TMPL_DIR/$filename", 1) == 1) {
-                &MergeSourceDocumentation;
-            }
+	    $have_tmpl = &ReadTemplateFile ("$TMPL_DIR/$filename", 1);
 
 	} elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
 	    if ($in_section) {
@@ -428,9 +428,16 @@
 	    }
 
 	} elsif (m/^<\/SECTION>/) {
+	    if($title eq "" && $filename eq "") {
+                &LogWarning ($file, $., "Section has no title and no file.");
+	    }
+	    # FIXME: one of those would be enough
 	    if ($title eq "") {
 		$title = $filename;
 	    }
+	    if ($filename eq "") {
+		$filename = $title;
+	    }
 	    #print "End of section: $title\n";
 
 	    $filename =~ s/\s/_/g;
@@ -598,8 +605,11 @@
 EOF
 		}
 
-                 $synopsis =~ s/^\n*//g;
-                 $synopsis =~ s/\n+$/\n/g;
+		$synopsis =~ s/^\n*//g;
+		$synopsis =~ s/\n+$/\n/g;
+		if ($have_tmpl) {
+		    &MergeSourceDocumentation;
+		}
 		my $file_changed = &OutputSGMLFile ($filename, $title, $section_id,
 						    $section_includes,
 						    \$synopsis, \$details,
@@ -680,9 +690,6 @@
 	}
     }
     close (INPUT);
-    
-    # if there were no templates, merge the source docs
-    &MergeSourceDocumentation;
 
     &OutputMissingDocumentation;
     &OutputUndeclaredSymbols;
@@ -1570,6 +1577,8 @@
 sub OutputSGMLFile {
     my ($file, $title, $section_id, $includes, $synopsis, $details, $signals_synop, $signals_desc, $args_synop, $args_desc, $hierarchy, $interfaces, $implementations, $prerequisites, $derived, $file_objects) = @_;
 
+    #print "Output sgml for file $file with title '$title'\n";
+    
     # The edited title overrides the one from the sections file.
     my $new_title = $SymbolDocs{"$TMPL_DIR/$file:Title"};
     if (defined ($new_title) && $new_title !~ m/^\s*$/) {
@@ -1586,7 +1595,7 @@
     }
     my $long_desc = $SymbolDocs{"$TMPL_DIR/$file:Long_Description"};
     if (!defined ($long_desc) || $long_desc =~ m/^\s*$/) {
-	$long_desc = "<para>\nA longer description goes here.\n</para>\n";
+	$long_desc = "";
     } else {
 	$long_desc = &ExpandAbbreviations("$title:Long_description",
 					  $long_desc);
@@ -2938,27 +2947,36 @@
                 if ($symbol =~ m/SECTION:\s*(.*)/) {
                     my $real_symbol=$1;
                     my $k;
+                    my $key;
 
                     #print "SECTION DOCS found in source for : '$real_symbol'\n";
                     $ignore_broken_returns = 1;
                     for ($k = 0; $k <= $#params; $k += 2) {
                         #print "   '".$params[$k]."'\n";
-		        $params[$k] = "\L$params[$k]";
+                        $params[$k] = "\L$params[$k]";
+                        undef $key;
                         if ($params[$k] eq "short_description") {
-                            $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Short_Description"}=$params[$k+1];
+                            $key = "$TMPL_DIR/$real_symbol:Short_Description";
                         } elsif ($params[$k] eq "see_also") {
-                            $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:See_Also"}=$params[$k+1];
+                            $key = "$TMPL_DIR/$real_symbol:See_Also";
                         } elsif ($params[$k] eq "title") {
-                            $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Title"}=$params[$k+1];
+                            $key = "$TMPL_DIR/$real_symbol:Title";
                         } elsif ($params[$k] eq "stability") {
-                            $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Stability_Level"}=$params[$k+1];
+                            $key = "$TMPL_DIR/$real_symbol:Stability_Level";
                         } elsif ($params[$k] eq "section_id") {
-                            $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Section_Id"}=$params[$k+1];
+                            $key = "$TMPL_DIR/$real_symbol:Section_Id";
                         } elsif ($params[$k] eq "include") {
-                            $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Include"}=$params[$k+1];
+                            $key = "$TMPL_DIR/$real_symbol:Include";
+                        }
+                        if (defined($key)) {
+                            $SourceSymbolDocs{$key}=$params[$k+1];
+                            $SourceSymbolSourceFile{$key} = $file;
+                            $SourceSymbolSourceLine{$key} = $.;
                         }
                     }
                     $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Long_Description"}=$description;
+                    $SourceSymbolSourceFile{"$TMPL_DIR/$real_symbol:Long_Description"} = $file;
+                    $SourceSymbolSourceLine{"$TMPL_DIR/$real_symbol:Long_Description"} = $.;
                     #$SourceSymbolTypes{$symbol} = "SECTION";
                 } else {
                     #print "SYMBOL DOCS found in source for : '$symbol' ",length($description), "\n";
@@ -3384,10 +3402,11 @@
 
     if (scalar %SymbolDocs) {
         @Symbols=keys (%SymbolDocs);
+        #print "num existing entries: ".(scalar @Symbols)."\n";
     }
     else {
         # filter scanned declarations, with what we suppress from -sections.txt
-        my %tmp;
+        my %tmp = ();
         foreach $symbol (keys (%Declarations)) {
             if ($KnownSymbols{$symbol}) {
                 $tmp{$symbol}=1;
@@ -3398,7 +3417,7 @@
             $tmp{$symbol}=1;
         }
         @Symbols = keys (%tmp);       
-        #print "num entries: ".(scalar @Symbols)."\n";
+        #print "num source entries: ".(scalar @Symbols)."\n";
     }
     foreach $symbol (@Symbols) {        
         $AllSymbols{$symbol} = 1;
@@ -3415,11 +3434,10 @@
             #print "## [$tmpl_doc]\n";
 	}
 
-	#print "merging $symbol\n";
+	#print "merging [$symbol]\n";
 
 	if (exists ($SourceSymbolDocs{$symbol})) {
 	    my $src_doc = $SourceSymbolDocs{$symbol};
-	    my $tmpl_doc = $SymbolDocs{$symbol};
 	    my $type = $DeclarationTypes {$symbol};
 
             #print "... from source\n";
@@ -3442,8 +3460,8 @@
 	    $src_doc =~ s/\s+$//;
 
 	    # Don't output warnings for overridden titles as titles are
-	    # automatically generated in the -sections.txt file so are often
-	    # overridden.
+	    # automatically generated in the -sections.txt file, and thus they
+	    # are often overridden.
 	    if ($have_tmpl_docs && $symbol !~ m/:Title$/) {
                 &LogWarning ($SourceSymbolSourceFile{$symbol}, $SourceSymbolSourceLine{$symbol},
                     "Documentation in template ".$SymbolSourceFile{$symbol}.":".$SymbolSourceLine{$symbol}." for $symbol being overridden by inline comments.");
@@ -3461,8 +3479,7 @@
 	    $src_doc = &ConvertBlankLines ($src_doc, $symbol);
 
             if ($symbol =~ m/$TMPL_DIR\/.+:Long_Description/) {
-                # FIXME: should we check for empty $tmpl_doc ?
-                $SymbolDocs{$symbol} = "<para>\n$src_doc</para>\n$tmpl_doc"
+                $SymbolDocs{$symbol} = "<para>\n$src_doc</para>\n$tmpl_doc";
             } elsif ($symbol =~ m/$TMPL_DIR\/.+:.+/) {
                 # For the title/summary/see also section docs we don't want to
 	        # add any <para> tags.
@@ -3550,8 +3567,9 @@
                 #print "... undocumented\n";
             }
         }
-        # if this symbol is documented, check if docs are complete
-        $tmpl_doc = $SymbolDocs{$symbol};
+
+	# if this symbol is documented, check if docs are complete
+	$tmpl_doc = $SymbolDocs{$symbol};
 	$tmpl_doc = defined ($tmpl_doc) ? $tmpl_doc : "";
 	$tmpl_doc =~ s/<\/?[a-z]+>//g;
 	$tmpl_doc =~ s/\s//g;
@@ -3594,6 +3612,7 @@
             }
         }
    }
+   #print "num doc entries: ".(scalar %SymbolDocs)."\n";
 }
 
 sub IsEmptyDoc {
@@ -3868,6 +3887,12 @@
 	return 0;
     }
 
+    # start with empty hashes, we merge the source comment for each file
+    # afterwards
+    %SymbolDocs = ();
+    %SymbolTypes = ();
+    %SymbolParams = ();
+
     my $current_type = "";	# Type of symbol being read.
     my $current_symbol = "";	# Name of symbol being read.
     my $symbol_doc = "";		# Description of symbol being read.