GNOME.org
 

[glibmm] gmmproc: Add _WRAP_ENUM_DOCS_ONLY() and simplify enum docs process.

commit 9b7a4076b50a862459a85fb0be4c7afdb26a3ef9
Author: José Alburquerque <jaalburquerque gmail com>
Date:   Sun Jun 30 17:49:32 2013 -0400

    gmmproc: Add _WRAP_ENUM_DOCS_ONLY() and simplify enum docs process.
    
        * tools/pm/DocsParser.pm (lookup_enum_documentation): Renamed from
        lookup_enum_description().  This subroutine now produces the entire
        Doxygen enum documentation block.
        (lookup_enum_value_documentation): Removed this subroutine because
        it's been merged into the above one.
        (convert_tags_to_doxygen): Don't convert the Doxygen @enum and @var
        tags because they appear in the enum documentation obtained from the
        subroutine above.
        * tools/pm/Enum.pm (build_element_list): Remove the lines that insert
        the Doxygen documentation individually for each of the members of the
        enum because the enum member documentation is already included by the
        lookup_enum_documentation() subroutine above.
        * tools/pm/Output.pm (output_wrap_enum): Modified to use the above
        lookup_enum_documentation() subroutine.
        (output_wrap_enum_docs_only): Added this subroutine that outputs an
        enum's Doxygen documentation block if the enum's documentation exists.
        This is useful for complexly defined C enums (using C macros, for
        example) that can't presently be wrapped with _WRAP_ENUM() and must be
        handwritten but outputting their documentation is still desired.
        (output_wrap_failed): Also produce the source file which caused a
        _WRAP_* to fail so that it is clear where the error is.
        * tools/pm/WrapParser.pm (parse_and_build_output): Also check for a
        _WRAP_ENUM_DOCS_ONLY() so it can be processed.
        (on_wrap_enum_docs_only): Called by the parse_and_build_output()
        subroutine above when a _WRAP_ENUM_DOCS_ONLY() is found.
    
        Bug #703155.

 tools/pm/DocsParser.pm |  105 +++++++++++++++++++++++++----------------------
 tools/pm/Enum.pm       |   16 -------
 tools/pm/Output.pm     |   47 ++++++++++++++++++---
 tools/pm/WrapParser.pm |   27 ++++++++++++
 4 files changed, 123 insertions(+), 72 deletions(-)
---
diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index b645c33..db23b7e 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -233,76 +233,82 @@ sub parse_on_cdata($$)
   }
 }
 
