GNOME Bugzilla – Bug 663190
Type: GLib.List<Blob> breaks gtk-doc
Last modified: 2015-02-07 16:58:19 UTC
gtk-doc passes this as-is to the docbook machinery and all it sees is an unclosed tag... Can we change the format to GLib.List(Blob) or [Blob] or something that won't break my documentation? I think it's probably pretty trivial to change the scanner to accept both.
Created attachment 203993 [details] [review] Allow using GLib.List(Foo) instead of GLib.List<Foo> The <> was recognized as a tag by gtk-doc causing confusing.
Might want to use [] or {} too .. but since it's not an array or a block, () sounded more logical to me..
Review of attachment 203993 [details] [review]: This fixes a real problem, thanks for the patch. 1) This patch should include a regression test (use tests/scanner/regress.[ch]) 2) We should update the annotation wiki page 3) The commit message could be better, I'd use: Using < and > for delimiters is problematic because gtk-doc is Docbook which in turn is SGML, and those are reserved characters. ::: giscanner/maintransformer.py @@ +265,3 @@ args = [resolver(first)] + if sep in '<(': + while sep not in '>)': Your patch allows mismatched pairs like "(>". Maybe not a problem in practice, but it seems better to be restrictive here.
Created attachment 203994 [details] [review] Allow using GLib.List(Foo) instead of GLib.List<Foo> Updated patch, that syntax isn't on the wiki, we should definitely add it there. Also, while we're at it, Constructor: is also missing from the wiki. Using < and > for delimiters is problematic because gtk-doc is Docbook which in turn is SGML, and those are reserved characters.
Review of attachment 203994 [details] [review]: This should update the annotation docs at the live wiki as well ::: giscanner/maintransformer.py @@ +291,3 @@ return combiner(base, *rest) + print "type_str: " + type_str leftover? ::: tests/scanner/regress.c @@ +2049,3 @@ + pspec = g_param_spec_pointer ("list-old", + "GList property with ()", + g_object_class_install_property (gobject_class, <> and () ?
Created attachment 204105 [details] [review] Allow using GLib.List(Foo) instead of GLib.List<Foo> Oops, removed the leftover print. The reason to allow both <> and () is to not break existing annotations, but allow new annotations to be replaced by ().
Review of attachment 204105 [details] [review]: Looks good, thanks.
Comment on attachment 204105 [details] [review] Allow using GLib.List(Foo) instead of GLib.List<Foo> commit bfe51fb9472df24ca21c16f5d2af64f8533807e1 Author: Olivier Crête <olivier.crete@collabora.com> Date: Tue Dec 20 17:45:11 2011 -0500 Allow using GLib.List(Foo) instead of GLib.List<Foo> Using < and > for delimiters is problematic because gtk-doc is Docbook which in turn is SGML, and those are reserved characters.
Done!
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]