[glibmm] gmmproc: Make enum documentation possible.
- From: Josà Alburquerque <jaalburqu src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glibmm] gmmproc: Make enum documentation possible.
- Date: Mon, 5 Nov 2012 19:57:18 +0000 (UTC)
commit f6b5fbc531137f76f0d8f418a03a2c3d53aad473
Author: Josà Alburquerque <jaalburqu svn gnome org>
Date: Mon Nov 5 14:21:55 2012 -0500
gmmproc: Make enum documentation possible.
* tools/defs_gen/docextract.py (enum_name_pattern): Add a new regular
expression that recognizes gtk-doc enum comment blocks (though
imperfectly because it also catches things such as structure comment
blocks).
(identifier_patterns): Append the new enum_name_pattern to the list of
patterns used to test each gtk-doc block's identifier to see what type
of block it is.
(parse_file): Do not add a particular gtk-doc block if it has been
marked as a block initially thought to be an enum comment block but
later found not to be so.
(skip_to_identifier): Mark the current comment block as an enum type
if the enum_name_pattern matches the identifier.
(process_params): Mark the current block as invalid if the block was
recognized as an enum type but no parameters are found or if any of
the parameter names are not all caps.
(parse_dir): Include .h files for processing because gtk-doc enum
comment blocks are included in those files.
* tools/defs_gen/docextract_to_xml.py: Add an option to not print out
enum docs. Assume that enum docs should be printed out by default.
* tools/pm/DocsParser.pm (parse_on_start):
(parse_on_end): Add logic to correctly parse an <enum> tag (which is
just like the already existing <function> and <signal> tags. The only
difference is in the name of the tags. The function name syntax is
the same as a C function name, the signal name has the form
'CStructName::signal-name' while the enum name has the form
'CEnumName')
(lookup_enum_description): Add this subroutine that gets the
the description of the specified enum.
(lookup_enum_value_documentation): Add this subroutine that gets the
description of an enum value as a Doxygen block.
(lookup_documentation): Use the new remove_example_code subroutine
described below.
(remove_example_code): Add this subroutine that removes example code
from the specified text so that it can be used in other places.
* tools/pm/Enum.pm (c_prefix): Add a new field to the class storing
the enum's C prefix. This field is used when looking up an enum's
value documentation.
(parse_values): Modified to store the C prefix of the enum.
(build_element_list): Modified to lookup the documentation of the
values of the enum and insert the Doxygen block just before each
value. This allows Doxygen to document each value of the enum.
* tools/pm/Output.pm (output_wrap_enum): Modified to lookup
the description of the enum previously parsed by the DocParser and
merge it with an already passed in comment for the enum which is then
passed as before to the _ENUM macro.
* tools/m4/enum.m4: Whitespace correction.
Bug #544694.
ChangeLog | 53 +++++++++++++++++
tools/defs_gen/docextract.py | 45 +++++++++++---
tools/defs_gen/docextract_to_xml.py | 38 ++++++++-----
tools/m4/enum.m4 | 4 +-
tools/pm/DocsParser.pm | 107 ++++++++++++++++++++++++++++++----
tools/pm/Enum.pm | 22 +++++++
tools/pm/Output.pm | 12 ++++
7 files changed, 240 insertions(+), 41 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index b7a6b57..49aaa40 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,56 @@
+2012-11-04 Josà Alburquerque <jaalburquerque gmail com>
+
+ gmmproc: Make enum documentation possible.
+
+ * tools/defs_gen/docextract.py (enum_name_pattern): Add a new regular
+ expression that recognizes gtk-doc enum comment blocks (though
+ imperfectly because it also catches things such as structure comment
+ blocks).
+ (identifier_patterns): Append the new enum_name_pattern to the list of
+ patterns used to test each gtk-doc block's identifier to see what type
+ of block it is.
+ (parse_file): Do not add a particular gtk-doc block if it has been
+ marked as a block initially thought to be an enum comment block but
+ later found not to be so.
+ (skip_to_identifier): Mark the current comment block as an enum type
+ if the enum_name_pattern matches the identifier.
+ (process_params): Mark the current block as invalid if the block was
+ recognized as an enum type but no parameters are found or if any of
+ the parameter names are not all caps.
+ (parse_dir): Include .h files for processing because gtk-doc enum
+ comment blocks are included in those files.
+ * tools/defs_gen/docextract_to_xml.py: Add an option to not print out
+ enum docs. Assume that enum docs should be printed out by default.
+ * tools/pm/DocsParser.pm (parse_on_start):
+ (parse_on_end): Add logic to correctly parse an <enum> tag (which is
+ just like the already existing <function> and <signal> tags. The only
+ difference is in the name of the tags. The function name syntax is
+ the same as a C function name, the signal name has the form
+ 'CStructName::signal-name' while the enum name has the form
+ 'CEnumName')
+ (lookup_enum_description): Add this subroutine that gets the
+ the description of the specified enum.
+ (lookup_enum_value_documentation): Add this subroutine that gets the
+ description of an enum value as a Doxygen block.
+ (lookup_documentation): Use the new remove_example_code subroutine
+ described below.
+ (remove_example_code): Add this subroutine that removes example code
+ from the specified text so that it can be used in other places.
+ * tools/pm/Enum.pm (c_prefix): Add a new field to the class storing
+ the enum's C prefix. This field is used when looking up an enum's
+ value documentation.
+ (parse_values): Modified to store the C prefix of the enum.
+ (build_element_list): Modified to lookup the documentation of the
+ values of the enum and insert the Doxygen block just before each
+ value. This allows Doxygen to document each value of the enum.
+ * tools/pm/Output.pm (output_wrap_enum): Modified to lookup
+ the description of the enum previously parsed by the DocParser and
+ merge it with an already passed in comment for the enum which is then
+ passed as before to the _ENUM macro.
+ * tools/m4/enum.m4: Whitespace correction.
+
+ Bug #544694.
+
2012-11-04 Murray Cumming <murrayc murrayc com>
MountOperation: Correct an ABI break.
diff --git a/tools/defs_gen/docextract.py b/tools/defs_gen/docextract.py
index 13beeff..19204de 100644
--- a/tools/defs_gen/docextract.py
+++ b/tools/defs_gen/docextract.py
@@ -17,7 +17,8 @@ __all__ = ['extract']
class GtkDoc:
def __init__(self):
self.name = None
- self.block_type = '' # The block type ('function', 'signal', 'property')
+ # The block type ('function', 'signal', property', 'enum')
+ self.block_type = ''
self.params = []
self.annotations = []
self.description = ''
@@ -63,6 +64,7 @@ comment_empty_line_pattern = re.compile(r'^\s*\**\s*$')
function_name_pattern = re.compile(r'^([a-z]\w*)\s*:?(\s*\(.*\)\s*){0,2}\s*$')
signal_name_pattern = re.compile(r'^([A-Z]\w+::[a-z0-9-]+)\s*:?(\s*\(.*\)\s*){0,2}\s*$')
property_name_pattern = re.compile(r'^([A-Z]\w+:[a-z0-9-]+)\s*:?(\s*\(.*\)\s*){0,2}\s*$')
+enum_name_pattern = re.compile(r'^([A-Z]\w+)\s*:?(\s*\(.*\)\s*){0,2}\s*$')
return_pattern = re.compile(r'^ ?(returns:|return\s+value:)(.*\n?)$', re.IGNORECASE)
deprecated_pattern = re.compile(r'^(deprecated\s*:\s*.*\n?)$', re.IGNORECASE)
rename_to_pattern = re.compile(r'^(rename\s+to)\s*:\s*(.*\n?)$', re.IGNORECASE)
@@ -77,7 +79,7 @@ annotation_lead_pattern = re.compile(r'^\s*\(\s*(.*?)\s*\)\s*')
# are grouped in a list for easy determination of block identifiers (in
# skip_to_identifier). The function_name_pattern should be tested for last
# because it always matches signal and property identifiers.
-identifier_patterns = [ signal_name_pattern, property_name_pattern, function_name_pattern ]
+identifier_patterns = [ signal_name_pattern, property_name_pattern, enum_name_pattern, function_name_pattern ]
# This pattern is to match return sections that forget to have a colon (':')
# after the initial 'Return' phrase. It is not included by default in the list
@@ -106,8 +108,14 @@ def parse_file(fp, doc_dict):
line = process_params(fp, line, cur_doc)
line = process_description(fp, line, cur_doc)
line = process_final_sections(fp, line, cur_doc)
- # Add the current doc block to the dictionary of doc blocks.
- doc_dict[cur_doc.name] = cur_doc
+
+ # Add the current doc block to the dictionary of doc blocks. If
+ # this block was initially recognized as an 'enum' block in
+ # skip_to_identifier(), the process_params() function will mark the
+ # block as invalid if enum members are not all caps. In that case
+ # do not add the block.
+ if cur_doc.get_type() != 'invalid':
+ doc_dict[cur_doc.name] = cur_doc
# Given a list of annotations as string of the form
# '(annotation1) (annotation2) ...' return a list of annotations of the form
@@ -153,9 +161,9 @@ def skip_to_nonblank(fp, line):
# Given the first line of a comment block (the '/**'), see if the next
# non-blank line is the identifier of the comment block. Stop processing if
# the end of the block or eof is reached. Store the identifier (if there is
-# one) and its type ('function', 'signal' or 'property') in the given GtkDoc.
-# Return the line where the identifier is found or the line that stops the
-# processing (if eof or the end of the comment block is found first).
+# one) and its type ('function', 'signal' or 'property', 'enum') in the given
+# GtkDoc. Return the line where the identifier is found or the line that stops
+# the processing (if eof or the end of the comment block is found first).
def skip_to_identifier(fp, line, cur_doc):
# Skip the initial comment block line ('/**') if not eof.
if line: line = fp.readline()
@@ -182,6 +190,8 @@ def skip_to_identifier(fp, line, cur_doc):
cur_doc.set_type('signal')
elif pattern == property_name_pattern:
cur_doc.set_type('property')
+ elif pattern == enum_name_pattern:
+ cur_doc.set_type('enum')
elif pattern == function_name_pattern:
cur_doc.set_type('function')
return line
@@ -198,6 +208,10 @@ def process_params(fp, line, cur_doc):
if line: line = fp.readline()
line = skip_to_nonblank(fp, line)
if not line or comment_end_pattern.match(line):
+ # If there are no parameters and this block has been recognized as an
+ # enum block, then mark it as invalid.
+ if cur_doc.get_type() == 'enum':
+ cur_doc.set_type('invalid')
return line
# Remove initial ' * ' in first non-empty comment block line.
@@ -207,9 +221,20 @@ def process_params(fp, line, cur_doc):
# param section is not reached (which could be triggered by anything that
# doesn't match a '@param:..." line, even the end of the comment block).
match = param_pattern.match(line)
+
+ # Mark the cur_doc type as invalid if no parameters are found.
+ if not match and cur_doc.get_type() == 'enum':
+ cur_doc.set_type('invalid')
+
while line and match:
+ name = match.group(1)
description = match.group(2)
+ # Set the cur_doc type as 'invalid' if the enum member names are not
+ # all caps.
+ if not name.isupper() and cur_doc.get_type() == 'enum':
+ cur_doc.set_type('invalid')
+
# First extract the annotations from the description and save them.
annotations = []
annotation_match = annotations_pattern.match(description)
@@ -224,12 +249,12 @@ def process_params(fp, line, cur_doc):
# See if the return has been included as part of the parameter
# section and make sure that lines are added to the GtkDoc return if
# so.
- if match.group(1).lower() == "returns":
+ if name.lower() == "returns":
cur_doc.add_return(description, annotations)
append_func = cur_doc.append_to_return
# If not, just add it as a regular parameter.
else:
- cur_doc.add_param(match.group(1), description, annotations)
+ cur_doc.add_param(name, description, annotations)
# Now read lines and append them until next parameter, beginning of
# description (an empty line), the end of the comment block or eof.
@@ -403,7 +428,7 @@ def parse_dir(dir, doc_dict):
path = os.path.join(dir, file)
if os.path.isdir(path):
parse_dir(path, doc_dict)
- if len(file) > 2 and file[-2:] == '.c':
+ if len(file) > 2 and (file[-2:] == '.c' or file[-2:] == '.h'):
sys.stderr.write("Processing " + path + '\n')
parse_file(open(path, 'r'), doc_dict)
diff --git a/tools/defs_gen/docextract_to_xml.py b/tools/defs_gen/docextract_to_xml.py
index d77ad6e..c94c857 100755
--- a/tools/defs_gen/docextract_to_xml.py
+++ b/tools/defs_gen/docextract_to_xml.py
@@ -17,7 +17,7 @@ def usage():
sys.stderr.write('usage: docextract_to_xml.py ' +
'[-s /src/dir | --source-dir=/src/dir] ' +
'[-a | --with-annotations] [-p | --with-properties] ' +
- '[-i | --no-signals ] [-n | --no-since]\n')
+ '[-n | --no-since] [-i | --no-signals ] [-e | --no-enums ]\n')
sys.exit(1)
# Translates special texts to &... HTML acceptable format. Also replace
@@ -61,10 +61,10 @@ def print_annotations(annotations):
if __name__ == '__main__':
try:
- opts, args = getopt.getopt(sys.argv[1:], "d:s:o:apin",
+ opts, args = getopt.getopt(sys.argv[1:], "d:s:o:apnie",
["source-dir=", "with-annotations",
- "with-properties", "no-signals",
- "no-since"])
+ "with-properties", "no-since",
+ "no-signals", "no-enums"])
except getopt.error, e:
sys.stderr.write('docextract_to_xml.py: %s\n' % e)
usage()
@@ -72,6 +72,7 @@ if __name__ == '__main__':
with_annotations = False
with_signals = True
with_properties = False
+ with_enums = True
for opt, arg in opts:
if opt in ('-s', '--source-dir'):
source_dirs.append(arg)
@@ -79,10 +80,12 @@ if __name__ == '__main__':
with_annotations = True
if opt in ('-p', '--with-properties'):
with_properties = True
- if opt in ('-i', '--no-signals'):
- with_signals = False
if opt in ('-n', '--no-since'):
docextract.no_since = True
+ if opt in ('-i', '--no-signals'):
+ with_signals = False
+ if opt in ('-e', '--no-enums'):
+ with_enums = False
if len(args) != 0:
usage()
@@ -106,6 +109,9 @@ if __name__ == '__main__':
# Likewise for properties.
elif block_type == 'property' and not with_properties:
continue
+ # Likewise for enums.
+ elif block_type == 'enum' and not with_enums:
+ continue
print "<" + block_type + " name=\"" + escape_text(name) + "\">"
@@ -127,15 +133,17 @@ if __name__ == '__main__':
print "</parameters>"
- # Show the return-type (also if not dealing with a property):
- if with_annotations:
- print "<return>"
- print "<return_description>" + escape_text(value.ret[0]) + \
- "</return_description>"
- print_annotations(value.ret[1])
- print "</return>"
- else:
- print "<return>" + escape_text(value.ret[0]) + "</return>"
+ if block_type != 'property' and block_type != 'enum':
+ # Show the return-type (also if not dealing with a property or
+ # enum):
+ if with_annotations:
+ print "<return>"
+ print "<return_description>" + escape_text(value.ret[0]) + \
+ "</return_description>"
+ print_annotations(value.ret[1])
+ print "</return>"
+ else:
+ print "<return>" + escape_text(value.ret[0]) + "</return>"
if with_annotations:
print_annotations(value.get_annotations())
diff --git a/tools/m4/enum.m4 b/tools/m4/enum.m4
index b1901d5..3ac338b 100644
--- a/tools/m4/enum.m4
+++ b/tools/m4/enum.m4
@@ -1,4 +1,3 @@
-
dnl
dnl _ENUM(cpp_type, c_type, value_suffix, `element_list', `flags', `optional_refdoc_comment', 'get_type_function_name')
dnl
@@ -20,7 +19,7 @@ m4_define(`__DOCGROUP_'__MODULE_CANONICAL__`_ENUMS__')dnl
')dnl endif
dnl
dnl
-/**$6
+/** $6
* @ingroup __MODULE_CANONICAL__`'Enums
m4_ifelse($3,Flags,`dnl
* @par Bitwise operators:
@@ -98,4 +97,3 @@ GType Glib::Value<__NAMESPACE__::__ENUM_CPPNAME__>::value_type()
_POP()
')dnl endif !NO_GTYPE
')dnl enddef _ENUM
-
diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index 65d3f1d..0a56e55 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -112,11 +112,12 @@ sub parse_on_start($$%)
$tag = lc($tag);
- if($tag eq "function" or $tag eq "signal")
+ if($tag eq "function" or $tag eq "signal" or $tag eq "enum")
{
if(defined $DocsParser::objCurrentFunction)
{
- $objParser->xpcroak("\nClose a function tag before you open another one.");
+ $objParser->xpcroak(
+ "\nClose a function, signal or enum tag before you open another one.");
}
my $functionName = $attr{name};
@@ -194,7 +195,7 @@ sub parse_on_end($$)
$tag = lc($tag);
- if($tag eq "function" or $tag eq "signal")
+ if($tag eq "function" or $tag eq "signal" or $tag eq "enum")
{
# Store the Function structure in the array:
my $functionName = $$DocsParser::objCurrentFunction{name};
@@ -233,6 +234,77 @@ sub parse_on_cdata($$)
}
+# $text lookup_enum_description($enum_name)
+# Looks up the description of enum and returns it after converting it from
+# C to C++ format.
+sub lookup_enum_description($)
+{
+ my ($enum_name) = @_;
+
+ my $objFunction = $DocsParser::hasharrayFunctions{$enum_name};
+ if(!$objFunction)
+ {
+ #print "DocsParser.pm: Warning: enum not found: $enum_name\n";
+ return ""
+ }
+
+ my $text = $$objFunction{description};
+
+ if(length($text) eq 0)
+ {
+ print "DocsParser.pm: Warning: No C docs for: \"$enum_name\"\n";
+ return "";
+ }
+
+ DocsParser::convert_docs_to_cpp($objFunction, \$text);
+ DocsParser::add_m4_quotes(\$text);
+
+ # Escape the space after "i.e." or "e.g." in the brief description.
+ $text =~ s/^([^.]*\b(?:i\.e\.|e\.g\.))\s/$1\\ /;
+
+ remove_example_code($enum_name, \$text);
+
+ return $text;
+}
+
+# $strCommentBlock lookup_enum_value_documentation($enum_name, $c_val_name)
+# Returns a Doxygen comment block for the enum value.
+sub lookup_enum_value_documentation($$)
+{
+ my ($enum_name, $c_val_name) = @_;
+
+ # Assume that there is no description.
+ my $desc = "";
+
+ my $obj_function = $DocsParser::hasharrayFunctions{$enum_name};
+
+ if($obj_function)
+ {
+ my $param_descriptions = \$$obj_function{param_descriptions};
+ $desc = $$param_descriptions->{$c_val_name};
+ }
+
+ if(!$desc or length($desc) eq 0)
+ {
+ return "";
+ }
+
+ DocsParser::convert_docs_to_cpp($obj_function, \$desc);
+ DocsParser::add_m4_quotes(\$desc);
+
+ # Escape the space after "i.e." or "e.g." in the brief description.
+ $desc =~ s/^([^.]*\b(?:i\.e\.|e\.g\.))\s/$1\\ /;
+
+ remove_example_code($enum_name, \$desc);
+
+ # Convert to Doxygen-style comment.
+ $desc =~ s/\n/\n${DocsParser::commentMiddleStart}/g;
+ $desc = $DocsParser::commentStart . $desc;
+ $desc .= "\n${DocsParser::commentEnd}\n";
+
+ return $desc;
+}
+
# $strCommentBlock lookup_documentation($strFunctionName, $deprecation_docs)
sub lookup_documentation($$)
{
@@ -266,16 +338,8 @@ sub lookup_documentation($$)
# Escape the space after "i.e." or "e.g." in the brief description.
$text =~ s/^([^.]*\b(?:i\.e\.|e\.g\.))\s/$1\\ /;
-
- # Remove C example code.
- my $example_removals =
- ($text =~ s"<informalexample>.*?</informalexample>"[C example ellipted]"sg);
- $example_removals +=
- ($text =~ s"<programlisting>.*?</programlisting>"\n[C example ellipted]"sg);
- $example_removals += ($text =~ s"\|\[.*?]\|"\n[C example ellipted]"sg);
-
- print STDERR "gmmproc: $functionName(): Example code discarded.\n"
- if ($example_removals);
+
+ remove_example_code($functionName, \$text);
# Convert to Doxygen-style comment.
$text =~ s/\n/\n${DocsParser::commentMiddleStart}/g;
@@ -285,6 +349,23 @@ sub lookup_documentation($$)
return $text;
}
+# void remove_example_code($obj_name, \$text)
+# Removes example code from the text of docs (passed by reference).
+sub remove_example_code($$)
+{
+ my ($obj_name, $text) = @_;
+
+ # Remove C example code.
+ my $example_removals =
+ ($$text =~ s"<informalexample>.*?</informalexample>"[C example ellipted]"sg);
+ $example_removals +=
+ ($$text =~ s"<programlisting>.*?</programlisting>"\n[C example ellipted]"sg);
+ $example_removals += ($$text =~ s"\|\[.*?]\|"\n[C example ellipted]"sg);
+
+ print STDERR "gmmproc: $obj_name: Example code discarded.\n"
+ if ($example_removals);
+}
+
sub add_m4_quotes($)
{
my ($text) = @_;
diff --git a/tools/pm/Enum.pm b/tools/pm/Enum.pm
index 6096645..fa372cc 100644
--- a/tools/pm/Enum.pm
+++ b/tools/pm/Enum.pm
@@ -2,6 +2,7 @@ package Enum;
use strict;
use warnings;
+use DocsParser;
BEGIN {
use Exporter ();
@@ -27,6 +28,7 @@ our @EXPORT_OK;
#
# string array elem_names;
# string array elem_values;
+# string c_prefix;
#
# bool mark;
# }
@@ -143,6 +145,7 @@ sub new
$$self{mark} = 0;
$$self{flags} = 0;
+ $$self{c_prefix} = "";
$$self{elem_names} = [];
$$self{elem_values} = [];
@@ -215,6 +218,9 @@ sub parse_values($$)
{
# cut off the module prefix, e.g. GTK_
s/^$common_prefix// foreach (@$elem_names);
+
+ # Save the common prefix.
+ $$self{c_prefix} = $common_prefix;
}
$$self{elem_names} = $elem_names;
@@ -316,7 +322,23 @@ sub build_element_list($$$$)
$name =~ s/${subst_in[$ii]}/${subst_out[$ii]}/;
$value =~ s/${subst_in[$ii]}/${subst_out[$ii]}/;
}
+
+ my $docs =
+ DocsParser::lookup_enum_value_documentation("$$self{c_type}",
+ "$$self{c_prefix}$name");
+ if($docs ne "")
+ {
+ # Make sure the docs is indented the right number of spaces.
+ # (First remove initial spaces in first line and then the rest
+ # and then indent the lines).
+ $docs =~ s/^\s+//;
+ $docs =~ s/\n\s+/\n/g;
+ $docs =~ s/\n(\s*\*)/\n${indent} $1/g;
+ $docs = "${indent}${docs}";
+ }
+
+ $elements .= $docs;
$elements .= "${indent}${name}";
$elements .= " = ${value}" if($value ne "");
$elements .= ",\n" if($i < $num_elements - 1);
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index 5312218..3dd34da 100644
--- a/tools/pm/Output.pm
+++ b/tools/pm/Output.pm
@@ -601,6 +601,18 @@ sub output_wrap_enum($$$$$$$)
my $value_suffix = "Enum";
$value_suffix = "Flags" if($$objEnum{flags});
+
+ # Get the existing enum description from the parsed docs.
+ my $description = DocsParser::lookup_enum_description("$c_type");
+
+ # Prepend the Doxygen marker ' * ' to all but the first line.
+ $description =~ s/\n/\n * /g;
+
+ # Make sure indentation of passed in comment is correct.
+ $comment =~ s/\n\s*\*/\n */g;
+
+ # Merge the passed in comment to the existing enum documentation.
+ $comment = $comment . "\n * " . $description;
my $str = sprintf("_ENUM(%s,%s,%s,\`%s\',\`%s\',\`%s\')dnl\n",
$cpp_type,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
