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:'.

4 files changed, 118 insertions, 14 deletions

diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index afd3b800..aeb682d1 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 903f5f75..cb50341a 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 fb11a676..1ef4ffc1 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 0068679e..60d3d58c 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>