[gobject-introspection] giscanner: improve state tracking

[Colin Walters <walters src gnome org>]

commit 23dddc02594e733b65f9be76dbf0a0a1e54bc67c
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date:   Wed Aug 14 16:44:22 2013 +0200

    giscanner: improve state tracking

 giscanner/annotationparser.py                      |   31 ++++------
 .../annotationparser/gi/identifier_section.xml     |   60 +-------------------
 tests/scanner/annotationparser/gi/parameter.xml    |    5 +-
 tests/scanner/annotationparser/gi/syntax.xml       |    2 +-
 tests/scanner/annotationparser/gi/tag_returns.xml  |   10 +---
 5 files changed, 22 insertions(+), 86 deletions(-)
---
diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py
index fc9945a..542734a 100644
--- a/giscanner/annotationparser.py
+++ b/giscanner/annotationparser.py
@@ -1341,18 +1341,15 @@ class GtkDocCommentBlockParser(object):
                 param_fields_start = result.start('fields')
                 marker = ' ' * (result.start('parameter_name') + column_offset) + '^'
 
-                if in_part == PART_IDENTIFIER:
-                    in_part = PART_PARAMETERS
-
-                if in_part != PART_PARAMETERS:
-                    column = result.start('parameter_name') + column_offset
-                    warn("'@%s' parameter unexpected at this location:\n%s\n%s" %
+                if in_part not in [PART_IDENTIFIER, PART_PARAMETERS]:
+                    warn('"@%s" parameter unexpected at this location:\n%s\n%s' %
                          (param_name, original_line, marker),
                          position)
 
-                # Old style GTK-Doc allowed return values to be specified as
-                # parameters instead of tags.
+                in_part = PART_PARAMETERS
+
                 if param_name_lower == TAG_RETURNS:
+                    # Deprecated return value as parameter instead of tag
                     param_name = TAG_RETURNS
 
                     if not returns_seen:
@@ -1503,12 +1500,15 @@ class GtkDocCommentBlockParser(object):
                     continue
 
                 # Now that the deprecated stuff is out of the way, continue parsing real tags
-                if in_part == PART_DESCRIPTION:
+                if (in_part == PART_DESCRIPTION
+                or (in_part == PART_PARAMETERS and not comment_block.description)
+                or (in_part == PART_IDENTIFIER and not comment_block.params and not
+                comment_block.description)):
                     in_part = PART_TAGS
 
                 if in_part != PART_TAGS:
-                    column = result.start('tag_name') + column_offset
-                    warn("'%s:' tag unexpected at this location:\n%s\n%s" %
+                    in_part = PART_TAGS
+                    warn('"%s:" tag unexpected at this location:\n%s\n%s' %
                          (tag_name, original_line, marker),
                          position)
 
@@ -1574,20 +1574,13 @@ class GtkDocCommentBlockParser(object):
                 else:
                     comment_block.description += '\n' + line
                 continue
-            elif in_part == PART_PARAMETERS:
+            elif in_part in [PART_PARAMETERS, PART_TAGS]:
                 if not current_part.description:
                     self._validate_multiline_annotation_continuation(line, original_line,
                                                                      column_offset, position)
                 # Append to parameter description.
                 current_part.description += ' ' + line.strip()
                 continue
-            elif in_part == PART_TAGS:
-                if not current_part.description:
-                    self._validate_multiline_annotation_continuation(line, original_line,
-                                                                     column_offset, position)
-
-                # Append to tag description.
-                current_part.description += ' ' + line.strip()
 
         ########################################################################
         # Finished parsing this comment block.
diff --git a/tests/scanner/annotationparser/gi/identifier_section.xml 
b/tests/scanner/annotationparser/gi/identifier_section.xml
index 35ffec6..b75e2dd 100644
--- a/tests/scanner/annotationparser/gi/identifier_section.xml
+++ b/tests/scanner/annotationparser/gi/identifier_section.xml
@@ -111,27 +111,9 @@
       <description>The application class handles ...</description>
     </docblock>
     <messages>
-      <message>4: Warning: Test: '@short_description' parameter unexpected at this location:
+      <message>4: Warning: Test: "@short_description" parameter unexpected at this location:
  * @short_description: the application class
     ^</message>
-      <message>5: Warning: Test: '@title' parameter unexpected at this location:
- * @title: Meep application
-    ^</message>
-      <message>6: Warning: Test: '@section_id' parameter unexpected at this location:
- * @section_id:
-    ^</message>
-      <message>7: Warning: Test: '@see_also' parameter unexpected at this location:
- * @see_also: #MeepSettings
-    ^</message>
-      <message>8: Warning: Test: '@stability' parameter unexpected at this location:
- * @stability: Stable
-    ^</message>
-      <message>9: Warning: Test: '@include' parameter unexpected at this location:
- * @include: meep/app.h
-    ^</message>
-      <message>10: Warning: Test: '@image' parameter unexpected at this location:
- * @image: application.png
-    ^</message>
     </messages>
   </parser>
 </test>
@@ -189,27 +171,9 @@
       <description>The application class handles ...</description>
     </docblock>
     <messages>
-      <message>5: Warning: Test: '@short_description' parameter unexpected at this location:
+      <message>5: Warning: Test: "@short_description" parameter unexpected at this location:
  * @short_description: the application class
     ^</message>
-      <message>6: Warning: Test: '@title' parameter unexpected at this location:
- * @title: Meep application
-    ^</message>
-      <message>7: Warning: Test: '@section_id' parameter unexpected at this location:
- * @section_id:
-    ^</message>
-      <message>8: Warning: Test: '@see_also' parameter unexpected at this location:
- * @see_also: #MeepSettings
-    ^</message>
-      <message>9: Warning: Test: '@stability' parameter unexpected at this location:
- * @stability: Stable
-    ^</message>
-      <message>10: Warning: Test: '@include' parameter unexpected at this location:
- * @include: meep/app.h
-    ^</message>
-      <message>11: Warning: Test: '@image' parameter unexpected at this location:
- * @image: application.png
-    ^</message>
     </messages>
   </parser>
 </test>
@@ -268,27 +232,9 @@
       <description>The application class handles ...</description>
     </docblock>
     <messages>
-      <message>6: Warning: Test: '@short_description' parameter unexpected at this location:
+      <message>6: Warning: Test: "@short_description" parameter unexpected at this location:
  * @short_description: the application class
     ^</message>
-      <message>7: Warning: Test: '@title' parameter unexpected at this location:
- * @title: Meep application
-    ^</message>
-      <message>8: Warning: Test: '@section_id' parameter unexpected at this location:
- * @section_id:
-    ^</message>
-      <message>9: Warning: Test: '@see_also' parameter unexpected at this location:
- * @see_also: #MeepSettings
-    ^</message>
-      <message>10: Warning: Test: '@stability' parameter unexpected at this location:
- * @stability: Stable
-    ^</message>
-      <message>11: Warning: Test: '@include' parameter unexpected at this location:
- * @include: meep/app.h
-    ^</message>
-      <message>12: Warning: Test: '@image' parameter unexpected at this location:
- * @image: application.png
-    ^</message>
     </messages>
   </parser>
 </test>
diff --git a/tests/scanner/annotationparser/gi/parameter.xml b/tests/scanner/annotationparser/gi/parameter.xml
index 5e3a3a1..d6c4ab3 100644
--- a/tests/scanner/annotationparser/gi/parameter.xml
+++ b/tests/scanner/annotationparser/gi/parameter.xml
@@ -31,9 +31,12 @@
       </tags>
     </docblock>
     <messages>
-      <message>6: Warning: Test: '@param1' parameter unexpected at this location:
+      <message>6: Warning: Test: "@param1" parameter unexpected at this location:
  * @param1: first parameter
     ^</message>
+      <message>7: Warning: Test: "Returns:" tag unexpected at this location:
+ * Returns: something
+   ^</message>
     </messages>
   </parser>
 </test>
diff --git a/tests/scanner/annotationparser/gi/syntax.xml b/tests/scanner/annotationparser/gi/syntax.xml
index b8c85b5..6f63dff 100644
--- a/tests/scanner/annotationparser/gi/syntax.xml
+++ b/tests/scanner/annotationparser/gi/syntax.xml
@@ -220,7 +220,7 @@ something */ code goes here
       <description>The application class handles ...</description>
     </docblock>
     <messages>
-      <message>4: Warning: Test: '@short_description' parameter unexpected at this location:
+      <message>4: Warning: Test: "@short_description" parameter unexpected at this location:
  * @short_description: the application class
     ^</message>
     </messages>
diff --git a/tests/scanner/annotationparser/gi/tag_returns.xml 
b/tests/scanner/annotationparser/gi/tag_returns.xml
index 96ee804..ec6e2c4 100644
--- a/tests/scanner/annotationparser/gi/tag_returns.xml
+++ b/tests/scanner/annotationparser/gi/tag_returns.xml
@@ -50,19 +50,13 @@
           <description>first parameter</description>
         </parameter>
       </parameters>
-      <description>Tags should go after the comment block description</description>
       <tags>
         <tag>
           <name>returns</name>
-          <description>something</description>
+          <description>something  Tags should go after the comment block description</description>
         </tag>
       </tags>
     </docblock>
-    <messages>
-      <message>4: Warning: Test: 'Returns:' tag unexpected at this location:
- * Returns: something
-   ^</message>
-    </messages>
   </parser>
 </test>
 
@@ -157,7 +151,7 @@ parameter is encountered.</description>
       </tags>
     </docblock>
     <messages>
-      <message>8: Warning: Test: '@returns' parameter unexpected at this location:
+      <message>8: Warning: Test: "@returns" parameter unexpected at this location:
  * @returns: something else
     ^</message>
       <message>8: Warning: Test: encountered multiple 'Returns' parameters or tags for 
'test_multiple_returns_tag_and_parameter'.</message>