GNOME Bugzilla – Bug 657844
Documentation: Slot parameter types link to libsigc++ instead of the typedef
Last modified: 2015-09-15 16:26:54 UTC
Hi. This is probably easy to fix (and anyone might probably be able fix it), but something happens with the documentation with regards to slot types in method signatures. See, for example, the Gtk::TreeViewColumn::set_cell_data_func() documentation: http://developer.gnome.org/gtkmm/stable/classGtk_1_1TreeViewColumn.html#a765296845c9e9757ba405becbbc13d96 If an attempt is made to click on the SlotCellData type, it leads to the sigc documentation here: http://developer.gnome.org/libsigc++/unstable/classsigc_1_1slot.html instead of to the gtkmm documentation of it here: http://developer.gnome.org/gtkmm/stable/classGtk_1_1TreeViewColumn.html#a5f5b39cdb46dc52083a7d7c019ef9c60 which is clearer.
Yes, but I guess that is Doxygen's fault. Maybe we need a simple test case for Doxygen (whose bugs are also tracked on bugzilla.gnome.org).
Created attachment 195821 [details] Doxygen test header file. I guess the treeviewcolumn.h file could be used as a test. I still think it's more something to do with mm-common and not Doxygen. I tested this single header by placing it in a test directory, running `doxygen -g Doxygen.conf' and then `doxygen Doxygen.conf' in the directory. Browsing the slot in the mentioned method goes to the desired section of the same page.
To be a little more specific, I think the doc-install.pl script in mm-common somehow process the files while installing in such a way that this happens.
I suppose its still Doxygen's fault. Try to repeat your test but put both treeviewcolumn.h and slot.h from <libsigc++2_srcdir>/sigc++/functors/ into your test directory and then run doxygen -g Doxyfile && doxygen Doxyfile. You'll see that SlotCellData now points to sigc::slot class instead.
Yes, but would that happen in a normal build of, eg. gtkmm? Doxygen would not know about libsigc++'s headers then. I admit, I don't fully understand what's actually happening. I'm not even sure this is actually a bug. If it's still a Doxygen bug though I'll be glad to reassign it then.
Probably Doxygen knows about libsigc++ headers during gtkmm compilation because it parses .tag files. I'll check it later in different way - instead of putting libsigc++ header I'll put libsigc++.tag and force Doxygen to read it too.
Isn't this just a general issue of Doxygen linking directly to the type instead of to the typedef to that type? I can see how that might be useful sometimes, but it's not what we want her. It seems best to ask about it on the doxygen list or to file a doxygen bug.
I tested this with using tag files and still parameter is linked to Slot class instead to a typedef, filed a bug #659249 for Doxygen. Closing this one as NOTABUG.
Thanks, but I prefer to keep this bug open, but dependent on the doxygen bug, because this is still a bug, whatever the cause.
[Setting QA Contact of all open gtkmm/documentation tickets to 'gtkmm-forge@' so people interested in following reports' changes via the users watchlist can still follow if the assignee is changed to a real person.]
This is still a problem with the latest documentation: http://developer.gnome.org/gtkmm/unstable/classGtk_1_1TreeViewColumn.html#a765296845c9e9757ba405becbbc13d96
The doxygen bug 659249 has been fixed in doxygen 1.7.5, although not in the way suggested in the bug description. The link in comment 11 still goes to Gtk::TreeViewColumn::set_cell_data_func(), but now the link from SlotCellData does not go to sigc::slot, but to typedef xxx SlotCellData. Probably http://developer.gnome.org/gtkmm/unstable has been regenerated with a newer version of doxygen after comment 11 was filed. But there's still an error. SlotCellData in TreeViewColumn:: set_cell_data_func() does not link to typedef xxx SlotCellData in TreeViewColumn. It links to typedef xxx SlotCellData in the base class CellLayout. This kind of bug is reported in the doxygen bug 648719.
Yes. This is still happening. I guess we could rename the types if we really want to work around this outside of doxygen.
Created attachment 286800 [details] [review] patch: TreeView, TreeViewColumn: Deprecate SlotCellData, add SlotTreeCellData Just renaming the types would break API. Someone might have declared Gtk::TreeViewColumn::SlotCellData my_slot = ......; Luckily typedefs are not part of the ABI. It's possible to add a new typedef and use that typedef in TreeViewColumn, like in the attached patch. It's not necessary to deprecate SlotCellData and add SlotTreeCellData in TreeView, but I think it's nice to have the same name in TreeView and TreeViewColumn. Those slot definitions are identical.
Sure. Please go ahead.
Review of attachment 286800 [details] [review]: I have pushed an updated version of the patch in comment 14. I had forgotten to replace the now deprecated SlotCellData by SlotTreeCellData in .ccg and .cc files. https://git.gnome.org/browse/gtkmm/commit/?id=9d8f30b3c8451c33fa2a2271c410af56b74165ee