From ceb84d1e084b8048b2abb81d1e1ebe600f00d00e Mon Sep 17 00:00:00 2001
From: Dieter Verfaillie <dieterv@optionexplicit.be>
Date: Sat, 1 Dec 2012 16:02:01 +0100
Subject: [PATCH] scanner: Parse comments with */ not on a new line, but emit a
 warning

We don't know how many apps do this, but at least ibus had one.

https://bugzilla.gnome.org/show_bug.cgi?id=689354
---
 giscanner/annotationparser.py                   | 25 +++++++++++++++++----
 tests/scanner/annotationparser/gi/syntax.xml    | 17 +++++++++++---
 tests/scanner/annotationparser/test_patterns.py | 30 ++++++++++++++++++++++++-
 tests/warn/annotationparser.h                   | 11 +++++++++
 4 files changed, 75 insertions(+), 8 deletions(-)

diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py
index e91df3a..f545590 100644
--- a/giscanner/annotationparser.py
+++ b/giscanner/annotationparser.py
@@ -151,14 +151,20 @@ COMMENT_START_RE = re.compile(r'''
     ''',
     re.VERBOSE)
 
-# Program matching the end of a comment block.
+# Program matching the end of a comment block. We need to take care
+# of comment ends that aren't on their own line for legacy support
+# reasons. See https://bugzilla.gnome.org/show_bug.cgi?id=689354
 #
-# Results in 0 symbolic groups.
+# Results in 1 symbolic group:
+#    - group 1 = description
 COMMENT_END_RE = re.compile(r'''
     ^                                        # start
     [^\S\n\r]*                               # 0 or more whitespace characters
+    (?P<description>.*?)                     # description text
+    [^\S\n\r]*                               # 0 or more whitespace characters
     \*+                                      # 1 or more asterisk characters
     /                                        # 1 forward slash character
+    [^\S\n\r]*                               # 0 or more whitespace characters
     $                                        # end
     ''',
     re.VERBOSE)
@@ -801,8 +807,19 @@ class AnnotationParser(object):
             return None
 
         # Check for the end the comment block.
-        if COMMENT_END_RE.match(comment_lines[-1][1]):
-            del comment_lines[-1]
+        line_offset, line = comment_lines[-1]
+        result = COMMENT_END_RE.match(line)
+        if result:
+            description = result.group('description')
+            if description:
+                comment_lines[-1] = (line_offset, description)
+                position = message.Position(filename, lineno + line_offset)
+                marker = ' '*result.end('description') + '^'
+                message.warn("Comments should end with */ on a new line:\n%s\n%s" %
+                             (line, marker),
+                             position)
+            else:
+                del comment_lines[-1]
         else:
             # Not a GTK-Doc comment block.
             return None
diff --git a/tests/scanner/annotationparser/gi/syntax.xml b/tests/scanner/annotationparser/gi/syntax.xml
index c97bd5b..83c56b9 100644
--- a/tests/scanner/annotationparser/gi/syntax.xml
+++ b/tests/scanner/annotationparser/gi/syntax.xml
@@ -71,23 +71,34 @@ something */</commentblock>
 
 <test>
   <!--
-  Not GTK-Doc
+  Technically not GTK-Doc, but we need to support this for backwards compatibility
   -->
   <commentblock>/**
 Test
 something */</commentblock>
+  <docblock>
+    <identifier>
+      <name>Test</name>
+    </identifier>
+    <description>something</description>
+  </docblock>
 </test>
 
 <test>
   <!--
-  Not GTK-Doc
+  Technically not GTK-Doc, but we need to support this for backwards compatibility
   -->
   <commentblock>/**
 Test
 something **/</commentblock>
+  <docblock>
+    <identifier>
+      <name>Test</name>
+    </identifier>
+    <description>something</description>
+  </docblock>
 </test>
 
-
 <test>
   <!--
   Broken comment block, signal the start of the comment block description followed
diff --git a/tests/scanner/annotationparser/test_patterns.py b/tests/scanner/annotationparser/test_patterns.py
index 2755cc9..6db99c3 100644
--- a/tests/scanner/annotationparser/test_patterns.py
+++ b/tests/scanner/annotationparser/test_patterns.py
@@ -32,7 +32,8 @@ against the expected output.
 
 
 from giscanner.annotationparser import (SECTION_RE, SYMBOL_RE, PROPERTY_RE,
-                                        SIGNAL_RE, PARAMETER_RE, TAG_RE)
+                                        SIGNAL_RE, PARAMETER_RE, TAG_RE,
+                                        COMMENT_END_RE)
 from unittest import (TestCase, main)
 
 
@@ -544,6 +545,32 @@ tag_tests = [
           'colon': ':',
           'description': ''})]
 
+comment_end_tests = [
+    (COMMENT_END_RE, '*/',
+         {'description': ''}),
+    (COMMENT_END_RE, '   */',
+         {'description': ''}),
+    (COMMENT_END_RE, ' */ ',
+         {'description': ''}),
+    (COMMENT_END_RE, '**/',
+         {'description': ''}),
+    (COMMENT_END_RE, ' **/',
+         {'description': ''}),
+    (COMMENT_END_RE, ' **/ ',
+         {'description': ''}),
+    (COMMENT_END_RE, 'test */',
+         {'description': 'test'}),
+    (COMMENT_END_RE, ' test*/',
+         {'description': 'test'}),
+    (COMMENT_END_RE, 'test **/',
+         {'description': 'test'}),
+    (COMMENT_END_RE, ' test**/',
+         {'description': 'test'}),
+    (COMMENT_END_RE, 'test *****/',
+         {'description': 'test'}),
+    (COMMENT_END_RE, ' test*****/',
+         {'description': 'test'})]
+
 
 def create_tests(tests_name, testcases):
     for (index, testcase) in enumerate(testcases):
@@ -585,6 +612,7 @@ if __name__ == '__main__':
     create_tests('test_identifier_signal', identifier_signal_tests)
     create_tests('test_parameter', parameter_tests)
     create_tests('test_tag', tag_tests)
+    create_tests('test_comment_end', comment_end_tests)
 
     # Run test suite
     main()
diff --git a/tests/warn/annotationparser.h b/tests/warn/annotationparser.h
index ff9030e..dba6971 100644
--- a/tests/warn/annotationparser.h
+++ b/tests/warn/annotationparser.h
@@ -203,3 +203,14 @@ void test_symbol_twice_documented();
 // EXPECT:195: Warning: Test: ignoring unrecognized GTK-Doc comment block, identifier not found:
 //+
 //+^
+
+/**
+ * regress_test_invalid_comment_end:
+ * @foo: a param
+ *
+ * invalid comment with a line without
+ * https://bugzilla.gnome.org/show_bug.cgi?id=689354 */
+
+// EXPECT:212: Warning: Test: Comments should end with */ on a new line:
+//+ * https://bugzilla.gnome.org/show_bug.cgi?id=689354 */
+//+                                                    ^
-- 
2.7.4