GNOME Bugzilla – Bug 544694
Enums are not documented
Last modified: 2013-02-25 08:38:48 UTC
gmmproc does not document the enums that it generates with _WRAP_ENUM(). GTK+, for instance, generally provides documentation in the .sgml files. For instance, the GtkFileChooserAction enum has documentation: http://library.gnome.org/devel/gtk/unstable/GtkFileChooser.html#GtkFileChooserAction But our Gtk::FileChooserAction enum does not: http://www.gtkmm.org/docs/gtkmm-2.4/docs/reference/html/group__gtkmmEnums.html#g0d6076e7637ec501f26296e65fee2212 pygobject/codegen/docextract_to_xml.py doesn't seem to put that documentation into our gtk_docs.xml file.
Created attachment 227776 [details] [review] gmmproc: Make enum documentation possible. This preliminary patch shows that this is possible presently. In glibmm, once the docs are regenerated, enum documentation appears in the .h files. Apparently, the Doxygen syntax is not quite right so they are not recognized correctly by Doxygen but that's just a matter or correcting the Doxygen syntax. I'll try and update the patch to get the Doxygen syntax right so that we can have enums documented.
Created attachment 227869 [details] [review] gmmproc: Make enum documentation possible. Here's the updated patch. With it, enums now appear documented in the HTML once the XML docs are regenerated. If used, it's necessary to keep in mind that enums that already have Doxygen comment blocks in the .hg file will have the existing enum description merged into that comment block if docs for it exist in the XML docs file.
Great. Please do push that and let's have a look at the results.
Sure. Pushed to the master branch: http://git.gnome.org/browse/glibmm/commit/?id=f6b5fbc531137f76f0d8f418a03a2c3d53aad473 The XML docs file have also been regenerated for glibmm and giomm in this commit: http://git.gnome.org/browse/glibmm/commit/?id=8544ed1d4665521c7eb25e3e851f333fec91e2e1
Created attachment 230898 [details] [review] patch: gmmproc: Improve the documentation of enums. In Enum.pm, build_element_list(), wouldn't it be better to use original element names, read from xxx_enums.defs, when searching for documentation? As an example, look at the enums in glibmm/gio/src/dbusmessage.hg. "DBUS_" is removed from the names, e.g. _WRAP_ENUM(MessageType, GDBusMessageType, s#^DBUS_##, NO_GTYPE) DocsParser::lookup_enum_value_documentation() does not find the modified names, e.g. G_MESSAGE_TYPE_METHOD_CALL, but it finds the original names, e.g. G_DBUS_MESSAGE_TYPE_METHOD_CALL.
José, any comment to comment 5? I can push the patch myself, but this seems to be a function that you are still developing or evaluating. I don't want to interfere with your work without your approval.
This comment is slightly (or completely) off-topic. It also concerns build_element_list() in Enum.pm, but it's not about documentation. GdkEventType contains pairs of enum constants with the same value. GDK_2BUTTON_PRESS = 5, GDK_DOUBLE_BUTTON_PRESS = GDK_2BUTTON_PRESS, GDK_3BUTTON_PRESS = 6, GDK_TRIPLE_BUTTON_PRESS = GDK_3BUTTON_PRESS, GDK_DOUBLE_BUTTON_PRESS and GDK_TRIPLE_BUTTON_PRESS were manually removed in http://git.gnome.org/browse/gtkmm/commit/?id=e7b3c1333f0de63672307612d5d5552d13ae3c30 Copied from the commit message: "However, I had to remove the changes to GdkEventType because gmmproc generates duplicate enums for that if I use the newly generated .defs." It would be fine if those enum constants could be removed by instructions in gdk/src/event.hg. _WRAP_ENUM(EventType, GdkEventType, s#^DOUBLE_BUTTON_PRESS$##, s#^2BUTTON_PRESS#DOUBLE_BUTTON_PRESS#, s#^TRIPLE_BUTTON_PRESS$##, s#^3BUTTON_PRESS#TRIPLE_BUTTON_PRESS# ) That would be possible if build_element_list() removed an enum constant with $name eq "" after the string substitutions. I can make a patch.
(In reply to comment #5) > Created an attachment (id=230898) [details] [review] > patch: gmmproc: Improve the documentation of enums. > > In Enum.pm, build_element_list(), wouldn't it be better to use original element > names, read from xxx_enums.defs, when searching for documentation? > > As an example, look at the enums in glibmm/gio/src/dbusmessage.hg. > "DBUS_" is removed from the names, e.g. > _WRAP_ENUM(MessageType, GDBusMessageType, s#^DBUS_##, NO_GTYPE) > > DocsParser::lookup_enum_value_documentation() does not find the modified names, > e.g. G_MESSAGE_TYPE_METHOD_CALL, but it finds the original names, e.g. > G_DBUS_MESSAGE_TYPE_METHOD_CALL. Yes, it would be better to search for the documentation of the enum values using the unmodified names. I have no objections to your patch since it only improves the docs.
I have pushed the patch in comment 5 (with a changed title): http://git.gnome.org/browse/glibmm/commit/?id=8d4160aa7c2b696224cdd3eb4848ee56625392df
Pushed a patch that implements the small improvement discussed in comment 7: http://git.gnome.org/browse/glibmm/commit/?id=76b64020e39c2205a847557f84be31c774c17a13
Is anything left to be done on this bug?
I don't think anything is left to be done. José should be able to give a definite answer. He's done at least 99% of the job on this bug.
I can't think of anything else to be done. Closing.
Sorry about closing this bug. Maybe there might have been further comments. Re-opening. As I said, I can't think of anything. I'm opened to other comments. If there are none, please feel free to re-close.
Really, it's fine and good to close bugs that you think are done. Thanks.