[gobject-introspection] giscanner: treat the GTK-Doc Description: tag like any other tag

[Dieter Verfaillie <dieterv src gnome org>]

commit 079b2c5bf9d73ac47a7bb1c62f176cbd85fb1e2a
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date:   Tue Jul 17 17:30:47 2012 +0200

    giscanner: treat the GTK-Doc Description: tag like any other tag
    
    and add paragraph break tests.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=688897

 giscanner/annotationparser.py                      |   33 +++---
 .../gi/syntax_paragraph_breaks.xml                 |  117 ++++++++++++++++++++
 2 files changed, 136 insertions(+), 14 deletions(-)
---
diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py
index 509579f..179af86 100644
--- a/giscanner/annotationparser.py
+++ b/giscanner/annotationparser.py
@@ -48,6 +48,7 @@ TAG_STABILITY = 'stability'
 TAG_DEPRECATED = 'deprecated'
 TAG_RETURNS = 'returns'
 TAG_RETURNVALUE = 'return value'
+TAG_DESCRIPTION = 'description'
 TAG_ATTRIBUTES = 'attributes'
 TAG_RENAME_TO = 'rename to'
 TAG_TYPE = 'type'
@@ -63,6 +64,7 @@ _ALL_TAGS = [TAG_VFUNC,
              TAG_DEPRECATED,
              TAG_RETURNS,
              TAG_RETURNVALUE,
+             TAG_DESCRIPTION,
              TAG_ATTRIBUTES,
              TAG_RENAME_TO,
              TAG_TYPE,
@@ -296,16 +298,6 @@ PARAMETER_RE = re.compile(r'''
     ''',
     re.VERBOSE | re.MULTILINE)
 
-# Program matching old style "Description:" tag.
-#
-# Results in 0 symbolic groups.
-DESCRIPTION_TAG_RE = re.compile(r'''
-    ^                                        # start
-    [^\S\n\r]*                               # 0 or more whitespace characters
-    Description:                             # 'Description:' literal
-    ''',
-    re.VERBOSE | re.MULTILINE)
-
 # Program matching tags.
 #
 # Results in 4 symbolic groups:
@@ -987,6 +979,23 @@ class AnnotationParser(object):
                 tag_annotations = result.group('annotations')
                 tag_description = result.group('description')
 
+                marker = ' '*(result.start('tag_name') + column_offset) + '^'
+
+                # Deprecated GTK-Doc Description: tag
+                if tag_name.lower() == TAG_DESCRIPTION:
+                    message.warn("GTK-Doc tag \"Description:\" has been deprecated:\n%s\n%s" %
+                                 (original_line, marker),
+                                 position)
+
+                    in_part = PART_DESCRIPTION
+
+                    if not comment_block.comment:
+                        comment_block.comment = tag_description
+                    else:
+                        comment_block.comment += '\n' + tag_description
+                    continue
+
+                # Now that the deprecated stuff is out of the way, continue parsing real tags
                 if in_part == PART_DESCRIPTION:
                     in_part = PART_TAGS
 
@@ -1041,10 +1050,6 @@ class AnnotationParser(object):
             ####################################################################
             if in_part in [PART_IDENTIFIER, PART_DESCRIPTION]:
                 if not comment_block.comment:
-                    # Backwards compatibility with old style GTK-Doc
-                    # comment blocks where Description used to be a comment
-                    # block tag. Simply get rid of 'Description:'.
-                    line = re.sub(DESCRIPTION_TAG_RE, '', line)
                     comment_block.comment = line
                 else:
                     comment_block.comment += '\n' + line
diff --git a/tests/scanner/annotationparser/gi/syntax_paragraph_breaks.xml b/tests/scanner/annotationparser/gi/syntax_paragraph_breaks.xml
index 6291493..4ae1e03 100644
--- a/tests/scanner/annotationparser/gi/syntax_paragraph_breaks.xml
+++ b/tests/scanner/annotationparser/gi/syntax_paragraph_breaks.xml
@@ -26,6 +26,28 @@ So this is considered a new paragraph.</description>
 
 <test>
   <!--
+  Description: tag, all lines (outside program- listings and CDATA sections) just containing
+  a ' *' (blank-asterisk) are converted to paragraph breaks.
+  -->
+  <commentblock>/**
+ * SECTION:test
+ *
+ * Description: The following line is ' *' (blank-asterisk).
+ *
+ * So this is considered a new paragraph.
+ */</commentblock>
+  <docblock>
+    <identifier>
+      <name>SECTION:test</name>
+    </identifier>
+    <description>The following line is ' *' (blank-asterisk).
+
+So this is considered a new paragraph.</description>
+  </docblock>
+</test>
+
+<test>
+  <!--
   ' * ' (blank-asterisk-blank) are also converted to paragraph breaks.
   -->
   <commentblock>/**
@@ -47,6 +69,27 @@ So this is considered a new paragraph.</description>
 
 <test>
   <!--
+  Description: tag, ' * ' (blank-asterisk-blank) are also converted to paragraph breaks.
+  -->
+  <commentblock>/**
+ * SECTION:test
+ *
+ * Description: The following line is ' * ' (blank-asterisk-blank).
+ * 
+ * So this is considered a new paragraph.
+ */</commentblock>
+  <docblock>
+    <identifier>
+      <name>SECTION:test</name>
+    </identifier>
+    <description>The following line is ' * ' (blank-asterisk-blank).
+
+So this is considered a new paragraph.</description>
+  </docblock>
+</test>
+
+<test>
+  <!--
   If you want an "empty line" but not a paragraph break, change that into ' *  '
   (blank-asterisk-blank-blank). The "empty line" can be easily recognized in the
   output as it contains a single space character.
@@ -70,6 +113,29 @@ So this is preceded by an empty line and is not considered a new paragraph.</des
 
 <test>
   <!--
+  Description: tag, if you want an "empty line" but not a paragraph break, change that into ' *  '
+  (blank-asterisk-blank-blank). The "empty line" can be easily recognized in the
+  output as it contains a single space character.
+  -->
+  <commentblock>/**
+ * SECTION:test
+ *
+ * Description: The following line is (blank-asterisk-blank-blank).
+ *  
+ * So this is preceded by an empty line and is not considered a new paragraph.
+ */</commentblock>
+  <docblock>
+    <identifier>
+      <name>SECTION:test</name>
+    </identifier>
+    <description>The following line is (blank-asterisk-blank-blank).
+ 
+So this is preceded by an empty line and is not considered a new paragraph.</description>
+  </docblock>
+</test>
+
+<test>
+  <!--
   If you want an "empty line" but not a paragraph break, change that into ' *  '
   (blank-asterisk-blank-blank). The "empty line" can be easily recognized in the
   output as it contains a single space character.
@@ -119,4 +185,55 @@ print_attributes (GIBaseInfo *info)
   </docblock>
 </test>
 
+<test>
+  <!--
+  Description: tag, if you want an "empty line" but not a paragraph break, change that into ' *  '
+  (blank-asterisk-blank-blank). The "empty line" can be easily recognized in the
+  output as it contains a single space character.
+  -->
+  <commentblock><![CDATA[/**
+ * SECTION:test
+ *
+ * Description: <example>
+ * <title>Iterating over attributes</title>
+ * <programlisting>
+ * void
+ * print_attributes (GIBaseInfo *info)
+ * {
+ *   GIAttributeIter iter = { 0, };
+ *   char *name;
+ *   char *value;
+ *  
+ *   while (g_base_info_iterate_attributes (info, &iter, &name, &value))
+ *     {
+ *       g_print ("attribute name: %s value: %s", name, value);
+ *     }
+ * }
+ * </programlisting>
+ * </example>
+ */]]></commentblock>
+  <docblock>
+    <identifier>
+      <name>SECTION:test</name>
+    </identifier>
+    <description><![CDATA[<example>
+<title>Iterating over attributes</title>
+<programlisting>
+void
+print_attributes (GIBaseInfo *info)
+{
+  GIAttributeIter iter = { 0, };
+  char *name;
+  char *value;
+ 
+  while (g_base_info_iterate_attributes (info, &iter, &name, &value))
+    {
+      g_print ("attribute name: %s value: %s", name, value);
+    }
+}
+</programlisting>
+</example>]]></description>
+  </docblock>
+</test>
+
 </tests>