[gtk-doc] mkdb: add support for multiline symbol annotations

[Stefan Kost <stefkost src gnome org>]

commit b73f5a36137a4a4b759b9f037439f8a53210b5f9
Author: Stefan Sauer <ensonic users sf net>
Date:   Fri Apr 17 15:45:26 2015 +0200

    mkdb: add support for multiline symbol annotations
    
    We support the syntax suggested in
    https://bugzilla.gnome.org/show_bug.cgi?id=676133#c26
    Fixes #676133

 gtkdoc-mkdb.in                             |   10 +++++++++-
 tests/annotations/docs/tester-sections.txt |    2 ++
 tests/annotations/src/tester.c             |   19 +++++++++++++++++++
 tests/annotations/src/tester.h             |    3 +++
 4 files changed, 33 insertions(+), 1 deletions(-)
---
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index 3ac7a6d..e736fb7 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -2233,7 +2233,9 @@ sub OutputFunction {
     if (defined ($SymbolAnnotations{$symbol})) {
       my $param_desc = $SymbolAnnotations{$symbol};
       my $param_annotations = "";
+      @TRACE@("expand annotation for $symbol: $param_desc");
       ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc);
+      @TRACE@("expanded annotation for $symbol: $param_desc | $param_annotations");
       if ($param_annotations ne "") {
          $desc .= "\n<para>$param_annotations</para>";
       }
@@ -2831,7 +2833,7 @@ sub ExpandAnnotation {
 
     # look for annotations at the start of the comment part
     # function level annotations don't end with a colon ':'
-    if ($param_desc =~ m%^\s*\((.*?)\):?%) {
+    if ($param_desc =~ m%^\s*\((.*?)\)(:|$)%) {
         my @annotations;
         my $annotation;
         $param_desc = $';
@@ -4151,7 +4153,13 @@ sub ScanSourceFile {
             push (@params, $param_name);
             push (@params, $param_desc);
             $current_param += $PARAM_FIELD_COUNT;
+            $in_part = "param";
             next;
+        } elsif ($in_part eq "") {
+            @TRACE@("continuation for $symbol annotation '$_'");
+            my $annotation = $_;
+            $annotation =~ s/^\s+|\s+$//g ; 
+            $SymbolAnnotations{$symbol} .= $annotation;
         }
 
         # We must be in the middle of a parameter description, so add it on
diff --git a/tests/annotations/docs/tester-sections.txt b/tests/annotations/docs/tester-sections.txt
index f540b9e..81b3ccf 100644
--- a/tests/annotations/docs/tester-sections.txt
+++ b/tests/annotations/docs/tester-sections.txt
@@ -17,6 +17,8 @@ annotation_skip_return
 annotation_scope
 annotation_rename_to
 stability_unstable
+annotation_multiline_on_function
+annotation_multiline_on_function2
 <SUBSECTION Standard>
 <SUBSECTION Private>
 </SECTION>
diff --git a/tests/annotations/src/tester.c b/tests/annotations/src/tester.c
index d9d8eba..cf193cf 100644
--- a/tests/annotations/src/tester.c
+++ b/tests/annotations/src/tester.c
@@ -221,3 +221,22 @@ stability_unstable(void)
 {
 }
 
+/**
+ * annotation_multiline_on_function: (rename-to annotation_scope)
+ *                                   (skip)
+ *
+ * Documentation for this function.
+ */
+void annotation_multiline_on_function (void)
+{
+}
+
+/**
+ * annotation_multiline_on_function2:
+ * (rename-to annotation_scope)(skip)
+ *
+ * Documentation for this function.
+ */
+void annotation_multiline_on_function2 (void)
+{
+}
\ No newline at end of file
diff --git a/tests/annotations/src/tester.h b/tests/annotations/src/tester.h
index 677606a..33437dc 100644
--- a/tests/annotations/src/tester.h
+++ b/tests/annotations/src/tester.h
@@ -37,5 +37,8 @@ void annotation_rename_to (void);
 
 void stability_unstable(void);
 
+void annotation_multiline_on_function (void);
+void annotation_multiline_on_function2 (void);
+
 #endif // GTKDOC_TESTER_H