diff options
author | Dieter Verfaillie <dieterv@optionexplicit.be> | 2013-07-30 15:24:43 +0200 |
---|---|---|
committer | Dieter Verfaillie <dieterv@optionexplicit.be> | 2013-10-08 20:54:14 +0200 |
commit | 6f910b872158a063dcadd5efc26e72e9fae3711c (patch) | |
tree | 0f9a9e745a2a3e399441748f2abf3132f7f243a4 /giscanner/annotationparser.py | |
parent | b8835443531fd1b5b00d72e566780c589a90cec9 (diff) | |
download | gobject-introspection-6f910b872158a063dcadd5efc26e72e9fae3711c.tar.gz |
giscanner: improve inline docs
Diffstat (limited to 'giscanner/annotationparser.py')
-rw-r--r-- | giscanner/annotationparser.py | 129 |
1 files changed, 106 insertions, 23 deletions
diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py index 9d6a6b61..bbe81cfc 100644 --- a/giscanner/annotationparser.py +++ b/giscanner/annotationparser.py @@ -1,7 +1,8 @@ +# -*- coding: utf-8 -*- # -*- Mode: Python -*- # GObject-Introspection - a framework for introspecting GObject libraries # Copyright (C) 2008-2010 Johan Dahlin -# Copyright (C) 2012 Dieter Verfaillie <dieterv@optionexplicit.be> +# Copyright (C) 2012-2013 Dieter Verfaillie <dieterv@optionexplicit.be> # # This program is free software; you can redistribute it and/or # modify it under the terms of the GNU General Public License @@ -20,7 +21,88 @@ # -# AnnotationParser - extract annotations from GTK-Doc comment blocks +''' +GTK-Doc comment block format +---------------------------- + +A GTK-Doc comment block is built out of multiple parts. Each part can be further +divided into fields which are separated by a colon ("``:``") delimiter. + +Known parts and the fields they are constructed from look like the following +(optional fields are enclosed in square brackets):: + + ┌───────────────────────────────────────────────────────────┐ + │ /** │ ─▷ start token + ├────────────────────┬──────────────────────────────────────┤ + │ * identifier_name │ [: annotations] │ ─▷ identifier part + ├────────────────────┼─────────────────┬────────────────────┤ + │ * @parameter_name │ [: annotations] │ : description │ ─▷ parameter part + ├────────────────────┴─────────────────┴────────────────────┤ + │ * │ ─▷ comment block description + │ * comment_block_description │ + ├─────────────┬─────────────────┬───────────┬───────────────┤ + │ * tag_name │ [: annotations] │ [: value] │ : description │ ─▷ tag part + ├─────────────┴─────────────────┴───────────┴───────────────┤ + │ */ │ ─▷ end token + └───────────────────────────────────────────────────────────┘ + +There are two conditions that must be met before a comment block is recognized +as a GTK-Doc comment block: + +#. The comment block is opened with a GTK-Doc start token ("``/**``") +#. The first line following the start token contains a valid identifier part + +Once a GTK-Doc comment block has been identified as such and has been stripped +from its start and end tokens the remaining parts have to be written in a +specific order: + +#. There must be exactly 1 `identifier` part on the first line of the + comment block which consists of: + + * a required `identifier_name` field + * an optional `annotations` field + +#. Zero or more `parameter` parts, each consisting of: + + * a required `parameter_name` field + * an optional `annotations` field + * a required `description` field (can be the empty string) + +#. One optional `comment block description` part which must begin with at + least 1 empty line signaling the start of this part. + +#. Zero or more `tag` parts, each consisting of: + + * a required `tag_name` field + * an optional `annotations` field + * an optional `value` field + * a required `description` field (can be the empty string) + +Additionally, the following restrictions are in effect: + +#. Separating parts with an empty line: + + * `identifier` and `parameter` parts cannot be separated from each other by + an empty line as this would signal the start of the + `comment block description` part (see above). + * it is required to separate the `comment block description` part from the + `identifier` or `parameter` parts with an empty line (see above) + * `comment block description` and `tag` parts can optionally be separated + by an empty line + +#. Parts and fields cannot span multiple lines, except for: + + * the `comment_block_description` part + * `parameter description` and `tag description` fields + +#. Taking the above restrictions into account, spanning multiple paragraphs is + limited to the `comment block description` part and `tag description` fields. + +Refer to the `GTK-Doc manual`_ for more detailed usage information. + +.. _GTK-Doc manual: + http://developer.gnome.org/gtk-doc-manual/1.18/documenting.html.en +''' import re @@ -171,19 +253,17 @@ COMMENT_END_RE = re.compile( ''', re.VERBOSE) -# Program matching the ' * ' at the beginning of every +# Pattern matching the ' * ' at the beginning of every # line inside a comment block. -# -# Results in 0 symbolic groups. COMMENT_ASTERISK_RE = re.compile( r''' ^ # start [^\S\n\r]* # 0 or more whitespace characters \* # 1 asterisk character - [^\S\n\r]? # 0 or 1 whitespace characters. Careful, - # removing more than 1 whitespace - # character would break embedded - # example program indentation + [^\S\n\r]? # 0 or 1 whitespace characters + # WARNING: removing more than 1 + # whitespace character breaks + # embedded example program indentation ''', re.VERBOSE) @@ -201,9 +281,7 @@ COMMENT_INDENTATION_RE = re.compile( ''', re.VERBOSE) -# Program matching an empty line. -# -# Results in 0 symbolic groups. +# Pattern matching an empty line. EMPTY_LINE_RE = re.compile( r''' ^ # start @@ -385,6 +463,9 @@ class DocBlock(object): self.position = None def __cmp__(self, other): + # Note: This is used by g-ir-annotation-tool, which does a ``sorted(blocks.values())``, + # meaning that keeping this around makes update-glib-annotations.py patches + # easier to review. return cmp(self.name, other.name) def __repr__(self): @@ -753,12 +834,12 @@ class AnnotationParser(object): """ def parse(self, comments): - """ - Parses multiple GTK-Doc comment blocks. + ''' + Parse multiple GTK-Doc comment blocks. - :param comments: a list of (comment, filename, lineno) tuples - :returns: a dictionary mapping identifier names to :class:`DocBlock` objects - """ + :param comments: an iterable of ``(comment, filename, lineno)`` tuples + :returns: a dictionary mapping identifier names to :class:`GtkDocCommentBlock` objects + ''' comment_blocks = {} @@ -788,12 +869,13 @@ class AnnotationParser(object): return comment_blocks def parse_comment_block(self, comment): - """ - Parses a single GTK-Doc comment block. + ''' + Parse a single GTK-Doc comment block. - :param comment: a (comment, filename, lineno) tuple + :param comment: string representing the GTK-Doc comment block including it's + start ("``/**``") and end ("``*/``") tokens. :returns: a :class:`DocBlock` object or ``None`` - """ + ''' comment, filename, lineno = comment @@ -827,7 +909,8 @@ class AnnotationParser(object): # Not a GTK-Doc comment block. return None - # If we get this far, we are inside a GTK-Doc comment block. + # If we get this far, we must be inside something + # that looks like a GTK-Doc comment block. return self._parse_comment_block(comment_lines, filename, lineno) def _parse_comment_block(self, comment_lines, filename, lineno): @@ -871,7 +954,7 @@ class AnnotationParser(object): original_line = line column_offset = 0 - # Get rid of ' * ' at start of the line. + # Get rid of the ' * ' at the start of the line. result = COMMENT_ASTERISK_RE.match(line) if result: column_offset = result.end(0) |