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 457077 - add --no-implicit-returns to gtkdoc-mkdb
add --no-implicit-returns to gtkdoc-mkdb
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other Linux
: Normal enhancement
: 1.9
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2007-07-15 10:03 UTC by Stefan Sauer (gstreamer, gtkdoc dev)
Modified: 2007-09-22 19:54 UTC
See Also:
GNOME target: 2.20.x
GNOME version: ---


Attachments
proposed patch (4.71 KB, patch)
2007-07-16 15:42 UTC, Yeti
committed Details | Review

Description Stefan Sauer (gstreamer, gtkdoc dev) 2007-07-15 10:03:19 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,
Comment 1 Yeti 2007-07-16 08:07:26 UTC
Hm, shouldn't we ignore returns statements in section documentation in the first place?
Comment 2 Yeti 2007-07-16 09:12:18 UTC
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?
Comment 3 Stefan Sauer (gstreamer, gtkdoc dev) 2007-07-16 14:16:06 UTC
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.
Comment 4 Yeti 2007-07-16 14:41:39 UTC
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...
Comment 5 Yeti 2007-07-16 15:36:35 UTC
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.
Comment 6 Yeti 2007-07-16 15:42:31 UTC
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.
Comment 7 Stefan Sauer (gstreamer, gtkdoc dev) 2007-07-18 18:12:19 UTC
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.
Comment 8 Stefan Sauer (gstreamer, gtkdoc dev) 2007-07-18 18:53:39 UTC
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
Comment 9 Yeti 2007-07-21 15:40:36 UTC
Is comment #7 still an issue?

And if it is, how to reproduce it?
Comment 10 Stefan Sauer (gstreamer, gtkdoc dev) 2007-07-22 10:14:39 UTC
No, its fixed. Thanks for the patch. I modified it a little.