GNOME Bugzilla – Bug 322035
wrong macro parsing
Last modified: 2007-09-23 14:16:32 UTC
if one uses macros-docs like this /** * GST_ERROR_SYSTEM: * * Returns a string using errno describing the previously failed system * call. To be used as the debug argument in #GST_ELEMENT_ERROR. */ #define GST_ERROR_SYSTEM ("system error: %s", g_strerror (errno)) then the macro appears in the undocumented list changing the docs to /** * GST_ERROR_SYSTEM: * * Builds a string using errno describing the previously failed system * call. To be used as the debug argument in #GST_ELEMENT_ERROR. */ works around the problem.
It is in gtkdoc-mkdb.in:2776 if (!$ignore_returns && m%^\s*(returns:|return\s+value:|returns\s*)%i) { $return_start = $1; $return_desc = $'; $in_return = 1; next; } Do we really want to allow 'Return' (without a ':') to start a returns: section. IMHO even 'return value:' is one variant to much.
I allowed those since that was what the GNOME people were using in their docs before they started using gtk-doc. I don't really think we can change that now, as it might break a lot of docs.
I did some grepping over e.g. gtk sources and I don'T think it breaks alot. The use sentences such as "Returns this and that" but also have a "Returns:" paragraph. Anyway for now I add it to the FAQ.
What about a warning in this case to help people to fix the old usage?
I wouldn't mind a warning. Note that in your original example gtk-doc was probably correct, as the macro does return a value and that should be documented, as well as the macro itself.
The patches in bug 380824 should address these issues.