diff options
author | José Alburquerque <jaalburqu@svn.gnome.org> | 2012-02-07 14:03:02 -0500 |
---|---|---|
committer | José Alburquerque <jaalburqu@svn.gnome.org> | 2012-02-07 14:03:02 -0500 |
commit | ce3f70daccba5b841fc508fa4c0ab808e35bb934 (patch) | |
tree | 4d3c1f5820e17df26bc69641d67a0f4202ce6846 | |
parent | 2de7f8ae378e2e0f3285433168850e50f095b377 (diff) | |
download | glibmm-ce3f70daccba5b841fc508fa4c0ab808e35bb934.tar.gz |
gmmproc: Add documentation to wrapped signals.
* tools/m4/signal.m4: Add docs to the on_*() default handlers
referring the users to the signal_*() docs.
* tools/pm/DocsParser.pm (parse_on_start):
(parse_on_end): Allow the <signal></signal> tags from the generated
XML docs to be processed in a similar way as the <function></function>
tags are processed. The docs of the signals are stored as
"Class::a_signal_name" in the hash.
(append_parameter_docs): Skip the first parameter for signals also
because the first parameter of signals is the object for which the
signal is triggered.
(lookup_documentation): Generalize the no docs warning to include
signals also.
* tools/pm/Function.pm (get_refdoc_comment): Modify the subroutine to
accept the docs of the signal (that the DocsParser stores) and include
the prototype of the slot in the docs.
* tools/pm/Output.pm (output_wrap_sig_decl): Modify the subroutine to
look up the documentation of the signal which it then passes to
get_refdoc_comment() so that the documentation of the signal from the
generated XML is included in the declaration of the signal.
Bug #668918 (Mark)
-rw-r--r-- | ChangeLog | 26 | ||||
-rw-r--r-- | tools/m4/signal.m4 | 1 | ||||
-rw-r--r-- | tools/pm/DocsParser.pm | 18 | ||||
-rw-r--r-- | tools/pm/Function.pm | 26 | ||||
-rw-r--r-- | tools/pm/Output.pm | 15 | ||||
-rw-r--r-- | tools/pm/Util.pm | 2 | ||||
-rw-r--r-- | tools/pm/WrapParser.pm | 2 |
7 files changed, 75 insertions, 15 deletions
@@ -1,3 +1,29 @@ +2012-02-03 José Alburquerque <jaalburquerque@gmail.com> + + gmmproc: Add documentation to wrapped signals. + + * tools/m4/signal.m4: Add docs to the on_*() default handlers + referring the users to the signal_*() docs. + * tools/pm/DocsParser.pm (parse_on_start): + (parse_on_end): Allow the <signal></signal> tags from the generated + XML docs to be processed in a similar way as the <function></function> + tags are processed. The docs of the signals are stored as + "Class::a_signal_name" in the hash. + (append_parameter_docs): Skip the first parameter for signals also + because the first parameter of signals is the object for which the + signal is triggered. + (lookup_documentation): Generalize the no docs warning to include + signals also. + * tools/pm/Function.pm (get_refdoc_comment): Modify the subroutine to + accept the docs of the signal (that the DocsParser stores) and include + the prototype of the slot in the docs. + * tools/pm/Output.pm (output_wrap_sig_decl): Modify the subroutine to + look up the documentation of the signal which it then passes to + get_refdoc_comment() so that the documentation of the signal from the + generated XML is included in the declaration of the signal. + + Bug #668918 (Mark) + 2.31.16: 2012-01-30 TS <t.sailer@alumni.ethz.ch> diff --git a/tools/m4/signal.m4 b/tools/m4/signal.m4 index 970c20db..9cf43052 100644 --- a/tools/m4/signal.m4 +++ b/tools/m4/signal.m4 @@ -230,6 +230,7 @@ define(`_SIGNAL_H',`dnl _PUSH(SECTION_H_DEFAULT_SIGNAL_HANDLERS) ifelse(`$4',,,`#ifdef $4' )dnl + /// This is a default handler for the signal signal_$1`'(). virtual $2 on_$1`'($3); ifelse(`$4',,,`#endif // $4 ')dnl diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm index aa46cdca..7df773b6 100644 --- a/tools/pm/DocsParser.pm +++ b/tools/pm/DocsParser.pm @@ -112,7 +112,7 @@ sub parse_on_start($$%) $tag = lc($tag); - if($tag eq "function") + if($tag eq "function" or $tag eq "signal") { if(defined $DocsParser::objCurrentFunction) { @@ -121,6 +121,9 @@ sub parse_on_start($$%) my $functionName = $attr{name}; + # Change signal name from Class::a-signal-name to Class::a_signal_name. + $functionName =~ s/-/_/g if($tag eq "signal"); + #Reuse existing Function, if it exists: #(For instance, if this is the override parse) $DocsParser::objCurrentFunction = $DocsParser::hasharrayFunctions{$functionName}; @@ -191,7 +194,7 @@ sub parse_on_end($$) $tag = lc($tag); - if($tag eq "function") + if($tag eq "function" or $tag eq "signal") { # Store the Function structure in the array: my $functionName = $$DocsParser::objCurrentFunction{name}; @@ -246,7 +249,7 @@ sub lookup_documentation($$) if(length($text) eq 0) { - print "DocsParser.pm: Warning: No C docs for function: \"$functionName\"\n"; + print "DocsParser.pm: Warning: No C docs for: \"$functionName\"\n"; } DocsParser::convert_docs_to_cpp($objFunction, \$text); @@ -266,10 +269,10 @@ sub lookup_documentation($$) # Remove C example code. my $example_removals = - ($text =~ s"<informalexample>.*?</informalexample>""sg); + ($text =~ s"<informalexample>.*?</informalexample>"\[C example ellipted]"sg); $example_removals += - ($text =~ s"<programlisting>.*?</programlisting>""sg); - $example_removals += ($text =~ s"\|\[.*?]\|""sg); + ($text =~ s"<programlisting>.*?</programlisting>"\n[C example ellipted]"sg); + $example_removals += ($text =~ s"\|\[.*?]\|"\n[C example ellipted]"sg); print STDERR "gmmproc: $functionName(): Example code discarded.\n" if ($example_removals); @@ -311,6 +314,9 @@ sub append_parameter_docs($$) shift(@param_names) if(($defs_method && $$defs_method{class} ne "") || ($$obj_function{mapped_class} ne "")); + # Also skip first param if this is a signal. + shift(@param_names) if ($$obj_function{name} =~ /\w+::/); + foreach my $param (@param_names) { if ($param ne "error" ) #We wrap GErrors as exceptions, so ignore these. diff --git a/tools/pm/Function.pm b/tools/pm/Function.pm index 8032c047..7073ebe0 100644 --- a/tools/pm/Function.pm +++ b/tools/pm/Function.pm @@ -376,15 +376,16 @@ sub add_parameter($$$) return $self; } -# $string get_refdoc_comment() -# Generate a readable prototype for signals. -sub get_refdoc_comment($) +# $string get_refdoc_comment($existing_signal_docs) +# Generate a readable prototype for signals and merge the prototype into the +# existing Doxygen comment block. +sub get_refdoc_comment($$) { - my ($self) = @_; + my ($self, $documentation) = @_; my $str = " /**\n"; - $str .= " * \@par Prototype:\n"; + $str .= " * \@par Slot Prototype:\n"; $str .= " * <tt>$$self{rettype} on_my_\%$$self{name}("; my $param_names = $$self{param_names}; @@ -399,8 +400,21 @@ sub get_refdoc_comment($) } $str .= ")</tt>\n"; - $str .= " */"; + $str .= " *\n"; + + if($documentation ne "") + { + # Remove the initial '/** ' from the existing docs and merge it. + $documentation =~ s/\/\*\*\s+/ \* /; + $str .= $documentation; + } + else + { + # Close the doc block if there's no existing docs. + $str .= " */\n"; + } + # Return the merged documentation. return $str; } diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm index 4ec437d9..79a5e40a 100644 --- a/tools/pm/Output.pm +++ b/tools/pm/Output.pm @@ -20,6 +20,8 @@ package Output; use strict; use open IO => ":utf8"; +use DocsParser; + BEGIN { @Namespace::ISA=qw(main); } # $objOutputter new() @@ -481,7 +483,18 @@ sub output_wrap_sig_decl($$$$$$$$) # cpp_signal_name, cpp_return_type, `<cpp_arg_types>',`<c_args_to_cpp>', # refdoc_comment) - my $doxycomment = $objCppfunc->get_refdoc_comment(); + # Get the signal name with underscores only (to look up docs -- they are + # stored that way). + my $underscored_signal_name = $signal_name; + $underscored_signal_name =~ s/-/_/g; + + # Get the existing signal documentation from the parsed docs. + my $documentation = + DocsParser::lookup_documentation("$$objCSignal{class}::$underscored_signal_name", ""); + + # Create a merged Doxygen comment block for the signal from the looked up + # docs (the block will also contain a prototype of the slot as an example). + my $doxycomment = $objCppfunc->get_refdoc_comment($documentation); # If there was already a previous doxygen comment, we want to merge this # one with the previous so it is one big comment. If it were two separate diff --git a/tools/pm/Util.pm b/tools/pm/Util.pm index cc1ccfa0..f8bc9331 100644 --- a/tools/pm/Util.pm +++ b/tools/pm/Util.pm @@ -51,7 +51,7 @@ sub string_unquote($) $str =~ s/^['`"]// ; $str =~ s/['`"]$// ; - + return $str; } diff --git a/tools/pm/WrapParser.pm b/tools/pm/WrapParser.pm index 04abd0f1..d2716222 100644 --- a/tools/pm/WrapParser.pm +++ b/tools/pm/WrapParser.pm @@ -1414,7 +1414,7 @@ sub byattrib() "sig_decl" ,4, "meth" ,5 ); - + # $a and $b are hidden parameters to a sorting function return $attrib_value{$b} <=> $attrib_value{$a}; } |