diff options
author | Kjell Ahlstedt <kjell.ahlstedt@bredband.net> | 2015-06-02 09:19:24 +0200 |
---|---|---|
committer | Kjell Ahlstedt <kjell.ahlstedt@bredband.net> | 2015-06-02 09:19:24 +0200 |
commit | 46e2b79fc1fbcb724b1633988e6e976105218523 (patch) | |
tree | b093cb253234b531eb5ff8803d12dbf6fcd604a5 /tools | |
parent | 139edfe4ed773f127b7e271f2b1f2d614ad1f916 (diff) | |
download | glibmm-46e2b79fc1fbcb724b1633988e6e976105218523.tar.gz |
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.
Diffstat (limited to 'tools')
-rw-r--r-- | tools/pm/DocsParser.pm | 18 | ||||
-rw-r--r-- | tools/pm/Output.pm | 56 | ||||
-rw-r--r-- | tools/pm/Property.pm | 10 | ||||
-rw-r--r-- | 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 3cfac2d3..726ada2f 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 e145489b..099a1e46 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 f89140ea..8e2a131f 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 f14ad575..b33ecb13 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($$$$$$) |