GNOME Bugzilla – Bug 668918
Wrapped signals don't use the C documentation.
Last modified: 2012-03-06 11:58:09 UTC
Currently there's only a little bit information about the virtual functions and signals of Gtk::Widget available in the Doxygen documentation. The complete documentation is at the GTK+ reference. Wouldn't it be possible to copy the GTK+ documentation about the signals to the gtkmm reference? It is time-consuming to switch back and forth between two references. Also, I think it's very confusing, especially for beginners, who might not know where to look for the reference. After doing some research why gmmproc doesn't use GTK+ signal documentation, I've got some information that might be useful: * The current gtk/source/gtk_doc.xml does not contain signal documentation * If it is regenerated with signal documentation included, gmmproc doesn't pick it up. Regards, Mark
*_vfunc() methods are not related to signals. Let's deal with them separately, talking about signals first. The on_*() methods are related to signals. It would indeed be good if they had documentation, maybe just mentioning the signal_*() for which is is a default signal handler. And those signals should have the documentation from the C documentation. For instance, this: http://developer.gnome.org/gtk3/unstable/GtkButton.html#GtkButton-clicked should show up here: http://developer.gnome.org/gtkmm/unstable/classGtk_1_1Button.html#a515244a851fd9874cc481cdfc5ebf512 > * The current gtk/source/gtk_doc.xml does not contain signal documentation > * If it is regenerated with signal documentation included, gmmproc doesn't pick it up. How are you "regenerating it" to include signal documentation? The signal documentation would ideally be here, like it is for properties, whose documentation we _do_ use: http://git.gnome.org/browse/gtkmm/tree/gtk/src/gtk_signals.defs That part of that file is generated by this code (get_signals()): http://git.gnome.org/browse/glibmm/tree/tools/extra_defs_gen/generate_extra_defs.cc#n144 But it looks like the signal documentation is not available at runtime like it is for properties: http://developer.gnome.org/gobject/stable/gobject-Signals.html#GSignalQuery (I guess that's why Glade doesn't offer any documentation for signals either.) Maybe we would use the signal documentation somehow in output_wrap_sig_decl() here: http://git.gnome.org/browse/glibmm/tree/tools/pm/Output.pm#n474
Created attachment 206697 [details] [review] Patch to add documentation to generated signals. This patch does just what's described for signals. It adds docs to the on_*() default handlers, referring the reader to the signal_*() docs. It also modifies the relevant code in gmmproc to store the documentation of the signals from the generated docs and then retrieve them to be included in the Doxygen block of the signal declaration. I think the way the documentation is generated is by passing the --signal (or -i) option to docextract_to_xml.py.
Excellent. Please push this and try to use it in gtkmm. Thanks.
Sure. Can I also try in glibmm?
Pushed to the master branch: http://git.gnome.org/browse/glibmm/commit/?id=ce3f70daccba5b841fc508fa4c0ab808e35bb934 I accidentally included a change (in DocsParser.pm) that signals that C example code is removed in the method docs: @@ -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); @ Please let me know if this should be reverted.
I've tested the changes with gtkmm and it works well. I removed some already existing signal docs so that the generated ones are used: http://git.gnome.org/browse/gtkmm/commit/?id=d634d9459d4e3d32223e95c4aad8bb49de2b2050 Having gmmproc change the generated signal name from "::a-signal" to "signal_a_signal()" might be considered because quite a few signal docs use that format for the name and is what appears in the docs. It might also be a good idea to do the same thing in glibmm as in gtkmm. I guess this bug can remain open in the mean time.
Created attachment 207468 [details] [review] gmmproc: Patch to convert property and signal names correctly. This patch converts gtk-doc property and signal references to the correct C++ names so that they are correctly referenced in the documentation. While providing the patch I noticed that the C API gtk-docs quite often uses incorrect formats to refer to properties, using #CType::a-property instead of #CType:a-property (notice the double colon as opposed to a single colon) and sometimes "::a-property" which is not a correct gtk-doc way of referring to them (see the gtk-docs: http://developer.gnome.org/gtk-doc-manual/unstable/documenting_symbols.html.en). This patch protects against these references and correctly converts them by seeing if the word "property" occurs after the gtk-doc reference which happens in all the references to properties that I could find in the gtk+ docs. As a warning, if the word "property" does not follow these incorrect references (which does not presently occur), they are treated as signals (which they should be). gtk-doc does not accept a "::a-property" format. A "#CType::a-property" is correctly translated by gtk-doc as a property, but there is no link in the documentation as there should be, signalling an error (see for example the gtk_activatable_sync_action_properties() docs[1][2] which incorrecly references the "related-action" property as opposed to the gtk_activatable_set_related_action() docs[3][4] which does it correctly. Overall, I'm pretty pleased with how the patch works. [1] http://developer.gnome.org/gtk3/3.3/GtkActivatable.html#gtk-activatable-sync-action-properties [2] http://git.gnome.org/browse/gtkmm/tree/gtk/src/gtk_docs.xml#n11165 [3] http://developer.gnome.org/gtk3/3.3/GtkActivatable.html#gtk-activatable-set-related-action [4] http://git.gnome.org/browse/gtkmm/tree/gtk/src/gtk_docs.xml#n11116 [4]
I forgot to mention that, though references to signals in the gtk-doc such as "::a-signal" are also incorrect, the patch treats them as references to signals unless they are followd by the word "property" because there are many references such as those to signals in the gtk-docs.
(In reply to comment #4) > Sure. Can I also try in glibmm? Yes, of course. Thanks. Feel free to push the other patch(es) too. I will try to run regexxer on glib and gtk+ to correct these mistakes, but it's good to be ready for these common problems.
(In reply to comment #7) > Created an attachment (id=207468) [details] [review] > gmmproc: Patch to convert property and signal names correctly. Pushed: http://git.gnome.org/browse/glibmm/commit/?id=274870acdd9baf8b163fd224a6a4f92469796819
The changes have also been tried in glibmm: http://git.gnome.org/browse/glibmm/commit/?id=fd8efdc63640e9a8c8b478f0fab634c502825d2f http://git.gnome.org/browse/glibmm/commit/?id=a7e1bc1cdba727e0fcb1a64e8b8161bf6d7b4814 The changes work well there also. There was a typo in the gtk-docs of the g_application_activate() function refering to the GApplication::activate signal. It appends parenthesis in the reference when it should not (ie. The reference is "#GApplication::activate()" when it should just be "#GApplication::activate").
The typo is not important, however, because the parenthesis are removed if they are found.
This is the commit that reomves the parens: http://git.gnome.org/browse/glibmm/commit/?id=658733d60d55d35617c86346673aab9a22ca6fe7
(In reply to comment #7) > I noticed that the C API gtk-docs quite often uses > incorrect formats to refer to properties, using #CType::a-property instead of > #CType:a-property (notice the double colon as opposed to a single colon) and > sometimes "::a-property" which is not a correct gtk-doc way of referring to > them (see the gtk-docs: > http://developer.gnome.org/gtk-doc-manual/unstable/documenting_symbols.html.en). Fixed in GTK+: http://git.gnome.org/browse/gtk+/commit/?id=a0b4ab109dccb0d523082de928948e71b0681ef1 > There was a typo in the gtk-docs of the g_application_activate() function > refering to the GApplication::activate signal. It appends parenthesis in the > reference when it should not (ie. The reference is "#GApplication::activate()" > when it should just be "#GApplication::activate"). Fixed in glib: http://git.gnome.org/browse/glib/commit/?id=d4992b3d10f64918017617cda0fdaba4d132bf99 What still needs to be done in glibmm or gtkmm, if anything?
Nothing at all. Closing.
(In reply to comment #11) > The changes have also been tried in glibmm: > > http://git.gnome.org/browse/glibmm/commit/?id=fd8efdc63640e9a8c8b478f0fab634c502825d2f How are you generating the *_docs.xml files now. I don't see how to get that signal documentation into them.
(In reply to comment #16) > How are you generating the *_docs.xml files now. I don't see how to get that > signal documentation into them. To be honest, I have a few scripts that I run in jhbuild's shell that generate them for me (similar to ones in gstreamermm found in gstreamer/src -- I can add them to glibmm and giomm as well). However, I just pass the '-i' ('--with-signals') option to docextract_to_xml.py. It might be better to have the default for this option to be true instead of false (as it is now) since gmmproc can now handle the signal doc. On another note, related to the original filing of this bug, it may be possible to get the documentation of vfuncs in (similar to what is done with signals) and then include them in the documentation of wrapped virtual functions. The thought had occurred to me recently though it will have to be looked at a little later.
(In reply to comment #17) > (In reply to comment #16) > > How are you generating the *_docs.xml files now. I don't see how to get that > > signal documentation into them. > > To be honest, I have a few scripts that I run in jhbuild's shell that generate > them for me (similar to ones in gstreamermm found in gstreamer/src -- I can add > them to glibmm and giomm as well). That sounds useful. Yes, please. Maybe in tools/ > However, I just pass the '-i' > ('--with-signals') option to docextract_to_xml.py. It might be better to have > the default for this option to be true instead of false (as it is now) since > gmmproc can now handle the signal doc. Yes. Why is it even an option? > On another note, related to the original filing of this bug, it may be possible > to get the documentation of vfuncs in (similar to what is done with signals) > and then include them in the documentation of wrapped virtual functions. The > thought had occurred to me recently though it will have to be looked at a > little later. That sounds great, but it's something for a separate bug, I think.
The scripts have been added to glibmm in tools/gen_scripts by this commit: http://git.gnome.org/browse/glibmm/commit/?id=fd90d1f8329d7e0840e176ae2e493190cea57521 Also, docextract_to_xml.py has been modified so that it is not necessary to pass any options so that the signal documentation is included in the generated XML. The '-i' option (and its corresponding new --no-signal option which replaces the old --with-signal option) now requests that the signal doc not be included (I hope this is fine). The commit that does that is: http://git.gnome.org/browse/glibmm/commit/?id=33f7f9a873c6e07d08a77963d237ca966ea057bc I'm sure I can probably add similar scripts to the ones in glbimm to gtkmm if that's a good idea.
There are now scripts in gtkmm as well. All that's left for the future is including virtual function documentation, but that corresponds to a separate future bug.
Closing this bug then. Thanks.