[glibmm] gmmproc: Fetch property docs from the docs.xml file, if available there

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 46e2b79fc1fbcb724b1633988e6e976105218523
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Tue Jun 2 09:19:24 2015 +0200

    gmmproc: Fetch property docs from the docs.xml file, if available there
    
    * tools/pm/DocsParser.pm: Read info from <property> tags.
    * tools/pm/Output.pm: output_wrap_any_property(): Handle 'newin' option.
    Read documentation from DocsParser, if available there, else (like before)
    from the Property object.
    * tools/pm/Property.pm: get_docs(): Handle 'newin' option.
    * tools/pm/WrapParser.pm: on_wrap_any_property(): Add support for the
    'newin "m,n"' option in _WRAP_PROPERTY and _WRAP_CHILD_PROPERTY.

 tools/pm/DocsParser.pm |   18 ++++++++++-----
 tools/pm/Output.pm     |   56 +++++++++++++++++++++++++++++++++++++++++------
 tools/pm/Property.pm   |   10 ++++++-
 tools/pm/WrapParser.pm |   20 ++++++++++++----
 4 files changed, 83 insertions(+), 21 deletions(-)
---
diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index 3cfac2d..726ada2 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -112,18 +112,19 @@ sub parse_on_start($$%)
 
   $tag = lc($tag);
 
-  if($tag eq "function" or $tag eq "signal" or $tag eq "enum")
+  if($tag eq "function" or $tag eq "signal" or $tag eq "property" or $tag eq "enum")
   {
     if(defined $DocsParser::objCurrentFunction)
     {
       $objParser->xpcroak(
-        "\nClose a function, signal or enum tag before you open another one.");
+        "\nClose a function, signal, property or enum tag before you open another one.");
     }
 
     my $functionName = $attr{name};
 
-    # Change signal name from Class::a-signal-name to Class::a_signal_name.
-    $functionName =~ s/-/_/g if($tag eq "signal");
+    # Change signal name from Class::a-signal-name to Class::a_signal_name
+    # and property name from Class:a-property-name to Class:a_property_name
+    $functionName =~ s/-/_/g if ($tag eq "signal" or $tag eq "property");
 
     #Reuse existing Function, if it exists:
     #(For instance, if this is the override parse)
@@ -195,7 +196,7 @@ sub parse_on_end($$)
 
   $tag = lc($tag);
 
