GNOME Bugzilla – Bug 727778
gtk-doc doesn't understand annotations for GList-contained types
Last modified: 2015-04-18 09:30:53 UTC
I have a doc comment block similar to the one described on this page: https://wiki.gnome.org/action/show/Projects/GObjectIntrospection/Annotations?action=show&redirect=GObjectIntrospection%2FAnnotations#G.28S.29List_contained_types /** * FooBar:alist: (type GSList(NiceObj)) * * This property is a GSList of NiceObj GObjects. */ g_object_class_install_property (object_class, FOO_BAR_PROP_ALIST, g_param_spec_pointer ("alist", "Alist", "A list of nice objects", G_PARAM_READWRITE)); With gtk-doc master (1.20.1), this generates warnings during the "Building XML" phase: "warning: Symbol name not found at the start of the comment block." (the file and line number refer to the closing */ of the doc comment.) Gtk-doc isn't picking up that "FooBar:alist: (annotation)" is an identifier for "FooBar:alist:". I think this causes the whole doc comment to be ignored, since the description for the property in the generated HTML documentation reverts to the property's blurb string: "A list of nice objects".
Good catch. I can make the above parse, but I am afraid this is underspecified. I filed a blocking bug. In the meantime I'll also hack gtkdoc so that the annotation is used in the resulting docs (which it is not right now).
Created attachment 274630 [details] [review] Allow annotations property docs
So the hack doesn't care about whether the parens are matched? That seems reasonable to me until #728236 is solved more sustainably... (but I'm not a gtk-doc dev so don't count my review as the final word)
Created attachment 274939 [details] [review] Allow annotations property docs Do you have any opinion on where to place the annotations? In other cases we show the annotation right aligned in the param table or below the "Returns" docs. My take on this would be to show it after the property description. Does that sound good to you?
I think that sounds good. It would go with the other property annotations such as "Default value", "Flags", etc.
commit 53ead54371bcae7b5a7b1216886eb5ae7d77d293 Author: Stefan Sauer <ensonic@users.sf.net> Date: Sat Apr 18 11:27:41 2015 +0200 mkdb: allow annotations for property and signal docs. Fixes #727778 commit d3ac88b596bf2232a653852a984b359eb2e80c04 Author: Stefan Sauer <ensonic@users.sf.net> Date: Sat Apr 18 11:03:13 2015 +0200 mkdb: Allow annotations for property docs. Fixes #727778