[gobject-introspection] giscanner: complete vararg parameter parsing

[Colin Walters <walters src gnome org>]

commit 4d1972cedd20bb51b8c67ec030339d5d4dce12a9
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date:   Wed Sep 4 22:31:48 2013 +0200

    giscanner: complete vararg parameter parsing
    
    Normalize deprecated @Varargs [1] and named __VA_ARGS__ [2]
    notations in as single location, add tests. Remove special
    casing in maintransformer as it is no longer a special case
    (tests/warn/unknown-parameter.h passes).
    
    [1] https://git.gnome.org/browse/gtk-doc/commit/gtkdoc-mkdb.in?id=4c9d4db0e264d403b301dad9be1c290134846d03
    [1] https://git.gnome.org/browse/gtk-doc/commit/gtkdoc-mkdb.in?id=55c78181d6ae1606bdf7885e9caed70a484127ec

 giscanner/annotationparser.py                      |   12 +-
 giscanner/maintransformer.py                       |    3 -
 tests/scanner/Makefile.am                          |    1 +
 .../annotationparser/gi/parameter_varargs.xml      |  236 ++++++++++++++++++++
 4 files changed, 246 insertions(+), 6 deletions(-)
---
diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py
index b8e86e9..f5205a5 100644
--- a/giscanner/annotationparser.py
+++ b/giscanner/annotationparser.py
@@ -387,7 +387,7 @@ PARAMETER_RE = re.compile(
     ^                                                    # start
     \s*                                                  # 0 or more whitespace characters
     @                                                    # @ character
-    (?P<parameter_name>[\w-]*\w|\.\.\.)                  # parameter name
+    (?P<parameter_name>[\w-]*\w|.*?\.\.\.)               # parameter name
     \s*                                                  # 0 or more whitespace characters
     :{1}                                                 # required colon
     \s*                                                  # 0 or more whitespace characters
@@ -1043,6 +1043,7 @@ class GtkDocCommentBlockParser(object):
             ####################################################################
             result = PARAMETER_RE.match(line)
             if result:
+                marker = ' ' * (result.start('parameter_name') + column_offset) + '^'
                 param_name = result.group('parameter_name')
                 param_annotations = result.group('annotations')
                 param_description = result.group('description')
@@ -1054,7 +1055,6 @@ class GtkDocCommentBlockParser(object):
 
                 if in_part != PART_PARAMETERS:
                     column = result.start('parameter_name') + column_offset
-                    marker = ' ' * column + '^'
                     message.warn("'@%s' parameter unexpected at this location:\n%s\n%s" %
                                  (param_name, original_line, marker),
                                  position)
@@ -1070,9 +1070,15 @@ class GtkDocCommentBlockParser(object):
                         message.warn("encountered multiple 'Returns' parameters or tags for "
                                      "'%s'." % (comment_block.name, ),
                                      position)
+                elif (param_name == 'Varargs'
+                or (param_name.endswith('...') and param_name != '...')):
+                    # Deprecated @Varargs notation or named __VA_ARGS__ instead of @...
+                    message.warn('"@%s" parameter is deprecated, please use "@..." instead:\n'
+                                 '%s\n%s' % (param_name, original_line, marker),
+                                 position)
+                    param_name = '...'
                 elif param_name in comment_block.params.keys():
                     column = result.start('parameter_name') + column_offset
-                    marker = ' ' * column + '^'
                     message.warn("multiple '@%s' parameters for identifier '%s':\n%s\n%s" %
                                  (param_name, comment_block.name, original_line, marker),
                                  position)
diff --git a/giscanner/maintransformer.py b/giscanner/maintransformer.py
index a7ca221..6ffec2f 100644
--- a/giscanner/maintransformer.py
+++ b/giscanner/maintransformer.py
@@ -705,9 +705,6 @@ class MainTransformer(object):
         unused = declparams - docparams
 
         for doc_name in unknown:
-            # Skip varargs, see #629759
-            if doc_name.lower() in ['...', 'varargs']:
-                continue
             if len(unused) == 0:
                 text = ''
             elif len(unused) == 1:
diff --git a/tests/scanner/Makefile.am b/tests/scanner/Makefile.am
index e1eb433..0957a5f 100644
--- a/tests/scanner/Makefile.am
+++ b/tests/scanner/Makefile.am
@@ -226,6 +226,7 @@ EXTRA_DIST += \
        annotationparser/gi/identifier_section.xml              \
        annotationparser/gi/identifier_symbol.xml               \
        annotationparser/gi/parameter.xml                       \
+       annotationparser/gi/parameter_varargs.xml               \
        annotationparser/gi/syntax.xml                          \
        annotationparser/gi/syntax_nested_tags.xml              \
        annotationparser/gi/syntax_paragraph_breaks.xml         \
diff --git a/tests/scanner/annotationparser/gi/parameter_varargs.xml 
b/tests/scanner/annotationparser/gi/parameter_varargs.xml
new file mode 100644
index 0000000..7eb6236
--- /dev/null
+++ b/tests/scanner/annotationparser/gi/parameter_varargs.xml
@@ -0,0 +1,236 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<tests xmlns="http://schemas.gnome.org/gobject-introspection/2013/test";>
+
+<test>
+  <input>/**
+ * function_name:
+ * @par1:  description of parameter 1. These can extend over more than
+ * one line.
+ * @par2:  description of parameter 2
+ * @...: a %NULL-terminated list of bars
+ *
+ * The function description goes here. You can use @par1 to refer to parameters
+ * so that they are highlighted in the output. You can also use %constant
+ * for constants, function_name2() for functions and #GtkWidget for links to
+ * other declarations (which may be documented elsewhere).
+ *
+ * Returns: an integer.
+ *
+ * Since: 2.2
+ * Deprecated: 2.18: Use other_function() instead.
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>function_name</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>par1</name>
+          <description>description of parameter 1. These can extend over more than one line.</description>
+        </parameter>
+        <parameter>
+          <name>par2</name>
+          <description>description of parameter 2</description>
+        </parameter>
+        <parameter>
+          <name>...</name>
+          <description>a %NULL-terminated list of bars</description>
+        </parameter>
+      </parameters>
+      <description>The function description goes here. You can use @par1 to refer to parameters
+so that they are highlighted in the output. You can also use %constant
+for constants, function_name2() for functions and #GtkWidget for links to
+other declarations (which may be documented elsewhere).</description>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <description>an integer.</description>
+        </tag>
+        <tag>
+          <name>since</name>
+          <description>2.2</description>
+        </tag>
+        <tag>
+          <name>deprecated</name>
+          <description>2.18: Use other_function() instead.</description>
+        </tag>
+      </tags>
+    </docblock>
+  </parser>
+</test>
+
+<test>
+  <!--
+  gtkdoc-mkdb has deprecated named __VA_ARGS__ parameter notation.
+  But there is a gcc CPP extension that, for macros, makes it possible to give a more descriptive
+  name for the variable argument than simply __VA_ARGS__. See
+  http://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html for more information.
+  Encountered in the wild in for example:
+  
http://git.kernel.org/?p=bluetooth/bluez.git;a=blob;f=src/log.h;h=3d34fa3774e5400c030d29a264824fe0584de2a8;hb=HEAD#l44
+  -->
+  <input>/**
+ * DBG:
+ * @fmt: format string
+ * @arg...: list of arguments
+ *
+ * Simple macro around btd_debug() which also include the function
+ * name it is called in.
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>DBG</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>fmt</name>
+          <description>format string</description>
+        </parameter>
+        <parameter>
+          <name>...</name>
+          <description>list of arguments</description>
+        </parameter>
+      </parameters>
+      <description>Simple macro around btd_debug() which also include the function
+name it is called in.</description>
+    </docblock>
+    <messages>
+      <message>4: Warning: Test: "@arg..." parameter is deprecated, please use "@..." instead:
+ * @arg...: list of arguments
+    ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated @Vargargs parameter
+  -->
+  <input>/**
+ * function_name:
+ * @par1:  description of parameter 1. These can extend over more than
+ * one line.
+ * @par2:  description of parameter 2
+ * @Varargs: a %NULL-terminated list of bars
+ *
+ * The function description goes here. You can use @par1 to refer to parameters
+ * so that they are highlighted in the output. You can also use %constant
+ * for constants, function_name2() for functions and #GtkWidget for links to
+ * other declarations (which may be documented elsewhere).
+ *
+ * Returns: an integer.
+ *
+ * Since: 2.2
+ * Deprecated: 2.18: Use other_function() instead.
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>function_name</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>par1</name>
+          <description>description of parameter 1. These can extend over more than one line.</description>
+        </parameter>
+        <parameter>
+          <name>par2</name>
+          <description>description of parameter 2</description>
+        </parameter>
+        <parameter>
+          <name>...</name>
+          <description>a %NULL-terminated list of bars</description>
+        </parameter>
+      </parameters>
+      <description>The function description goes here. You can use @par1 to refer to parameters
+so that they are highlighted in the output. You can also use %constant
+for constants, function_name2() for functions and #GtkWidget for links to
+other declarations (which may be documented elsewhere).</description>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <description>an integer.</description>
+        </tag>
+        <tag>
+          <name>since</name>
+          <description>2.2</description>
+        </tag>
+        <tag>
+          <name>deprecated</name>
+          <description>2.18: Use other_function() instead.</description>
+        </tag>
+      </tags>
+    </docblock>
+    <messages>
+      <message>6: Warning: Test: "@Varargs" parameter is deprecated, please use "@..." instead:
+ * @Varargs: a %NULL-terminated list of bars
+    ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Normal @vargargs parameter (usually seen for va_list)
+  -->
+  <input>/**
+ * function_name:
+ * @par1:  description of parameter 1. These can extend over more than
+ * one line.
+ * @par2:  description of parameter 2
+ * @varargs: a %NULL-terminated list of bars
+ *
+ * The function description goes here. You can use @par1 to refer to parameters
+ * so that they are highlighted in the output. You can also use %constant
+ * for constants, function_name2() for functions and #GtkWidget for links to
+ * other declarations (which may be documented elsewhere).
+ *
+ * Returns: an integer.
+ *
+ * Since: 2.2
+ * Deprecated: 2.18: Use other_function() instead.
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>function_name</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>par1</name>
+          <description>description of parameter 1. These can extend over more than one line.</description>
+        </parameter>
+        <parameter>
+          <name>par2</name>
+          <description>description of parameter 2</description>
+        </parameter>
+        <parameter>
+          <name>varargs</name>
+          <description>a %NULL-terminated list of bars</description>
+        </parameter>
+      </parameters>
+      <description>The function description goes here. You can use @par1 to refer to parameters
+so that they are highlighted in the output. You can also use %constant
+for constants, function_name2() for functions and #GtkWidget for links to
+other declarations (which may be documented elsewhere).</description>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <description>an integer.</description>
+        </tag>
+        <tag>
+          <name>since</name>
+          <description>2.2</description>
+        </tag>
+        <tag>
+          <name>deprecated</name>
+          <description>2.18: Use other_function() instead.</description>
+        </tag>
+      </tags>
+    </docblock>
+  </parser>
+</test>
+
+</tests>