From 825fd305f03b726665edca34963978ce27448182 Mon Sep 17 00:00:00 2001 From: José Alburquerque Date: Sun, 11 Apr 2010 15:45:09 -0400 Subject: Update doc extraction tool to handle GObjectIntrospection annotations. * codegen/docextract.py (FunctionDoc): Renamed class to GtkDoc. (GtkDoc::annotations): Added a list field to store annotations which are 2-tuples of (name, value). (GtkDoc::ret): Modified field to store the return description along with a list of annotations as described above. (GtkDoc::params): Now holds a list of 3-tupples: name, description and annotations (as described above). (GtkDoc::block_type): Add a field to tell if the comment block is a function block, signal block or property block. (GtkDoc::set_type): (GtkDoc::get_type): Add methods for setting/getting the block type. (GtkDoc::add_param): Modified to also accept a list of annotations to be added with the parameter. (GtkDoc::add_annotation): (GtkDoc::get_annotations): Added methods to add/get annotations for the comment block. (GtkDoc::append_description): Renamed to append_to_description(). (GtkDoc::get_param_description): Removed unused method. (GtkDoc::get_description): Added method to get block description. (GtkDoc::add_return): Added method to add a return accepting the first line of the description and its annotations. (GtkDoc::append_return): Renamed to append_to_return(). (Regular expressions): - Made the names of the variables un-abbreviated. - Added 'since', 'deprecated' and 'rename to' regular expressions. - Modified the return matching regular expression so that it doesn't match descriptions that begin with 'Returns ...'. This improves the docs of many function. - Added signal and property comment block identifier matching regular expressions in case those are useful. - Modified existing identifier matching regular expressions (function, signal, and property regular expressions) to properly parse annotations. Also added a regular expression for extracting annotations from the parameter and return descriptions. - Refined the function name matching regular expression to only accept identifiers that begin with a lowercase letter. This eliminates 'SECTION:' matches. - Finally, grouped commonly related expressions like return_pattern, since_pattern, etc. into groups (in lists) so that matching those sections can be done using loops. (Parsing algorithm): Modified the algorithm to use a functional approach to parsing. Extra methods like skip_to_comment() and processs_params() have been added and used in the parse_file() function to now process the comment blocks. (parse_dir): Added file processing output to stderr. * codegen/docextract_to_xml.py (usage): Added function to print out the usage. (print_annotations): Added function to print the given list of annotations. (options): Added --with-signals (-i), with-properties (-p) and --with-annotation (-a) to the existing --source-dir (-s) option. (algorithm): Now prints annotations, if specified. Also, prints signals and properties correctly (using names like Class::signal-one for signals and Classs:property) with xml such as .... The return xml is slightly modified with annotations but this would only be exhibited if annotation xml is requested. --- codegen/docextract_to_xml.py | 87 +++++++++++++++++++++++++++++++++----------- 1 file changed, 65 insertions(+), 22 deletions(-) (limited to 'codegen/docextract_to_xml.py') diff --git a/codegen/docextract_to_xml.py b/codegen/docextract_to_xml.py index f8d3bae..638ac94 100755 --- a/codegen/docextract_to_xml.py +++ b/codegen/docextract_to_xml.py @@ -13,6 +13,13 @@ import sys import docextract +def usage(): + sys.stderr.write('usage: docextract_to_xml.py ' + + '[-s /src/dir | --source-dir=/src/dir] ' + + '[-a | --with-annotations] [-p | --with-properties] ' + + '[-i | --with-signals ]\n') + sys.exit(1) + def escape_text(unescaped_text): # Escape every "&" not part of an entity reference escaped_text = re.sub(r'&(?![A-Za-z]+;)', '&', unescaped_text) @@ -30,23 +37,34 @@ def escape_text(unescaped_text): return escaped_text +def print_annotations(annotations): + for annotation in annotations: + print "" + \ + escape_text(annotation[1]) + "" + if __name__ == '__main__': try: - opts, args = getopt.getopt(sys.argv[1:], "d:s:o:", - ["source-dir="]) + opts, args = getopt.getopt(sys.argv[1:], "d:s:o:api", + ["source-dir=", "with-annotations", + "with-properties", "with-signals"]) except getopt.error, e: - sys.stderr.write('docgen.py: %s\n' % e) - sys.stderr.write( - 'usage: docgen.py [-s /src/dir]\n') - sys.exit(1) + sys.stderr.write('docextract_to_xml.py: %s\n' % e) + usage() source_dirs = [] + with_annotations = False + with_signals = False + with_properties = False for opt, arg in opts: if opt in ('-s', '--source-dir'): source_dirs.append(arg) + if opt in ('-a', '--with-annotations'): + with_annotations = True + if opt in ('-p', '--with-properties'): + with_properties = True + if opt in ('-i', '--with-signals'): + with_signals = True if len(args) != 0: - sys.stderr.write( - 'usage: docgen.py [-s /src/dir]\n') - sys.exit(1) + usage() docs = docextract.extract(source_dirs); docextract.extract_tmpl(source_dirs, docs); #Try the tmpl sgml files too. @@ -58,25 +76,50 @@ if __name__ == '__main__': print "" for name, value in docs.items(): - print "" + # Get the type of comment block ('function', 'signal' or + # 'property') (the value is a GtkDoc). + block_type = value.get_type() + + # Skip signals if the option was not specified. + if block_type == 'signal' and not with_signals: + continue + # Likewise for properties. + elif block_type == 'property' and not with_properties: + continue + + print "<" + block_type + " name=\"" + escape_text(name) + "\">" print "" - #The value is a docextract.FunctionDoc - print escape_text(value.description) + print escape_text(value.get_description()) print "" - # Loop through the parameters: - print "" - for name, description in value.params: - print "" - print "" + escape_text(description) + "" - print "" + # Loop through the parameters if not dealing with a property: + if block_type != 'property': + print "" + for name, description, annotations in value.params: + print "" + print "" + escape_text(description) + "" + + if with_annotations: + print_annotations(annotations) + + print "" + + print "" - print "" + # Show the return-type (also if not dealing with a property): + if with_annotations: + print "" + print "" + escape_text(value.ret[0]) + \ + "" + print_annotations(value.ret[1]) + print "" + else: + print "" + escape_text(value.ret[0]) + "" - # Show the return-type: - print "" + escape_text(value.ret) + "" + if with_annotations: + print_annotations(value.get_annotations()) - print "\n" + print "\n" print "" -- cgit