GNOME Bugzilla – Bug 648293
Fields of instance structs are ignored by gtk-doc
Last modified: 2014-03-01 19:29:43 UTC
Since upgrading to gtk-doc 1.16, building telepathy-glib's documentation has spat out a number of lines into the previously-empty telepathy-glib-unused.txt. These include: TpBaseConnection(self_handle, parent, object_path, bus_name, status) TpGroupMixin(remote_pending, self_handle, handle_repo, members, local_pending, priv, group_flags) TpPropertiesMixin(properties, priv) The structures themselves show up in the documentation, but their fields are ignored. I bisected this issue down to this commit: <http://git.gnome.org/browse/gtk-doc/commit/?id=6689f85421d54949effafb1164f18257927234c1> I spent some time trying to figure out what was actually broken in the code, but eventually resorted to moving things around in the affected headers in the hope of making it work. In these cases, moving the definition of the instance structs above the definitions of the class structs made gtk-doc pick the fields up again: <http://cgit.collabora.co.uk/git/user/wjt/telepathy-glib.git/commit/?h=gtk-doc-regressions&id=3cfc2c5e0513c880bbbe3d99052c862b17b09b4c>. There are many other headers in telepathy-glib where the class is defined before the instance, and I can't figure out why those work fine while these three do not. The fields of three other structures vanished, too: TpAvatarRequirements(supported_mime_types, maximum_bytes, recommended_width, minimum_height, maximum_width, recommended_height, maximum_height, minimum_width) TpContactInfoField(parameters, field_value, field_name) TpContactInfoFieldSpec(flags, max, name, parameters) In this case, the workaround that seems to work is to add redundant /*<public>*/ annotations: <http://cgit.collabora.co.uk/git/user/wjt/telepathy-glib.git/commit/?h=gtk-doc-regressions&id=7f0c9b626e208fbfd1a4b32ef9ad078c2ed06735>. I believe this was caused by the same commit, but my memory of the bisects may be wrong. (I have read bug 638449. This seems to be a somewhat different case to the case described in that bug: the files do not contain multiple definitions of the same symbols.)
Created attachment 209711 [details] [review] Fixes AddSymbolToList In the ScanHeader function in gtkdoc-scan, when it finds a class struct it adds a $list = "<TITLE>$objectname</TITLE>\n$list" to the $list. Thus, if afterwards an instance struct is found, when AddSymbolToList is called it would return false since "<TITLE>$objectname</TITLE>\n$list" will match m/\b\Q$symbol\E\b/ preventing from printing to DECL. This problem doesn't happen if the instance struct appears first in the header. Changing the regex to m/[^\>]\b\Q$symbol\E\b[^\<]/ fixes the problem.
The links to the collabora-repo don't work for me :/ Thanks for the patch. Will apply it after adding a new test to the regression suite.
(In reply to comment #2) > The links to the collabora-repo don't work for me :/ Sorry, I renamed my repo: http://cgit.collabora.com/git/user/wjt/telepathy-glib/commit/?id=3cfc2c5e0513c880bbbe3d99052c862b17b09b4c http://cgit.collabora.com/git/user/wjt/telepathy-glib/commit/?id=7f0c9b626e208fbfd1a4b32ef9ad078c2ed06735
Sorry that this is still pending. So is this still a problem? What I need in such case is *an example what the issue is. The comment #1 is not true (anymore), the title is only added when the list has been collected. https://git.gnome.org/browse/gtk-doc/tree/gtkdoc-scan.in#n861 FYI: gtkdoc has a 'test-suite'. If you have an issue that is not so obvious, write some fake code that demonstrates the issue. thanks.
Nope, it doesn't seem to be a problem any more – I tried reverting my workaround and the docs still built just fine. Thanks for asking!