gtk-doc r558 - trunk
- From: stefkost svn gnome org
- To: svn-commits-list gnome org
- Subject: gtk-doc r558 - trunk
- Date: Thu, 17 Apr 2008 14:52:07 +0100 (BST)
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.
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]