After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 613611 - parameter descriptions with annotations truncated at first \n
parameter descriptions with annotations truncated at first \n
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
1.14
Other Linux
: Normal normal
: 1.14
Assigned To: Stefan Sauer (gstreamer, gtkdoc dev)
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2010-03-22 17:06 UTC by Simon McVittie
Modified: 2010-03-23 11:40 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
tests/gobject: check that long parameter descriptions work (they do) (823 bytes, patch)
2010-03-22 17:13 UTC, Simon McVittie
committed Details | Review
Don't truncate annotated param descriptions at newline. Fixes #613611 (804 bytes, patch)
2010-03-22 17:14 UTC, Simon McVittie
committed Details | Review
Add a long annotated parameter description (regression test for #613611) (889 bytes, patch)
2010-03-22 17:14 UTC, Simon McVittie
committed Details | Review
Check that multi-line annotated Returns: descriptions work (932 bytes, patch)
2010-03-22 17:15 UTC, Simon McVittie
committed Details | Review

Description Simon McVittie 2010-03-22 17:06:05 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.
Comment 1 Simon McVittie 2010-03-22 17:13:53 UTC
Created attachment 156770 [details] [review]
tests/gobject: check that long parameter descriptions work (they do)
Comment 2 Simon McVittie 2010-03-22 17:14:16 UTC
Created attachment 156771 [details] [review]
Don't truncate annotated param descriptions at newline. Fixes #613611
Comment 3 Simon McVittie 2010-03-22 17:14:32 UTC
Created attachment 156772 [details] [review]
Add a long annotated parameter description (regression test for #613611)
Comment 4 Simon McVittie 2010-03-22 17:15:13 UTC
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].
Comment 5 Simon McVittie 2010-03-22 17:19:02 UTC
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
Comment 6 Stefan Sauer (gstreamer, gtkdoc dev) 2010-03-23 11:40:41 UTC
Thanks for the patches and the tests!