[gobject-introspection] giscanner: rename DocBlock to GtkDocCommentBlock

[Colin Walters <walters src gnome org>]

commit 873c828b21ab837bea751be823b04c10e68dd9ed
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date:   Wed May 29 18:51:02 2013 +0200

    giscanner: rename DocBlock to GtkDocCommentBlock
    
    and move it downwards after DocTag, DocOptions etc for
    easier reading

 giscanner/annotationparser.py                 |  141 ++++++++++++++-----------
 tests/scanner/annotationparser/test_parser.py |    4 +-
 2 files changed, 79 insertions(+), 66 deletions(-)
---
diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py
index 1ef4ffc..0f628ce 100644
--- a/giscanner/annotationparser.py
+++ b/giscanner/annotationparser.py
@@ -455,67 +455,6 @@ MULTILINE_ANNOTATION_CONTINUATION_RE = re.compile(
     re.UNICODE | re.VERBOSE)
 
 
-class DocBlock(object):
-
-    __slots__ = ('name', 'annotations', 'value', 'tags', 'description', 'params', 'position')
-
-    def __init__(self, name):
-        self.name = name
-        self.annotations = DocAnnotations()
-        self.value = None
-        self.tags = OrderedDict()
-        self.description = None
-        self.params = OrderedDict()
-        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):
-        return '<DocBlock %r %r>' % (self.name, self.annotations)
-
-    def to_gtk_doc(self):
-        annotations = ''
-        if self.annotations:
-            annotations += ' '
-            annotations += ' '.join('(%s)' % o for o in self.annotations)
-        lines = [self.name]
-        if 'SECTION' not in self.name:
-            lines[0] += ':'
-        lines[0] += annotations
-        for param in self.params.values():
-            lines.append(param.to_gtk_doc_param())
-        if self.description:
-            lines.append('')
-            for l in self.description.split('\n'):
-                lines.append(l)
-        if self.tags:
-            lines.append('')
-            for tag in self.tags.values():
-                lines.append(tag.to_gtk_doc_tag())
-
-        comment = ''
-        comment += '/**\n'
-        for line in lines:
-            line = line.rstrip()
-            if line:
-                comment += ' * %s\n' % (line, )
-            else:
-                comment += ' *\n'
-        comment += ' */\n'
-        return comment
-
-    def validate(self):
-        for param in self.params.values():
-            param.validate()
-
-        for tag in self.tags.values():
-            tag.validate()
-
-
 class DocTag(object):
 
     __slots__ = ('block', 'name', 'annotations', 'description', 'value', 'position')
@@ -775,11 +714,85 @@ class DocOption(object):
         return self._dict
 
 
+class GtkDocCommentBlock(object):
+    '''
+    Represents a GTK-Doc comment block.
+    '''
+
+    __slots__ = ('name', 'annotations', 'value', 'tags', 'description', 'params', 'position')
+
+    def __init__(self, name):
+        #: Identifier name.
+        self.name = name
+
+        #: Ordered dictionary mapping parameter names to :class:`GtkDocParameter` instances
+        #: applied to this :class:`GtkDocCommentBlock`.
+        self.params = OrderedDict()
+
+        #: The GTK-Doc comment block description part.
+        self.description = None
+
+        #: Ordered dictionary mapping tag names to :class:`GtkDocTag` instances
+        #: applied to this :class:`GtkDocCommentBlock`.
+        self.tags = OrderedDict()
+
+        self.annotations = DocAnnotations()
+        self.value = None
+        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):
+        return '<GtkDocCommentBlock %r %r>' % (self.name, self.annotations)
+
+    def to_gtk_doc(self):
+        annotations = ''
+        if self.annotations:
+            annotations += ' '
+            annotations += ' '.join('(%s)' % o for o in self.annotations)
+        lines = [self.name]
+        if 'SECTION' not in self.name:
+            lines[0] += ':'
+        lines[0] += annotations
+        for param in self.params.values():
+            lines.append(param.to_gtk_doc_param())
+        if self.description:
+            lines.append('')
+            for l in self.description.split('\n'):
+                lines.append(l)
+        if self.tags:
+            lines.append('')
+            for tag in self.tags.values():
+                lines.append(tag.to_gtk_doc_tag())
+
+        comment = ''
+        comment += '/**\n'
+        for line in lines:
+            line = line.rstrip()
+            if line:
+                comment += ' * %s\n' % (line, )
+            else:
+                comment += ' *\n'
+        comment += ' */\n'
+        return comment
+
+    def validate(self):
+        for param in self.params.values():
+            param.validate()
+
+        for tag in self.tags.values():
+            tag.validate()
+
+
 class GtkDocCommentBlockParser(object):
     """
     GTK-Doc comment block parser.
 
-    Parses GTK-Doc comment blocks into a parse tree built out of :class:`DockBlock`,
+    Parse GTK-Doc comment blocks into a parse tree built out of :class:`GtkDocCommentBlock`,
     :class:`DocTag`, :class:`DocAnnotations` and :class:`DocOption` objects. This
     parser tries to accept malformed input whenever possible and does not emit
     syntax errors. However, it does emit warnings at the slightest indication
@@ -935,7 +948,7 @@ class GtkDocCommentBlockParser(object):
                               start (/**) and end (*/) marker lines
         :param filename: source file name where the comment block originated from
         :param lineno:  line in the source file where the comment block starts
-        :returns: a :class:`DocBlock` object or ``None``
+        :returns: a :class:`GtkDocCommentBlock` object or ``None``
 
         .. NOTE:: If you are tempted to refactor this method and split it
             further up (for example into _parse_identifier(), _parse_parameters(),
@@ -1014,7 +1027,7 @@ class GtkDocCommentBlockParser(object):
                     in_part = PART_IDENTIFIER
                     part_indent = line_indent
 
-                    comment_block = DocBlock(identifier_name)
+                    comment_block = GtkDocCommentBlock(identifier_name)
                     comment_block.position = position
 
                     if 'annotations' in result.groupdict() and result.group('annotations') != '':
diff --git a/tests/scanner/annotationparser/test_parser.py b/tests/scanner/annotationparser/test_parser.py
index 1b82625..7141c7a 100644
--- a/tests/scanner/annotationparser/test_parser.py
+++ b/tests/scanner/annotationparser/test_parser.py
@@ -96,11 +96,11 @@ class TestCommentBlock(unittest.TestCase):
                 expected_messages.append(w.text.strip())
 
             # Compare parsed with expected GtkDocCommentBlock
-            msg = 'Parsed DocBlock object tree does not match expected output:\n\n'
+            msg = 'Parsed GtkDocCommentBlock object tree does not match expected output:\n\n'
             msg += '%s\n\n' % (commentblock, )
 
             diff = difflib.unified_diff(expected_tree, parsed_tree,
-                                        'Expected DocBlock', 'Parsed DocBlock',
+                                        'Expected GtkDocCommentBlock', 'Parsed GtkDocCommentBlock',
                                         n=max(len(expected_tree), len(parsed_tree)),
                                         lineterm='')
             for line in diff: