gmmproc: Improve the conversion of Since to @newin

* tools/m4/enum.m4: Add a blank line in the enum documentation.
* tools/pm/Output.pm: Don't always add a blank line in the enum documentation.
* tools/pm/DocsParser.pm: Improve the rules for conversion of Since to @newin.

3 files changed, 17 insertions, 9 deletions

diff --git a/tools/m4/enum.m4 b/tools/m4/enum.m4
index 3ac338b2..dc988925 100644
--- a/tools/m4/enum.m4
+++ b/tools/m4/enum.m4
@@ -1,5 +1,6 @@
 dnl
 dnl _ENUM(cpp_type, c_type, value_suffix, `element_list', `flags', `optional_refdoc_comment', 'get_type_function_name')
+dnl          $1       $2         $3             $4           $5              $6                        $7
 dnl
 m4_define(`_ENUM',`dnl
 _PUSH()
@@ -20,6 +21,7 @@ m4_define(`__DOCGROUP_'__MODULE_CANONICAL__`_ENUMS__')dnl
 dnl
 dnl
 /** $6
+ *
  * @ingroup __MODULE_CANONICAL__`'Enums
 m4_ifelse($3,Flags,`dnl
  * @par Bitwise operators:
diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index 1997945e..3ffee0ed 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -514,14 +514,20 @@ sub convert_tags_to_doxygen($)
     s"<variablelist>\n?(.*?)</variablelist>\n?"&DocsParser::convert_variablelist($1)"esg;
 
     # Use our Doxygen @newin alias.
-    # If Since is not followed by a colon, substitute @newin only if it's
-    # in a sentence of its own at the end of the string. 
-    s/\bSince:\s*(\d+)\.(\d+)\.(\d+)\b\.?/\@newin{$1,$2,$3}/g;
-    s/\bSince:\s*(\d+)\.(\d+)\b\.?/\@newin{$1,$2}/g;
-    s/(\.\s+)Since\s+(\d+)\.(\d+)\.(\d+)\.?$/$1\@newin{$2,$3,$4}/;
-    s/(\.\s+)Since\s+(\d+)\.(\d+)\.?$/$1\@newin{$2,$3}/;
-
-    s"\b->\b"->"g;
+    # Accept "Since" with or without a following colon.
+    # Require the Since clause to be
+    # - at the end of the string,
+    # - at the end of a line and followed by a blank line, or
+    # - followed by "Deprecated".
+    # If none of these requirements is met, "Since" may be embedded inside
+    # a function description, referring to only a part of the description.
+    # See e.g. g_date_time_format() and gdk_cursor_new_from_pixbuf().
+    # Doxygen assumes that @newin is followed by a paragraph that describes
+    # what is new, but we don't use it that way.
+    my $first_part = '\bSince[:\h]\h*(\d+)\.(\d+)'; # \h == [\t ] (horizontal whitespace)
+    my $last_part = '\.?(\s*$|\h*\n\h*\n|\s+Deprecated)';
+    s/$first_part\.(\d+)$last_part/\@newin{$1,$2,$3}$4/g;
+    s/$first_part$last_part/\@newin{$1,$2}$3/g;
 
     # Doxygen is too dumb to handle &mdash;
     s"&mdash;" \@htmlonly&mdash;\@endhtmlonly "g;
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index de13f5ea..1b12f4e6 100644
--- a/tools/pm/Output.pm
+++ b/tools/pm/Output.pm
@@ -679,7 +679,7 @@ sub output_wrap_enum($$$$$$$)
     DocsParser::lookup_enum_documentation("$c_type", "$cpp_type", " ", \@flags);
 
   # Merge the passed in comment to the existing enum documentation.
-  $comment = $comment . "\n * " . $enum_docs;
+  $comment .= "\n * " . $enum_docs if $enum_docs ne "";
 
   my $str = sprintf("_ENUM(%s,%s,%s,\`%s\',\`%s\',\`%s\')dnl\n",
     $cpp_type,