GNOME Bugzilla – Bug 678094
the word "returns" in a function description can be parsed as the "Returns:" section
Last modified: 2014-07-10 08:02:54 UTC
I had a function like this: /** * my_function: * @arg: arg * * This does some stuff. Don't use @arg again after the function * returns. * * Since: 3.4 */ And it got parsed as though it was: /** * my_function: * @arg: arg * * This does some stuff. Don't use @arg again after the function * * Returns: . * * Since: 3.4 */ (I'm not sure if the "Since" tag was necessary to trigger the bug or not.) There really ought to be a single mandatory standard format for the "Returns" line, rather than just sucking in anything that matches /^return/i.
The last time I tried to remove the fallback for 'returns' people where afraid that it breaks existing docs :/ I'll write a mail to desktop and tell that people have time until the next release to fix their packages and I'll remove legacy support in git, so that people can quickly try it. Does that sound like a plan?
worksforme. You could maybe make it just print a warning for now, and then switch to rejecting it later.
The warning is already there for ages. Just to clarify, is the my_function a void function (I guess so)?
I think so. (I don't remember what function it was now.)
A related problem with "returns", see the g_strsignal() documentation in GLib. /** * g_strsignal: * @signum: the signal number. See the `signal` documentation * * Returns a string describing the given signal, e.g. "Segmentation fault". * You should use this function in preference to strsignal(), because it * returns a string in UTF-8 encoding, and since not all platforms support * the strsignal() function. * * Returns: a UTF-8 string describing the signal. If the signal is unknown, * it returns "unknown signal (<signum>)". */ https://developer.gnome.org/glib/unstable/glib-String-Utility-Functions.html#g-strsignal
commit 5be5b88761bf4284c3a93f046247dd44ec85d874 Author: Stefan Sauer <ensonic@users.sf.net> Date: Thu Jul 10 07:26:32 2014 +0200 mkdb: drop legacy 'return' description handling We don't recognize sentences starting with 'Returns' as return docs anymore. This was ambigous and we printed a warning for this since years. FIxes #678094