GNOME Bugzilla – Bug 380824
docs are truncated if line begins with '* returns '
Last modified: 2007-09-22 19:15:57 UTC
* Returns: %TRUE if the value could be set correctly. If there was no field * with @fieldname or the existing field did not contain an int, this function * returns %FALSE. In the above example, gtk-doc needs to check if it is already in a 'returns' statement.
This was actually done deliberately, to handle the original GNOME docs which were a bit ambiguous. So any "Returns" found at the start of the line is assumed to document the return value, and any previous "Returns" found is assumed to be part of the function documentation. We could improve it slightly by assuming that any "Returns" with a ":" after it is definitely the return value documentation.
IMHO, that behavior is really irritating and the GNOME docs should be fixed to use more stringent syntax instead. Often you describe a function by writing "Returns the value of foo if bar ..." and gtk-doc incorrectly assumes that that is the description for the return value. I think it only should use @returns for that.
Good luck fixing all the gnome docs to use a more stringent syntax. Come back when you are done... @returns works if you prefer to use that, btw.
(In reply to comment #3) > Good luck fixing all the gnome docs to use a more stringent syntax. Come back > when you are done... Give me the list of packages you consider `all gnome', i.e. that have to be fixed before we can finally get rid of this rubbish. I looked at some and it isn't so bad. I assume deprecated stuff needs no fixing as no information is lost, the return value description will just move to the body, which should be good enough for functions no one should use anyway.
It is also a matter of fitting in, imo. Stylistically, "Return value: bla bla" looks much nicer in doc comment in the source code than " @returns: balbla" hidden in the parameter list
The form that should be used in the source is: * ... * * Returns: the byte size, or 0 if there was an error * */
Ah, right. I see what is being complained about here. I think Damons proposal is a good one, to give any "return line start" that ends with a : a higher priority than one without a :.
(In reply to comment #7) > Ah, right. I see what is being complained about here. I think Damons proposal > is a good one, to give any "return line start" that ends with a : a higher > priority than one without a :. Is is necessary to complicate it further? Matthias, I don't see the `old Gnome documentation' argument backed by any hard data. It is easy to obtain it: build the documentation with and without accepting bare Returns in the parser and diff foo-undocumented.txt (where new `foo_blow_up (Returns)' will show up). It just takes lots of CPU time. With this data, one can actually weigh the impact and also fill bugs and fix the documentation. So please give me the list of packages that have to be fixed to enable switch to the stricter syntax.
I wouldn't want to break backwards compatability though. We don't know all the places where gtk-doc is used. Anyway, if we say that explicit "Returns:" has the highest priority the problem will only affect people with ambiguous documentation.
(In reply to comment #9) > I wouldn't want to break backwards compatability though. We don't know all the > places where gtk-doc is used. OK, so let's at least start producing warnings on free-form Returns as suggested in bug 322035. This will enable us to actually remove the support for them in the future. (Also note nothing terrible will happen to the old Returns, they will just move to the description body.)
Created attachment 91511 [details] [review] proposed patch Implements basic Returns priorities: old style Returns block cannot break sane Returns block. I don't like how old-style Returns can still break *other blocks* though.
Created attachment 91512 [details] [review] proposed patch (warning) To be applied on top of patch 91511. Adds a warning when old-style Returns is found and no new style one, i.e. if after all parsing all we got is an old-style Returns.
Created attachment 91514 [details] [review] proposed patch Patch 91511 is incomplete. We should also catch the situation when we find a free-form Returns in the description and we already have a strict Returns.
Thanks for the patch! I run it against gstreamer and buzztard. Now isuues found. I am fixing the few warnings it spotted. +1 from my side to get this committed.
When I build gst-plugin-base docs from CVS I get: Use of uninitialized value in concatenation (.) or string at /usr/bin/gtkdoc-mkdb line 2985, <SRCFILE> line 95. I added: if ($in_since) { if (m%^\s*(returns:|return\s+value:|returns\b\s*)%i) { if (! defined $return_start) { print "!!! no return_start\n"; } if (! defined $return_desc) { print "!!! no return_desc\n"; } if (! defined $description) { print "!!! no description\n"; } $description .= $return_start . $return_desc; $return_start = $1; and it says "!!! no return_start".
(In reply to comment #15) > When I build gst-plugin-base docs from CVS I get: > Use of uninitialized value in concatenation (.) or string at > /usr/bin/gtkdoc-mkdb line 2985, <SRCFILE> line 95. I can reproduce this problem, but it occurs regardless my patch is applied or not. It even occurs with stock gtk-doc-1.8. It looks like a bit too much liberal application of copy'n'paste. I can't see any reason why anything should be done with $return_start if we are not $in_return, but $in_since or $in_stability instead.
Created attachment 91625 [details] [review] proposed patch (cumulative) Comment 15 is probably a separate problem. The fix touches the same lines, so I attach a single patch that contains the two previous and fixes comment 15 as well.
Its not fixed, but I found the fix needed for gtkdoc-mkdb.in: @@ -2830,7 +2831,9 @@ $in_since = 0; $in_deprecated = 0; $description = ""; + $return_start = ""; $return_desc = ""; could you please add this to your patch?
2007-07-15 Stefan Kost <ensonic@users.sf.net> Patch by: Yeti <yeti@physics.muni.cz> * gtkdoc-mkdb.in: Improve handling of legacy "return" statement doc parsing. Warn about those.
The fix has a sideeffect still. See new bug #457077.
I'm confused. I got some conflicts on svn up and it seems the $description .= $return_start . $return_desc; statements in non-$in_return branches are still there. It seems what I attached as patch 91625 in comment 17 was not the final revision, I'm sorry. Now, to comment 18: In my opinion this is wrong and it only hides the real problem: manipulation with $return_start where it makes no sense at all.
Created attachment 91846 [details] [review] patch This is what was missing. Note it removes both the initialization of $return_start and its bad accesses (if there are more bad accesses, we will see them as it's kept uninitialized).
For the record, I've been hit by this too. I have had to reword function description to make gtk-doc pick it up, instead of parsing to return-value lines...
@Behdad, can you retry with gtkdoc from svn trunk? If it still happens, please reopen the bug.
It still happens. Will look into this later /** * gst_adapter_take_buffer: * @adapter: a #GstAdapter * @nbytes: the number of bytes to take * * Returns a #GstBuffer containing the first @nbytes bytes of the * @adapter. The returned bytes will be flushed from the adapter. * This function is potentially more performant than gst_adapter_take() * since it can reuse the memory in pushed buffers by subbuffering * or merging. * * Caller owns returned value. gst_buffer_unref() after usage. * * Since: 0.10.6 * * Returns: a #GstBuffer containing the first @nbytes of the adapter, * or #NULL if @nbytes bytes are not available */
When ever we parse a broken return, we need to remember which part we were parsing (in_since, in_description,...). If we encounter a real Returns: we have to append that broken return to the docs it belongs to (since_desc, description, ...).
Lazy fix that assumes that since/deprecated/stability won't start with 'returns '. 2007-08-13 Stefan Kost <ensonic@users.sf.net> * gtkdoc-mkdb.in: Now the 'broken' returns seems to work better. Fixes #380824 more.