GNOME Bugzilla – Bug 613611
parameter descriptions with annotations truncated at first \n
Last modified: 2010-03-23 11:40:41 UTC
When a parameter has annotations and also has a line-wrapped description, like this rather contrived example: /** * annotation_nullable: * @uri: a uri - * @label: (allow-none): an optional string + * @label: (allow-none): an optional string, which is used in ways too + * complicated to describe in a single line, making it necessary to wrap it * * Document optional parameters. * * Returns: (transfer full) (allow-none): Returns stuff which you have to free after use */ the HTML output loses everything after the first newline. The same parameter with no annotations works fine. The single-character fix is to change gtkdoc-mkdb.in like this (I'll attach in git format once I have a bug number): @@ -2623,11 +2623,11 @@ sub ExpandAnnotation { "unknown annotation \"$annotation\" in documentation for $symbol."); $param_annotations=$annotation; } } chomp($param_desc); - $param_desc =~ m/^(.*)\.*\s*$/; + $param_desc =~ m/^(.*)\.*\s*$/s; $param_desc = "$1. "; } return ($param_desc, $param_annotations); } I haven't yet verified whether long, annotated Returns lines work.
Created attachment 156770 [details] [review] tests/gobject: check that long parameter descriptions work (they do)
Created attachment 156771 [details] [review] Don't truncate annotated param descriptions at newline. Fixes #613611
Created attachment 156772 [details] [review] Add a long annotated parameter description (regression test for #613611)
Created attachment 156773 [details] [review] Check that multi-line annotated Returns: descriptions work It turns out these either worked already, or were also fixed by Attachment #156771 [details].
For those who prefer git remotes: * git://git.collabora.co.uk/git/user/smcv/gtk-doc.git * http://git.collabora.co.uk/?p=user/smcv/gtk-doc.git;a=shortlog;h=refs/heads/long-annotated-params
Thanks for the patches and the tests!