GNOME Bugzilla – Bug 728236
type annotation example for gobject properties needs work
Last modified: 2015-04-18 09:31:50 UTC
https://wiki.gnome.org/action/show/Projects/GObjectIntrospection/Annotations#G.28S.29List_contained_types has two examples that need review: = FooBar:alist: (type GSList(NiceObj)) = 1) GSList(NiceObj) is not a type, alternatives: a) (type GSList<NiceObj>) b) (type GSList)(element-type NiceObj) I prefer a) as it scales (consider GList<GArray<String>>) 2) we must not nest '()'. The annotations are parsed in gtkdoc using regular expressions. I can make this example work for annotation on the symbol-name level as there is no text following, but on parameter descriptions, matching extra '()' inside the annotation would require a handwritten parser. = Returns: (element-type Gtk.Widget) (transfer container): List of #GtkWidget = We should document on this page what TYPE means. Gtk.Widget reads well on the bindings level, but this notation is not consistently used. If we go this way should the property example be: (type G.SList<Nice.Obj>)?
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #0) > https://wiki.gnome.org/action/show/Projects/GObjectIntrospection/ > Annotations#G.28S.29List_contained_types > > has two examples that need review: > = FooBar:alist: (type GSList(NiceObj)) = > > 1) GSList(NiceObj) is not a type, alternatives: > a) (type GSList<NiceObj>) > b) (type GSList)(element-type NiceObj) > I prefer a) as it scales (consider GList<GArray<String>>) No, the wiki page is correct as (type GSList(NiceObj)) is the agreed upon syntax. > 2) we must not nest '()'. The annotations are parsed in gtkdoc using regular > expressions. I can make this example work for annotation on the symbol-name > level as there is no text following, but on parameter descriptions, matching > extra '()' inside the annotation would require a handwritten parser. I asked around about this 3 years ago on irc and in https://bugzilla.gnome.org/show_bug.cgi?id=676133#c17 when I tried to end the madness and make g-ir-scanner understand the actual real GTK-Doc comment block format. I was told on multiple occasions not to use angle brackets for the (type) annotation, but to use nested parens instead. Indeed resulting in the need to drop some regexes and use a parser-ish beast: https://git.gnome.org/browse/gobject-introspection/tree/giscanner/annotationparser.py#n1861 Note g-ir-scanner still accepts angle brackets for backward compatibility reasons: https://git.gnome.org/browse/gobject-introspection/tree/giscanner/annotationparser.py#n1788 So, I don't know if we need to be in a hurry to go and change this back to angle brackets, 3 years after deciding on parens? Maybe we should first decide and document the actual correct agreed upon GTK-Doc syntax for this once and for all... Well, this and other details, see https://bugzilla.gnome.org/show_bug.cgi?id=676133#c42 ;)
I'll give up here. I made the () work, but this will likely cause issues when there are multiple annotations on a symbol.