GNOME.org
 

[glibmm] gmmproc: Improve the conversion of documentation to Doxygen format.

commit 0513b1e520c267f700a0492014c6a7a845403690
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Tue Jan 29 10:18:11 2013 +0100

    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.

 ChangeLog                    |   12 +++++++
 tools/defs_gen/docextract.py |   33 ++++++++++++++++---
 tools/m4/signal.m4           |    2 +-
 tools/pm/DocsParser.pm       |   71 ++++++++++++++++++++++++++++++-----------
 tools/pm/Output.pm           |    8 ++--
 5 files changed, 97 insertions(+), 29 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 5f4cfca..d1692fd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2013-01-29  Kjell Ahlstedt  <kjell ahlstedt bredband net>
+
+	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.
+
 2013-01-27  Kjell Ahlstedt  <kjell ahlstedt bredband net>
 
 	Documentation: Fix many warnings from Doxygen.
diff --git a/tools/defs_gen/docextract.py b/tools/defs_gen/docextract.py
index 19204de..8b0b690 100644
--- a/tools/defs_gen/docextract.py
+++ b/tools/defs_gen/docextract.py
@@ -89,6 +89,13 @@ identifier_patterns = [ signal_name_pattern, property_name_pattern, enum_name_pa
 no_colon_return_pattern = re.compile(r'^ ?(returns|return\s+value)\s*(.*\n?)$', re.IGNORECASE)
 since_pattern = re.compile(r'^(since\s*:\s*.*\n?)$', re.IGNORECASE)
 
+# This pattern is to match since sections that forget to have a colon (':')
+# after the initial 'Since' phrase.  It is not included by default in the list
+# of final sections below because some function descriptions contain
+# 'Since ...' and the process_description() function would stop at that
+# line, thinking it is a since section.
+no_colon_since_pattern = re.compile(r'^Since\s+[.0-9]+\n?$')
+
 # These patterns normally will be encountered after the description.  Knowing
 # the order of their appearance is difficult so this list is used to test when
 # one begins and the other ends when processing the rest of the sections after
@@ -317,7 +324,12 @@ def process_description(fp, line, cur_doc):
                 return line
 
         # If not, append lines to description in the doc comment block.
-        cur_doc.append_to_description(line)
+        # But if --no-since is specified, skip a no_colon_since_pattern line.
+        if no_since and \
+                no_colon_since_pattern.match(line) and prev_line == '\n':
+            pass
+        else:
+            cur_doc.append_to_description(line)
 
         prev_line = line
         line = fp.readline()
@@ -336,6 +348,12 @@ def process_description(fp, line, cur_doc):
 # sections) process the final sections ('Returns:', 'Since:', etc.) until the
 # end of the comment block or eof.  Return the line that ends the processing.
 def process_final_sections(fp, line, cur_doc):
+    # Temporarily append the no_colon_since_pattern to the final section
+    # patterns now that the description has been processed.  It will be
+    # removed at the end of this function so that future descriptions
+    # that begin with 'Since ...' are not interpreted as a since section.
+    final_section_patterns.append(no_colon_since_pattern)
+
     while line and not comment_end_pattern.match(line):
         # Remove leading ' * ' from current non-empty comment line.
         line = comment_line_lead_pattern.sub('', line)
@@ -374,10 +392,11 @@ def process_final_sections(fp, line, cur_doc):
                     cur_doc.add_annotation((match.group(1),
                             match.group(2)))
                 else:
-                    # For all others ('Since:' and 'Deprecated:') just append
-                    # the line to the description for now.
-                    # But if --no-since is specified, don't append it.
-                    if no_since and pattern == since_pattern:
+                    # For all others ('Since:', 'Since ' and 'Deprecated:')
+                    # just append the line to the description for now.
+                    # But if --no-since is specified, skip a Since line.
+                    if no_since and (pattern == since_pattern or \
+                            pattern == no_colon_since_pattern):
                         pass
                     else:
                         cur_doc.append_to_description(line)
@@ -420,6 +439,10 @@ def process_final_sections(fp, line, cur_doc):
             # Get the next line to continue processing.
             line = fp.readline()
 
+    # Remove the no_colon_since_pattern (which was temporarily added at
+    # the beginning of this function) from the list of final section patterns.
+    final_section_patterns.pop()
+
     return line
 
 def parse_dir(dir, doc_dict):
diff --git a/tools/m4/signal.m4 b/tools/m4/signal.m4
index 4671948..f9802eb 100644
--- a/tools/m4/signal.m4
+++ b/tools/m4/signal.m4
@@ -16,11 +16,11 @@ dnl               $10 = `refdoc_comment',
 dnl               $11 = ifdef)
 
 define(`_SIGNAL_PROXY',`
-$10
 ifelse(`$11',,,`#ifdef $11'
 )dnl
 ifelse(`$9',,,`_DEPRECATE_IFDEF_START
 ')dnl
+$10
   Glib::SignalProxy`'_NUM($6)< $5`'_COMMA_PREFIX($6) > signal_$4`'();
 ifelse(`$9',,,`_DEPRECATE_IFDEF_END
 ')dnl
diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index c9436bb..87fcdfd 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 7a03dce..3300e8c 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");
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]