GNOME Bugzilla – Bug 457077
add --no-implicit-returns to gtkdoc-mkdb
Last modified: 2007-09-22 19:54:00 UTC
The fix for Bug #380824 unfortunaltely generates a warning about the broken return comment. /** * SECTION:bla * @short_description: helper interface ... * * Furthermore it adds the gst_property_meta_describe_property() method that * returns a string description of a property value. */ Maybe it makes sense to add --no-implicit-returns to gtkdoc-mkdb,
Hm, shouldn't we ignore returns statements in section documentation in the first place?
A note to the original report: The warning only makes the problem *visible* (which is a good thing), it has been always there and gtk-doc has always parsed the thing as a return value documentation. So this is not a side-effect, but the intended effect. Now to the ignoring. We have %SymbolParams from the template. Therefore we always know whether we expect a return statement or not -- except for macros. But we also have things that can in principle return something: functions, user functions, signals (and macros). And things that cannot return anything: enums, structs, properties, sections. I do not want old-style Returns to be recognized in the latter at all. The strict syntax should be recognized, because that's something I do not type by accident and therefore I want a warning. Personally, I do not want old-style Returns to be recognized anywhere else either, but adding an option would make this (desirable) behaviour opt-in. And once something is opt-in it's difficult to make it the default as `anyone can opt-in'. So, should I make a patch to ignore old-style returns in symbols that cannot return anything?
Yes, I was first tempted to do some quick hack to ignore it for sections, but realized that it needs more thinking. A patch that skips the old-style return parsing for enums, structs, properties, sections would be great as it reduces the likelyhood to get hit by the problem. We can still add the option later, if there is enough demand.
Can I count with patch 91846 (bug 380824) as committed and work on top of that? I'm afraid I might have to start using quilt...
I spoke too early. The processing goes as 1. read source file documentation <- here we would like to know symbol types 2. read sections file and according to <FILE>s there 3. read template files <- here we learn the symbol types It seems to me the major restructuring required to get the symbol types before reading the source files does not worth it.
Created attachment 91860 [details] [review] proposed patch However, not everything is lost, section documentation can be handled specially. The attached patch does this, it also unified the use of $ignore_returns -- renamed to $ignore_broken_returns. Now `Returns:' will be processed and cause a warning if it appears after `@returns:', which is desirable I think.
I still get this in WARNING: Free-form return value description in SECTION:tester. Use `Returns:' to avoid ambiguities. tests/bugs/docs/gtkdoc-mkdb.log.
2007-07-18 Stefan Kost <ensonic@users.sf.net> Patch by: Yeti <yeti@physics.muni.cz> * gtkdoc-mkdb.in: Cleanup broek-return handling and add ignore_broken_returns for section docs. Fixes #457077
Is comment #7 still an issue? And if it is, how to reproduce it?
No, its fixed. Thanks for the patch. I modified it a little.