[gobject-introspection] giscanner: restore support for 'Return:' and 'Returns value:' tags

[Colin Walters <walters src gnome org>]

commit bcc9f905cc723dd4c2cc4894622ebe14fffa55a8
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date:   Wed May 29 18:29:17 2013 +0200

    giscanner: restore support for 'Return:' and 'Returns value:' tags
    
    Accepted by old version of annotationparser.py and actually
    encountered in the wild. Internaly normalize to 'Returns:'.

 gir/glib-2.0.c                                    |    4 +-
 gir/gobject-2.0.c                                 |    8 +-
 giscanner/annotationparser.py                     |   18 +++-
 tests/scanner/annotationparser/gi/tag_returns.xml |  102 +++++++++++++++++++++
 4 files changed, 118 insertions(+), 14 deletions(-)
---
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index afd3b80..aeb682d 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -11793,9 +11793,7 @@
  * or may not include using @old_destroy as sometimes replacement
  * should not destroy the object in the normal way.
  *
- * Return: %TRUE if the existing value for @key_id was replaced
- *  by @newval, %FALSE otherwise.
- *
+ * Returns: %TRUE if the existing value for @key_id was replaced by @newval, %FALSE otherwise.
  * Since: 2.34
  */
 
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 903f5f7..cb50341 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -2452,9 +2452,7 @@
  * or may not include using @old_destroy as sometimes replacement
  * should not destroy the object in the normal way.
  *
- * Return: %TRUE if the existing value for @key was replaced
- *  by @newval, %FALSE otherwise.
- *
+ * Returns: %TRUE if the existing value for @key was replaced by @newval, %FALSE otherwise.
  * Since: 2.34
  */
 
@@ -2482,9 +2480,7 @@
  * or may not include using @old_destroy as sometimes replacement
  * should not destroy the object in the normal way.
  *
- * Return: %TRUE if the existing value for @quark was replaced
- *  by @newval, %FALSE otherwise.
- *
+ * Returns: %TRUE if the existing value for @quark was replaced by @newval, %FALSE otherwise.
  * Since: 2.34
  */
 
diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py
index fb11a67..1ef4ffc 100644
--- a/giscanner/annotationparser.py
+++ b/giscanner/annotationparser.py
@@ -130,7 +130,7 @@ TAG_SINCE = 'since'
 TAG_STABILITY = 'stability'
 TAG_DEPRECATED = 'deprecated'
 TAG_RETURNS = 'returns'
-TAG_RETURNVALUE = 'return value'
+TAG_RETURN_VALUE = 'return value'
 TAG_DESCRIPTION = 'description'
 TAG_ATTRIBUTES = 'attributes'
 TAG_RENAME_TO = 'rename to'
@@ -141,12 +141,17 @@ TAG_SET_VALUE_FUNC = 'set value func'
 TAG_GET_VALUE_FUNC = 'get value func'
 TAG_TRANSFER = 'transfer'
 TAG_VALUE = 'value'
+
+# Deprecated tags - Unfortunately, these where accepted by old versions of this module.
+TAG_RETURN = 'return'
+TAG_RETURNS_VALUE = 'returns value'
+
 _ALL_TAGS = [TAG_VFUNC,
              TAG_SINCE,
              TAG_STABILITY,
              TAG_DEPRECATED,
              TAG_RETURNS,
-             TAG_RETURNVALUE,
+             TAG_RETURN_VALUE,
              TAG_DESCRIPTION,
              TAG_ATTRIBUTES,
              TAG_RENAME_TO,
@@ -156,7 +161,9 @@ _ALL_TAGS = [TAG_VFUNC,
              TAG_SET_VALUE_FUNC,
              TAG_GET_VALUE_FUNC,
              TAG_TRANSFER,
-             TAG_VALUE]
+             TAG_VALUE,
+             TAG_RETURN,
+             TAG_RETURNS_VALUE]
 
 # Annotations - applied to parameters and return values
 ANN_ALLOW_NONE = 'allow-none'
@@ -1148,7 +1155,8 @@ class GtkDocCommentBlockParser(object):
                                  (tag_name, original_line, marker),
                                  position)
 
-                if tag_name.lower() in [TAG_RETURNS, TAG_RETURNVALUE]:
+                if tag_name.lower() in [TAG_RETURN, TAG_RETURNS,
+                                        TAG_RETURN_VALUE, TAG_RETURNS_VALUE]:
                     if not returns_seen:
                         returns_seen = True
                     else:
@@ -1206,7 +1214,7 @@ class GtkDocCommentBlockParser(object):
                 self._validate_multiline_annotation_continuation(line, original_line,
                                                                  column_offset, position)
                 # Append to tag description.
-                if current_tag.name.lower() in [TAG_RETURNS, TAG_RETURNVALUE]:
+                if current_tag.name.lower() in [TAG_RETURNS, TAG_RETURN_VALUE]:
                     current_tag.description += ' ' + line.strip()
                 else:
                     current_tag.value += ' ' + line.strip()
diff --git a/tests/scanner/annotationparser/gi/tag_returns.xml 
b/tests/scanner/annotationparser/gi/tag_returns.xml
index 0068679..60d3d58 100644
--- a/tests/scanner/annotationparser/gi/tag_returns.xml
+++ b/tests/scanner/annotationparser/gi/tag_returns.xml
@@ -231,4 +231,106 @@ parameter is encountered.</description>
   </parser>
 </test>
 
+<test>
+  <!--
+  Technically not a valid Returns: tag, but we need to support this for backwards compatibility
+  with the old annotationparser.
+  -->
+  <input>/**
+ * clutter_text_coords_to_position:
+ * @self: a #ClutterText
+ * @x: the X coordinate, relative to the actor
+ * @y: the Y coordinate, relative to the actor
+ *
+ * Retrieves the position of the character at the given coordinates.
+ *
+ * Return: the position of the character
+ *
+ * Since: 1.10
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>clutter_text_coords_to_position</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>self</name>
+          <description>a #ClutterText</description>
+        </parameter>
+        <parameter>
+          <name>x</name>
+          <description>the X coordinate, relative to the actor</description>
+        </parameter>
+        <parameter>
+          <name>y</name>
+          <description>the Y coordinate, relative to the actor</description>
+        </parameter>
+      </parameters>
+      <description>Retrieves the position of the character at the given coordinates.</description>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <description>the position of the character</description>
+        </tag>
+        <tag>
+          <name>since</name>
+          <description>1.10</description>
+        </tag>
+      </tags>
+    </docblock>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Technically not a valid Returns: tag, but we need to support this for backwards compatibility
+  with the old annotationparser.
+  -->
+  <input>/**
+ * clutter_text_coords_to_position:
+ * @self: a #ClutterText
+ * @x: the X coordinate, relative to the actor
+ * @y: the Y coordinate, relative to the actor
+ *
+ * Retrieves the position of the character at the given coordinates.
+ *
+ * Returns value: the position of the character
+ *
+ * Since: 1.10
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>clutter_text_coords_to_position</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>self</name>
+          <description>a #ClutterText</description>
+        </parameter>
+        <parameter>
+          <name>x</name>
+          <description>the X coordinate, relative to the actor</description>
+        </parameter>
+        <parameter>
+          <name>y</name>
+          <description>the Y coordinate, relative to the actor</description>
+        </parameter>
+      </parameters>
+      <description>Retrieves the position of the character at the given coordinates.</description>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <description>the position of the character</description>
+        </tag>
+        <tag>
+          <name>since</name>
+          <description>1.10</description>
+        </tag>
+      </tags>
+    </docblock>
+  </parser>
+</test>
+
 </tests>