-  if($tag eq "function" or $tag eq "signal" or $tag eq "enum")
+  if($tag eq "function" or $tag eq "signal" or $tag eq "property" or $tag eq "enum")
   {
     # Store the Function structure in the array:
     my $functionName = $$DocsParser::objCurrentFunction{name};
@@ -349,7 +350,8 @@ sub lookup_documentation($$$;$)
   # Most @newins are at the end of a function description.
   $text .= "\n";
 
-  #Add note about deprecation if we have specified that in our _WRAP_METHOD() call:
+  # Add note about deprecation if we have specified that in our _WRAP_METHOD(),
+  # _WRAP_SIGNAL(), _WRAP_PROPERTY() or _WRAP_CHILD_PROPERTY() call:
   if($deprecation_docs ne "")
   {
     $text .= "\n\ deprecated $deprecation_docs\n";
@@ -357,6 +359,10 @@ sub lookup_documentation($$$;$)
 
   DocsParser::append_parameter_docs($objFunction, \$text, $objCppfunc);
   DocsParser::append_return_docs($objFunction, \$text);
+
+  # Remove leading and trailing white space.
+  $text = string_trim($text);
+
   DocsParser::add_m4_quotes(\$text);
 
   # Escape the space after "i.e." or "e.g." in the brief description.
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index e145489..099a1e4 100644
--- a/tools/pm/Output.pm
+++ b/tools/pm/Output.pm
@@ -778,7 +778,8 @@ sub output_wrap_gerror($$$$$$$)
 # void output_wrap_any_property($filename, $line_num, $name, $cpp_type, $c_class, $deprecated, 
$deprecation_docs, $objProperty, $proxy_macro)
 sub output_wrap_any_property($$$$$$$$$$)
 {
-  my ($self, $filename, $line_num, $name, $cpp_type, $c_class, $deprecated, $deprecation_docs, $objProperty, 
$proxy_macro) = @_;
+  my ($self, $filename, $line_num, $name, $cpp_type, $c_class, $deprecated,
+      $deprecation_docs, $newin, $objProperty, $proxy_macro) = @_;
 
   my $objDefsParser = $$self{objDefsParser};
 
@@ -810,9 +811,44 @@ sub output_wrap_any_property($$$$$$$$$$)
   my $name_underscored = $name;
   $name_underscored =~ tr/-/_/;
 
-  # Get the property documentation, if any, and add m4 quotes.
-  my $documentation = $objProperty->get_docs($deprecation_docs);
-  add_m4_quotes(\$documentation) if ($documentation ne "");
+  # Get the existing property documentation, if any, from the parsed docs.
+  my $documentation = DocsParser::lookup_documentation(
+    "$$objProperty{class}:$name_underscored", $deprecation_docs, $newin);
+
+  if ($documentation ne "")
+  {
+    # Remove leading "/**" and trailing "*/". They will be added by the m4 macro.
+    $documentation =~ s/^\s*\/\*\*\s*//;
+    $documentation =~ s/\s*\*\/\s*$//;
+  }
+
+  if ($documentation =~ /^`?[*\s]*
+      (?:
+        \ newin\{[\d,]+\}
+        |[Ss]ince[:\h]+\d+\.\d+
+        |\ deprecated\s
+        |[Dd]eprecated[:\s]
+      )/x)
+  {
+    # The documentation begins with a "@newin", "Since", "@deprecated" or
+    # "Deprecated" line. Get documentation also from the Property object,
+    # but don't add another @newin or @deprecated.
+    my $objdoc = $objProperty->get_docs("", "");
+    if ($objdoc ne "")
+    {
+      add_m4_quotes(\$objdoc);
+      $documentation = "$objdoc\n   *\n   * $documentation";
+    }
+  }
+  elsif ($documentation eq "")
+  {
+    # Try to get the (usually short) documentation from the Property object.
+    $documentation = $objProperty->get_docs($deprecation_docs, $newin);
+    if ($documentation ne "")
+    {
+      add_m4_quotes(\$documentation);
+    }
+  }
 
   #Declaration:
   if($deprecated ne "")
@@ -856,7 +892,8 @@ sub output_wrap_any_property($$$$$$$$$$)
 # void output_wrap_property($filename, $line_num, $name, $cpp_type, $deprecated, $deprecation_docs)
 sub output_wrap_property($$$$$$$$)
 {
-  my ($self, $filename, $line_num, $name, $cpp_type, $c_class, $deprecated, $deprecation_docs) = @_;
+  my ($self, $filename, $line_num, $name, $cpp_type, $c_class, $deprecated,
+      $deprecation_docs, $newin) = @_;
 
   my $objProperty = GtkDefs::lookup_property($c_class, $name);
   if($objProperty eq 0) #If the lookup failed:
@@ -865,7 +902,8 @@ sub output_wrap_property($$$$$$$$)
   }
   else
   {
-    $self->output_wrap_any_property($filename, $line_num, $name, $cpp_type, $c_class, $deprecated, 
$deprecation_docs, $objProperty, "_PROPERTY_PROXY");
+    $self->output_wrap_any_property($filename, $line_num, $name, $cpp_type, $c_class,
+      $deprecated, $deprecation_docs, $newin, $objProperty, "_PROPERTY_PROXY");
   }
 }
 
@@ -873,7 +911,8 @@ sub output_wrap_property($$$$$$$$)
 # void output_wrap_child_property($filename, $line_num, $name, $cpp_type, $deprecated, $deprecation_docs)
 sub output_wrap_child_property($$$$$$$$)
 {
-  my ($self, $filename, $line_num, $name, $cpp_type, $c_class, $deprecated, $deprecation_docs) = @_;
+  my ($self, $filename, $line_num, $name, $cpp_type, $c_class, $deprecated,
+      $deprecation_docs, $newin) = @_;
 
   my $objChildProperty = GtkDefs::lookup_child_property($c_class, $name);
   if($objChildProperty eq 0) #If the lookup failed:
@@ -882,7 +921,8 @@ sub output_wrap_child_property($$$$$$$$)
   }
   else
   {
-    $self->output_wrap_any_property($filename, $line_num, $name, $cpp_type, $c_class, $deprecated, 
$deprecation_docs, $objChildProperty, "_CHILD_PROPERTY_PROXY");
+    $self->output_wrap_any_property($filename, $line_num, $name, $cpp_type, $c_class,
+      $deprecated, $deprecation_docs, $newin, $objChildProperty, "_CHILD_PROPERTY_PROXY");
   }
 }
 
diff --git a/tools/pm/Property.pm b/tools/pm/Property.pm
index f89140e..8e2a131 100644
--- a/tools/pm/Property.pm
+++ b/tools/pm/Property.pm
@@ -112,15 +112,21 @@ sub get_writable($)
 
 sub get_docs($$)
 {
-  my ($self, $deprecation_docs) = @_;
+  my ($self, $deprecation_docs, $newin) = @_;
   my $text = $$self{docs};
 
-  #Add note about deprecation if we have specified that in our _WRAP_METHOD() call:
+  #Add note about deprecation if we have specified that in our _WRAP_PROPERTY()
+  #or_WRAP_CHILD_PROPERTY() call:
   if($deprecation_docs ne "")
   {
     $text .= "\n   * \ deprecated $deprecation_docs";
   }
 
+  if ($newin ne "")
+  {
+    $text .= "\n   *\n   * \ newin{$newin}";
+  }
+
   return $text;
 }
 
diff --git a/tools/pm/WrapParser.pm b/tools/pm/WrapParser.pm
index f14ad57..b33ecb1 100644
--- a/tools/pm/WrapParser.pm
+++ b/tools/pm/WrapParser.pm
@@ -1501,6 +1501,7 @@ sub on_wrap_any_property($)
   #TODO: Reduce duplication with on_wrap_method():
   my $argDeprecated = "";
   my $deprecation_docs = "";
+  my $newin = "";
   while($#args >= 2) # If the optional arguments are there.
   {
     my $argRef = string_trim(pop @args);
@@ -1514,9 +1515,14 @@ sub on_wrap_any_property($)
         $deprecation_docs = string_unquote(string_trim($1));
       }
     }
+    elsif($argRef =~ /^newin(.*)/) #If newin is at the start.
+    {
+      $newin = string_unquote(string_trim($1));
+    }
   }
 
-  return ($filename, $line_num, $argPropertyName, $argCppType, $argDeprecated, $deprecation_docs);
+  return ($filename, $line_num, $argPropertyName, $argCppType,
+          $argDeprecated, $deprecation_docs, $newin);
 }
 
 sub on_wrap_property($)
@@ -1526,9 +1532,11 @@ sub on_wrap_property($)
 
   return unless ($self->check_for_eof());
 
-  my ($filename, $line_num, $argPropertyName, $argCppType, $argDeprecated, $deprecation_docs) = 
$self->on_wrap_any_property();
+  my ($filename, $line_num, $argPropertyName, $argCppType, $argDeprecated,
+      $deprecation_docs, $newin) = $self->on_wrap_any_property();
 
-  $objOutputter->output_wrap_property($filename, $line_num, $argPropertyName, $argCppType, $$self{c_class}, 
$argDeprecated, $deprecation_docs);
+  $objOutputter->output_wrap_property($filename, $line_num, $argPropertyName,
+    $argCppType, $$self{c_class}, $argDeprecated, $deprecation_docs, $newin);
 }
 
 sub on_wrap_child_property($)
@@ -1538,9 +1546,11 @@ sub on_wrap_child_property($)
 
   return unless ($self->check_for_eof());
 
-  my ($filename, $line_num, $argPropertyName, $argCppType, $argDeprecated, $deprecation_docs) = 
$self->on_wrap_any_property();
+  my ($filename, $line_num, $argPropertyName, $argCppType, $argDeprecated,
+      $deprecation_docs, $newin) = $self->on_wrap_any_property();
 
-  $objOutputter->output_wrap_child_property($filename, $line_num, $argPropertyName, $argCppType, 
$$self{c_class}, $argDeprecated, $deprecation_docs);
+  $objOutputter->output_wrap_child_property($filename, $line_num, $argPropertyName,
+    $argCppType, $$self{c_class}, $argDeprecated, $deprecation_docs, $newin);
 }
 
 sub output_wrap_check($$$$$$)