[gtk-doc] mkdb: track incomplete docs in tmpl-free build too. Fixes 568711
- From: Stefan Kost <stefkost src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [gtk-doc] mkdb: track incomplete docs in tmpl-free build too. Fixes 568711
- Date: Sat, 26 Dec 2009 22:37:52 +0000 (UTC)
commit 08be8c069a717279f80357df2959a7195728b0b2
Author: Stefan Kost <ensonic users sf net>
Date: Sun Dec 27 00:30:33 2009 +0200
mkdb: track incomplete docs in tmpl-free build too. Fixes 568711
We reparse the structs/unions/enums for doc output anyway. Use that info to
check if all fields/values have docs.
gtkdoc-common.pl.in | 14 ++--
gtkdoc-mkdb.in | 201 ++++++++++++++++++++++++++++++++++-----------------
2 files changed, 140 insertions(+), 75 deletions(-)
---
diff --git a/gtkdoc-common.pl.in b/gtkdoc-common.pl.in
index 04571b5..8364e8e 100644
--- a/gtkdoc-common.pl.in
+++ b/gtkdoc-common.pl.in
@@ -111,9 +111,7 @@ sub ParseStructDeclaration {
}
# Assume end of declaration if line begins with '}'
- $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/
- .*?
- (?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx;
+ $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx;
# Remove all other comments;
$declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g;
@@ -124,10 +122,12 @@ sub ParseStructDeclaration {
return @result;
}
- # Prime match after "struct {" declaration
+ # Prime match after "struct/union {" declaration
if (!scalar($declaration =~ m/(?:struct|union)\s+\w*\s*\{/msg)) {
- die "Structure declaration '$declaration' does not begin with struct [NAME] {\n";
+ die "Declaration '$declaration' does not begin with struct/union [NAME] {\n";
}
+
+ #print "DEBUG: public fields in struct/union: $declaration\n";
# Treat lines in sequence, allowing singly nested anonymous structs
# and unions.
@@ -141,7 +141,7 @@ sub ParseStructDeclaration {
# ignore preprocessor directives
while ($line =~ /^#.*?\n\s*(.*)/msg) {
- $line=$1;
+ $line=$1;
}
last if $line =~ /^\s*\}\s*\w*\s*$/;
@@ -228,7 +228,7 @@ sub ParseStructDeclaration {
}
} else {
- warn "Cannot parse structure field \"$line\"";
+ print "WARNING: Cannot parse structure field: \"$line\"\n";
}
}
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index de33d18..a52af36 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -1011,7 +1011,7 @@ sub OutputSinceIndexes {
foreach my $version (@sinces) {
#print "Since : [$version]\n";
- # todo make filtered hash
+ # TODO make filtered hash
#my %index = grep { $Since{$_} eq $version } %IndexEntriesSince;
my %index = map { $_ => $IndexEntriesSince{$_} } grep { $Since{$_} eq $version } keys %IndexEntriesSince;
@@ -1521,8 +1521,9 @@ sub OutputStruct {
if ($found) {
my %field_descrs = @$params;
+ my $missing_parameters = "";
- $desc .= <<EOF;
+ $desc .= <<EOF;
<variablelist role="struct">
EOF
while (@fields) {
@@ -1537,13 +1538,34 @@ EOF
$field_descr = &ExpandAbbreviations($symbol, $field_descr);
$desc .= "<listitem><simpara>$field_descr$param_annotations</simpara></listitem>\n";
} else {
- $desc .= "<listitem><simpara /></listitem>\n";
+ &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
+ "Field description for $symbol"."::"."$field_name is missing in source code comment block.");
+ if ($missing_parameters ne "") {
+ $missing_parameters .= ", ".$field_name;
+ } else {
+ $missing_parameters = $field_name;
+ }
+ $desc .= "<listitem />\n";
}
$desc .= "</varlistentry>\n";
}
-
$desc .= "</variablelist>";
+
+ # remember missing parameters (needed in tmpl-free build)
+ if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) {
+ $AllIncompleteSymbols{$symbol}=$missing_parameters;
+ }
+ }
+ else {
+ if (scalar(@fields) > 0) {
+ if (! exists ($AllIncompleteSymbols{$symbol})) {
+ $AllIncompleteSymbols{$symbol}="<items>";
+ &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
+ "Field descriptions for $symbol are missing in source code comment block.");
+ }
+ }
}
+
$desc .= OutputSymbolTraits ($symbol);
$desc .= "</refsect2>\n";
return ($synop, $desc);
@@ -1551,23 +1573,39 @@ EOF
#############################################################################
-# Function : OutputEnum
-# Description : Returns the synopsis and detailed description of a enum.
-# Arguments : $symbol - the enum.
-# $declaration - the declaration of the enum.
+# Function : OutputUnion
+# Description : Returns the synopsis and detailed description of a union.
+# Arguments : $symbol - the union.
+# $declaration - the declaration of the union.
#############################################################################
-sub OutputEnum {
+sub OutputUnion {
my ($symbol, $declaration) = @_;
my $id = &CreateValidSGMLID ($symbol);
my $condition = &MakeConditionDescription ($symbol);
- my $synop = &MakeReturnField("enum") . "<link linkend=\"$id\">$symbol</link>;\n";
- my $desc = "<refsect2 id=\"$id\" role=\"enum\"$condition>\n<title>enum $symbol</title>\n";
+
+ # Determine if it is a simple struct or it also has a typedef.
+ my $has_typedef = 0;
+ if ($StructHasTypedef{$symbol} || $declaration =~ m/^\s*typedef\s+/) {
+ $has_typedef = 1;
+ }
+
+ my $synop;
+ my $desc;
+ if ($has_typedef) {
+ # For unions with typedefs we just output the union name.
+ $synop = &MakeReturnField("") . "<link linkend=\"$id\">$symbol</link>;\n";
+ $desc = "<refsect2 id=\"$id\" role=\"union\"$condition>\n<title>$symbol</title>\n";
+ } else {
+ $synop = &MakeReturnField("union") . "<link linkend=\"$id\">$symbol</link>;\n";
+ $desc = "<refsect2 id=\"$id\" role=\"union\"$condition>\n<title>union $symbol</title>\n";
+ }
$desc .= MakeIndexterms($symbol, $id);
$desc .= "\n";
$desc .= OutputSymbolExtraLinks($symbol);
+ # FIXME: we do more for structs
my $decl_out = &CreateValidSGML ($declaration);
$desc .= "<programlisting>$decl_out</programlisting>\n";
@@ -1579,7 +1617,14 @@ sub OutputEnum {
# Create a table of fields and descriptions
- my @members = ParseEnumDeclaration($declaration);
+ # FIXME: Inserting  's into the produced type declarations here would
+ # improve the output in most situations ... except for function
+ # members of structs!
+ my @fields = ParseStructDeclaration($declaration, 0,
+ 0, \&MakeXRef,
+ sub {
+ "<structfield id=\"".&CreateValidSGMLID("$id.$_[0]")."\">$_[0]</structfield>";
+ });
my $params = $SymbolParams{$symbol};
# If no parameters are filled in, we don't generate the description
@@ -1596,29 +1641,50 @@ sub OutputEnum {
}
if ($found) {
- my %member_descrs = @$params;
+ my %field_descrs = @$params;
+ my $missing_parameters = "";
- $desc .= <<EOF;
-<variablelist role="enum">
+ $desc .= <<EOF;
+<variablelist role="union">
EOF
- for my $member_name (@members) {
- my $member_descr = $member_descrs{$member_name};
+ while (@fields) {
+ my $field_name = shift @fields;
+ my $text = shift @fields;
+ my $field_descr = $field_descrs{$field_name};
my $param_annotations = "";
- $id = &CreateValidSGMLID ($member_name);
- $condition = &MakeConditionDescription ($member_name);
- $desc .= "<varlistentry id=\"$id\" role=\"constant\"$condition>\n<term><literal>$member_name</literal></term>\n";
- if (defined $member_descr) {
- ($member_descr,$param_annotations) = &ExpandAnnotation($symbol, $member_descr);
- $member_descr = &ExpandAbbreviations($symbol, $member_descr);
- $desc .= "<listitem><simpara>$member_descr$param_annotations</simpara></listitem>\n";
+ $desc .= "<varlistentry><term>$text</term>\n";
+ if (defined $field_descr) {
+ ($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr);
+ $field_descr = &ExpandAbbreviations($symbol, $field_descr);
+ $desc .= "<listitem><simpara>$field_descr$param_annotations</simpara></listitem>\n";
} else {
- $desc .= "<listitem></listitem>\n";
+ &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
+ "Field description for $symbol"."::"."$field_name is missing in source code comment block.");
+ if ($missing_parameters ne "") {
+ $missing_parameters .= ", ".$field_name;
+ } else {
+ $missing_parameters = $field_name;
+ }
+ $desc .= "<listitem />\n";
}
$desc .= "</varlistentry>\n";
}
-
$desc .= "</variablelist>";
+
+ # remember missing parameters (needed in tmpl-free build)
+ if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) {
+ $AllIncompleteSymbols{$symbol}=$missing_parameters;
+ }
+ }
+ else {
+ if (scalar(@fields) > 0) {
+ if (! exists ($AllIncompleteSymbols{$symbol})) {
+ $AllIncompleteSymbols{$symbol}="<items>";
+ &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
+ "Field descriptions for $symbol are missing in source code comment block.");
+ }
+ }
}
$desc .= OutputSymbolTraits ($symbol);
@@ -1628,39 +1694,23 @@ EOF
#############################################################################
-# Function : OutputUnion
-# Description : Returns the synopsis and detailed description of a union.
-# Arguments : $symbol - the union.
-# $declaration - the declaration of the union.
+# Function : OutputEnum
+# Description : Returns the synopsis and detailed description of a enum.
+# Arguments : $symbol - the enum.
+# $declaration - the declaration of the enum.
#############################################################################
-sub OutputUnion {
+sub OutputEnum {
my ($symbol, $declaration) = @_;
my $id = &CreateValidSGMLID ($symbol);
my $condition = &MakeConditionDescription ($symbol);
-
- # Determine if it is a simple struct or it also has a typedef.
- my $has_typedef = 0;
- if ($StructHasTypedef{$symbol} || $declaration =~ m/^\s*typedef\s+/) {
- $has_typedef = 1;
- }
-
- my $synop;
- my $desc;
- if ($has_typedef) {
- # For unions with typedefs we just output the union name.
- $synop = &MakeReturnField("") . "<link linkend=\"$id\">$symbol</link>;\n";
- $desc = "<refsect2 id=\"$id\" role=\"union\"$condition>\n<title>$symbol</title>\n";
- } else {
- $synop = &MakeReturnField("union") . "<link linkend=\"$id\">$symbol</link>;\n";
- $desc = "<refsect2 id=\"$id\" role=\"union\"$condition>\n<title>union $symbol</title>\n";
- }
+ my $synop = &MakeReturnField("enum") . "<link linkend=\"$id\">$symbol</link>;\n";
+ my $desc = "<refsect2 id=\"$id\" role=\"enum\"$condition>\n<title>enum $symbol</title>\n";
$desc .= MakeIndexterms($symbol, $id);
$desc .= "\n";
$desc .= OutputSymbolExtraLinks($symbol);
- # FIXME: we do more for structs
my $decl_out = &CreateValidSGML ($declaration);
$desc .= "<programlisting>$decl_out</programlisting>\n";
@@ -1672,14 +1722,7 @@ sub OutputUnion {
# Create a table of fields and descriptions
- # FIXME: Inserting  's into the produced type declarations here would
- # improve the output in most situations ... except for function
- # members of structs!
- my @fields = ParseStructDeclaration($declaration, 0,
- 0, \&MakeXRef,
- sub {
- "<structfield id=\"".&CreateValidSGMLID("$id.$_[0]")."\">$_[0]</structfield>";
- });
+ my @fields = ParseEnumDeclaration($declaration);
my $params = $SymbolParams{$symbol};
# If no parameters are filled in, we don't generate the description
@@ -1697,29 +1740,51 @@ sub OutputUnion {
if ($found) {
my %field_descrs = @$params;
+ my $missing_parameters = "";
- $desc .= <<EOF;
-<variablelist role="struct">
+ $desc .= <<EOF;
+<variablelist role="enum">
EOF
- while (@fields) {
- my $field_name = shift @fields;
- my $text = shift @fields;
+ for my $field_name (@fields) {
my $field_descr = $field_descrs{$field_name};
my $param_annotations = "";
- $desc .= "<varlistentry><term>$text</term>\n";
+ $id = &CreateValidSGMLID ($field_name);
+ $condition = &MakeConditionDescription ($field_name);
+ $desc .= "<varlistentry id=\"$id\" role=\"constant\"$condition>\n<term><literal>$field_name</literal></term>\n";
if (defined $field_descr) {
($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr);
$field_descr = &ExpandAbbreviations($symbol, $field_descr);
$desc .= "<listitem><simpara>$field_descr$param_annotations</simpara></listitem>\n";
} else {
- $desc .= "<listitem><simpara /></listitem>\n";
+ &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
+ "Value description for $symbol"."::"."$field_name is missing in source code comment block.");
+ if ($missing_parameters ne "") {
+ $missing_parameters .= ", ".$field_name;
+ } else {
+ $missing_parameters = $field_name;
+ }
+ $desc .= "<listitem />\n";
}
$desc .= "</varlistentry>\n";
}
-
$desc .= "</variablelist>";
+
+ # remember missing parameters (needed in tmpl-free build)
+ if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) {
+ $AllIncompleteSymbols{$symbol}=$missing_parameters;
+ }
}
+ else {
+ if (scalar(@fields) > 0) {
+ if (! exists ($AllIncompleteSymbols{$symbol})) {
+ $AllIncompleteSymbols{$symbol}="<items>";
+ &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
+ "Value descriptions for $symbol are missing in source code comment block.");
+ }
+ }
+ }
+
$desc .= OutputSymbolTraits ($symbol);
$desc .= "</refsect2>\n";
return ($synop, $desc);
@@ -2518,9 +2583,6 @@ sub ExpandAbbreviations {
# TODO: check for a xml comment after |[ and pick the language attribute from
# that
- # TODO: optionally check all words from $text against internal symbols and
- # warn if those could be xreffed, but miss a %,# or ()
-
# keep CDATA unmodified, preserve ulink tags (ideally we preseve all tags
# as such)
return &ModifyXMLElements ($text, $symbol,
@@ -2582,6 +2644,9 @@ sub ExpandAbbreviationsCallback {
# this is apparently also called for markup and not just for plain text
# disable for now.
#$text =~ s%(http|https|ftp)://(.*?)((?:\s|,|\)|\]|\<|\.\s))%<ulink url="$1://$2">$2</ulink>$3%g;
+
+ # TODO: optionally check all words from $text against internal symbols and
+ # warn if those could be xreffed, but miss a %,# or ()
}
return $text;
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
