GNOME Bugzilla – Bug 688204
undocumented enum values missing in indexes
Last modified: 2012-11-13 17:18:35 UTC
Gtk+ devhelp and index.sgml files lack entries for values from GtkTextDirection, GtkIconSize, GtkScrollType, ... enums. This can be observed, among other things, on a large number of cross-link resolution failure warnings during documentation generation. And, of course, the enum values are not searchable in develp either (the enum type itself is). Values from other enums work fine, for instance values from GtkOrientation, GtkPositionType, ... Apparently, the difference is that the former are undocumented while the latter are documented (but I have not confirmed it yet).
Maybe I should have added that the enums appear normally in the HTML docs, including all the values. They are missing just from the indexes. So it is not a source code markup issue; something in gtk-doc decides to avoid indexing undocumented enum values.
The cause is clear: What gets an XML id and can be cross-referenced? Items in the <variablelist> documenting individual values. But if no value is documented the [useless] <variablelist> is not emitted at all. The unclear part is how to fix it. I would not mind emitting even useless <variablelist>s for completely undocumented enums. I do not tend to have any. But others may differ. So another possibility is to emit a bunch of <anchor>s just after the <indexterm> of the enum type.
Good observation. I would also just emit a bunch of empty <variablelist>s. This will at least help people get to the doc for the enum itself. I never noticed as my own docs are always 100% complete :)
Created attachment 228873 [details] [review] patch This patch should do the trick (most of the changes are indentation level shifts). The handling of enum values becomes somewhat inconsistent with fields of other symbols because their tables are still omitted completely if none is documented. However, individual enum values are globally visible symbols themselves -- unlike, for instance function arguments.
Comment on attachment 228873 [details] [review] patch thanks for the patch, even though a git style one would have been easier to apply