-
-# $text lookup_enum_description($enum_name)
-# Looks up the description of enum and returns it after converting it from
-# C to C++ format.
-sub lookup_enum_description($)
+sub lookup_enum_documentation($$$)
 {
-  my ($enum_name) = @_;
+  my ($c_enum_name, $cpp_enum_name, $ref_flags) = @_;
+  
+  my @subst_in  = [];
+  my @subst_out = [];
+ 
+ # Get the substitutions.
+  foreach(@$ref_flags)
+  {
+    if(/^\s*s#([^#]+)#([^#]*)#\s*$/)
+    {
+      push(@subst_in,  $1);
+      push(@subst_out, $2);
+    }
+  }
 
-  my $objFunction = $DocsParser::hasharrayFunctions{$enum_name};
+  my $objFunction = $DocsParser::hasharrayFunctions{$c_enum_name};
   if(!$objFunction)
   {
     #print "DocsParser.pm: Warning: enum not found: $enum_name\n";
     return ""
   }
 
-  my $text = $$objFunction{description};
-
-  if(length($text) eq 0)
-  {
-    print "DocsParser.pm: Warning: No C docs for: \"$enum_name\"\n";
-    return "";
-  }
-
-  DocsParser::convert_docs_to_cpp($objFunction, \$text);
-  DocsParser::add_m4_quotes(\$text);
-
-  # Escape the space after "i.e." or "e.g." in the brief description.
-  $text =~ s/^([^.]*\b(?:i\.e\.|e\.g\.))\s/$1\\ /;
+  my $docs = "";
 
-  remove_example_code($enum_name, \$text);
+  my @param_names = @{$$objFunction{param_names}};
+  my $param_descriptions = \$$objFunction{param_descriptions};
 
-  return $text;
-}
+  # Append the param docs first so that the enum description can come last and
+  # the possible flag docs that the m4 _ENUM() macro appends goes in the right
+  # place.
+  foreach my $param (@param_names)
+  {
+    my $desc = $$param_descriptions->{$param};
 
-# $strCommentBlock lookup_enum_value_documentation($enum_name, $c_val_name)
-# Returns a Doxygen comment block for the enum value.
-sub lookup_enum_value_documentation($$)
-{
-  my ($enum_name, $c_val_name) = @_;
+    # Remove the initial prefix which would be something like GTK_.
+    $param =~ s/\b[A-Z]+_//g;
+    $desc =~ s/\b[A-Z]+_//g;
 
-  # Assume that there is no description.
-  my $desc = "";
+    # Now apply custom substitutions.
+    for(my $i = 0; $i < scalar(@subst_in); ++$i)
+    {
+      $param  =~ s/${subst_in[$i]}/${subst_out[$i]}/;
+      $desc =~ s/${subst_in[$i]}/${subst_out[$i]}/;
+    }
 
-  my $obj_function = $DocsParser::hasharrayFunctions{$enum_name};
+    # Skip this element, if its name has been deleted.
+    next if($param eq "");
 
-  if($obj_function)
-  {
-    my $param_descriptions = \$$obj_function{param_descriptions};
-    $desc = $$param_descriptions->{$c_val_name};
+    $param =~ s/([a-zA-Z0-9]*(_[a-zA-Z0-9]+)*)_?/$1/g;
+    if(length($desc) > 0)
+    {
+      $desc =~ s/\n//g;
+      $desc  .= '.' unless($desc =~ /(?:^|\.)$/);
+      $docs .= "\ var $cpp_enum_name ${param}\n\u${desc}\n\n";
+    }
   }
 
-  if(!$desc or length($desc) eq 0)
-  {
-    return "";
-  }
+  # Append the enum description docs.
+  $docs .= "\ enum $cpp_enum_name\n"; 
+  $docs .= $$objFunction{description};
 
-  DocsParser::convert_docs_to_cpp($obj_function, \$desc);
-  DocsParser::add_m4_quotes(\$desc);
+  DocsParser::convert_docs_to_cpp($objFunction, \$docs);
+  DocsParser::add_m4_quotes(\$docs);
 
   # Escape the space after "i.e." or "e.g." in the brief description.
-  $desc =~ s/^([^.]*\b(?:i\.e\.|e\.g\.))\s/$1\\ /;
-
-  remove_example_code($enum_name, \$desc);
+  $docs =~ s/^([^.]*\b(?:i\.e\.|e\.g\.))\s/$1\\ /;
+  
+  remove_example_code($c_enum_name, \$docs);
 
   # Convert to Doxygen-style comment.
-  $desc =~ s/\n/\n${DocsParser::commentMiddleStart}/g;
-  $desc =  $DocsParser::commentStart . $desc;
-  $desc .= "\n${DocsParser::commentEnd}\n";
+  $docs =~ s/\n/\n \* /g;
+  $docs =  "\/\*\* " . $docs;
 
-  return $desc;
+  return $docs;
 }
 
 # $strCommentBlock lookup_documentation($strFunctionName, $deprecation_docs, $objCppfunc)
@@ -483,7 +489,8 @@ sub convert_tags_to_doxygen($)
 
     # 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;
+    # Also don't convert @enum and @var which are used for enum documentation.
+    s" \ a (throws?|param|enum|var)\b" \ $1"g;
 
     s"^Note ?\d?: "\ note "mg;
     s"</?programlisting>""g;
diff --git a/tools/pm/Enum.pm b/tools/pm/Enum.pm
index 2c71ab8..8d0ce77 100644
--- a/tools/pm/Enum.pm
+++ b/tools/pm/Enum.pm
@@ -317,10 +317,6 @@ sub build_element_list($$$$)
     my $name  = $$elem_names[$i];
     my $value = $$elem_values[$i];
 
-    my $docs  =
-      DocsParser::lookup_enum_value_documentation("$$self{c_type}",
-        "$$self{c_prefix}$name");
-
     for(my $ii = 0; $ii < scalar(@subst_in); ++$ii)
     {
       $name  =~ s/${subst_in[$ii]}/${subst_out[$ii]}/;
@@ -330,19 +326,7 @@ sub build_element_list($$$$)
     # Skip this element, if its name has been deleted.
     next if($name eq "");
 
-    if($docs ne "")
-    {
-      # Make sure the docs is indented the right number of spaces.
-      # (First remove initial spaces in first line and then the rest
-      # and then indent the lines).
-      $docs =~ s/^\s+//;
-      $docs =~ s/\n\s+/\n/g;
-      $docs =~ s/\n(\s*\*)/\n${indent} $1/g;
-      $docs = "${indent}${docs}";
-    }
-
     $elements .= ",\n" if($elements ne "");
-    $elements .= $docs;
     $elements .= "${indent}${name}";
     $elements .= " = ${value}" if($value ne "");
   }
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index c7adaec..2da2bf8 100644
--- a/tools/pm/Output.pm
+++ b/tools/pm/Output.pm
@@ -73,7 +73,7 @@ sub output_wrap_failed($$$)
   my ($self, $cname, $error) = @_;
 
   my $str = sprintf("//gtkmmproc error: %s : %s", $cname, $error);
-  print STDERR "Output.pm: $cname : $error\n";
+  print STDERR "Output.pm: $main::source: $cname : $error\n";
   $self->append($str);
 }
 
@@ -652,17 +652,19 @@ sub output_wrap_enum($$$$$$$)
   my $value_suffix = "Enum";
   $value_suffix = "Flags" if($$objEnum{flags});
 
-  # Get the existing enum description from the parsed docs.
-  my $description = DocsParser::lookup_enum_description("$c_type");
-
-  # Prepend the Doxygen marker ' * ' to all but the first line.
-  $description =~ s/\n/\n * /g;
+  # Get the enum documentation from the parsed docs.
+  my $enum_docs =
+    DocsParser::lookup_enum_documentation("$c_type", "$cpp_type", \ flags);
 
+  # Remove initial Doxygen comment block start ('/**') from the enum docs
+  # to merge the passed in Doxygen comment block.
+  $enum_docs =~ s/\/\*\*\s+//g;
+  
   # Make sure indentation of passed in comment is correct.
   $comment =~ s/\n\s*\*/\n */g;
 
   # Merge the passed in comment to the existing enum documentation.
-  $comment = $comment . "\n * " . $description;
+  $comment = $comment . "\n * " . $enum_docs;
 
   my $str = sprintf("_ENUM(%s,%s,%s,\`%s\',\`%s\',\`%s\')dnl\n",
     $cpp_type,
@@ -676,6 +678,37 @@ sub output_wrap_enum($$$$$$$)
   $self->append($str);
 }
 
+sub output_wrap_enum_docs_only($$$$$$$)
+{
+  my ($self, $filename, $line_num, $module_canonical, $cpp_type, $c_type,
+      $comment, @flags) = @_;
+ 
+  # Get the existing enum description from the parsed docs.
+  my $enum_docs =
+    DocsParser::lookup_enum_documentation("$c_type", "$cpp_type", \ flags);
+
+  if($enum_docs eq "")
+  {
+    $self->output_wrap_failed($c_type, "failed to find documentation.");
+    return;
+  }
+
+  # Include the enum docs in the module's enum docs group.
+  $enum_docs .= "\n * \ ingroup ${module_canonical}Enums\n";
+
+  # Remove initial Doxygen comment block start ('/**') from the enum docs
+  # to merge the passed in Doxygen comment block.
+  $enum_docs =~ s/\/\*\*\s+//g;
+  
+  # Merge the passed in comment to the existing enum documentation.
+  $comment = "\/\*\* " . $comment . "\n * " . $enum_docs . "\n */\n";
+
+  # Make sure indentation of passed in comment is correct.
+  $comment =~ s/\n\s*\*/\n */g;
+
+  $self->append($comment);
+}
+
 # void output_wrap_gerror($filename, $line_num, $cpp_type, $c_enum, $domain, @flags)
 sub output_wrap_gerror($$$$$$$)
 {
diff --git a/tools/pm/WrapParser.pm b/tools/pm/WrapParser.pm
index c620e4a..cd39097 100644
--- a/tools/pm/WrapParser.pm
+++ b/tools/pm/WrapParser.pm
@@ -121,6 +121,7 @@ sub parse_and_build_output($)
     if ($token eq "_WRAP_CREATE") { $self->on_wrap_create(); next;}
 
     if ($token eq "_WRAP_ENUM")   { $self->on_wrap_enum(); next;}
+    if ($token eq "_WRAP_ENUM_DOCS_ONLY")   { $self->on_wrap_enum_docs_only(); next;}
     if ($token eq "_WRAP_GERROR") { $self->on_wrap_gerror(); next;}
     if ($token eq "_IMPLEMENTS_INTERFACE") { $self->on_implements_interface(); next;}
 
@@ -1333,6 +1334,32 @@ sub on_wrap_enum($)
       $$self{filename}, $$self{line_num}, $cpp_type, $c_type, $comment, @args);
 }
 
+sub on_wrap_enum_docs_only($)
+{
+  my ($self) = @_;
+
+  return unless ($self->check_for_eof());
+
+  my $outputter = $$self{objOutputter};
+  my $comment = $self->extract_preceding_documentation();
+
+  # get the arguments
+  my @args = string_split_commas($self->extract_bracketed_text());
+
+  my $cpp_type = string_trim(shift(@args));
+  my $c_type   = string_trim(shift(@args));
+
+  # Get the module name so the enum docs can be included in the module's
+  # Doxygen enum group.
+  my $module_canonical = Util::string_canonical($$self{module});
+
+  # The remaining elements in @args could be flags or s#^FOO_## substitutions.
+
+  $outputter->output_wrap_enum_docs_only(
+      $$self{filename}, $$self{line_num}, $module_canonical, $cpp_type, $c_type,
+      $comment, @args);
+}
+
 sub on_wrap_gerror($)
 {
   my ($self) = @_;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]