gmmproc: Improve the conversion of documentation to Doxygen format.

* tools/defs_gen/docextract.py: Handle 'Since ' without a colon.
* tools/m4/signal.m4:
* tools/pm/Output.pm: When a function declaration is surrounded by
ifdef/endif, put its documentation inside the ifdef/endif.
* tools/pm/DocsParser.pm: Handle 'Since ' without a colon. Escape most
backslashes, not just \r and \n. Convert more <tags> to something that
Doxygen understands.

2 files changed, 56 insertions, 23 deletions

diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index c9436bba..87fcdfda 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -474,37 +474,40 @@ sub convert_tags_to_doxygen($)
   for($$text)
   {
     # Replace format tags.
-    s"<(/?)emphasis>"<$1em>"g;
-    s"<(/?)literal>"<$1tt>"g;
-    s"<(/?)constant>"<$1tt>"g;
-    s"<(/?)function>"<$1tt>"g;
+    s"<(/?)(?:emphasis|replaceable)>"<$1em>"g;
+    s"<(/?)(?:constant|envar|filename|function|guimenuitem|literal|option|structfield|varname)>"<$1tt>"g;
 
     # Some argument names are suffixed by "_" -- strip this.
     # gtk-doc uses @thearg, but doxygen uses @a thearg.
     s" ?\@([a-zA-Z0-9]*(_[a-zA-Z0-9]+)*)_?\b" \@a $1"g;
 
-    # Don't convert doxygen's @throws and @param, so these can be used in the
-    # docs_override.xml:
-    s" \@a (throws|param)" \@$1"g;
-    s"^Note ?\d?: "\@note "mg;
+    # Don't convert Doxygen's $throw, @throws and @param, so these can be used
+    # in the docs_override.xml.
+    s" \@a (throws?|param)\b" \@$1"g;
 
+    s"^Note ?\d?: "\@note "mg;
     s"</?programlisting>""g;
-
     s"<!>""g;
 
     # Remove all link tags.
     s"</?u?link[^&]*?>""g;
 
-    # Remove all para tags (from tmpl sgml files).
-    s"</?para>""g;
+    # Remove all para tags and simpara tags (simple paragraph).
+    s"</?(sim)?para>""g;
 
-    # Convert <itemizedlist> tags to Doxygen format.
-    s"</?itemizedlist>\n?""g;
-    s"<listitem>(.*?)(\n?)</listitem>(\n?)"- $1\n"sg;
+    # Convert <simplelist>, <itemizedlist> and <variablelist> to something that
+    # Doxygen understands.
+    s"<simplelist>\n?(.*?)</simplelist>\n?"&DocsParser::convert_simplelist($1)"esg;
+    s"<itemizedlist>\n?(.*?)</itemizedlist>\n?"&DocsParser::convert_itemizedlist($1)"esg;
+    s"<variablelist>\n?(.*?)</variablelist>\n?"&DocsParser::convert_variablelist($1)"esg;
 
-    # Use our Doxygen @newin alias:
-    s/\bSince:\s*(\d+)\.(\d+)\.(\d+)\b/\@newin{$1,$2,$3}/g;
-    s/\bSince:\s*(\d+)\.(\d+)\b/\@newin{$1,$2}/g;
+    # 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;
 
@@ -519,11 +522,41 @@ sub convert_tags_to_doxygen($)
     s"#?\bg(int|short|long)\b"<tt>$1</tt>"g;
     s"#?\bgu(int|short|long)\b"<tt>unsigned $1</tt>"g;
 
-    # For Gtk::TextIter.
-    s"(\\[rn])\b"<tt>\\$1</tt>"g;
+    # Escape all backslashes, except in \throw, \throws and \param, which can
+    # be Doxygen commands in the docs_override.xml.
+    s"\\"\\\\"g;
+    s"\\\\(throws?|param)\b"\\$1"g
   }
 }
 
+# Convert <simplelist> tags to a list of newline-separated elements.
+sub convert_simplelist($)
+{
+  my ($text) = @_;
+
+  $text =~ s"<member>(.*?)(\n?)</member>(\n?)"$1<br>\n"sg;
+  return "<br>\n" . $text . "<br>\n";
+}
+
+# Convert <itemizedlist> tags to Doxygen format.
+sub convert_itemizedlist($)
+{
+  my ($text) = @_;
+
+  $text =~ s"<listitem>(.*?)(\n?)</listitem>(\n?)"- $1\n"sg;
+  return $text;
+}
+
+# Convert <variablelist> tags to an HTML definition list.
+sub convert_variablelist($)
+{
+  my ($text) = @_;
+
+  $text =~ s"</?varlistentry>\n?""g;
+  $text =~ s"<(/?)term>"<$1dt>"g;
+  $text =~ s"<(/?)listitem>"<$1dd>"g;
+  return "<dl>\n" . $text . "</dl>\n";
+}
 
 sub substitute_identifiers($$)
 {
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index 7a03dcec..3300e8c0 100644
--- a/tools/pm/Output.pm
+++ b/tools/pm/Output.pm
@@ -118,6 +118,8 @@ sub output_wrap_vfunc_h($$$$$$)
 #   );
 #  $self->append($str);
 
+  $self->ifdef($ifdef);
+
   # Prepend a Doxygen @throws directive to the declaration if the virtual
   # function throws an error.
   if($$objCDefsFunc{throw_any_errors})
@@ -131,7 +133,6 @@ sub output_wrap_vfunc_h($$$$$$)
     $cppVfuncDecl .= " const";
   }
 
-  $self->ifdef($ifdef);
   $self->append("  $cppVfuncDecl;\n");
   $self->endif($ifdef);
 
@@ -355,6 +356,8 @@ sub output_wrap_meth($$$$$$$)
       $self->append("\n_DEPRECATE_IFDEF_START");
     }
 
+    $self->ifdef($ifdef);
+
     if($arg_list == 0)
     {
       # Doxygen documentation before the method declaration:
@@ -365,13 +368,10 @@ sub output_wrap_meth($$$$$$$)
       $self->append("\n\n  /// A $$objCppfunc{name}() convenience overload.\n");
     }
 
-    $self->ifdef($ifdef);
-
     $self->append("  " . $objCppfunc->get_declaration($arg_list));
 
     $self->endif($ifdef);
 
-
     if($deprecated ne "")
     {
       $self->append("\n_DEPRECATE_IFDEF_END\n");