GNOME Bugzilla – Bug 642998
Struct members aren't detected
Last modified: 2011-04-06 08:57:14 UTC
The following code in a header file[1]: /** * GDataColor: * @red: red color intensity, from 0–255 * @green: green color intensity, from 0–255 * @blue: blue color intensity, from 0–255 * * Describes a color, such as used in the Google Calendar interface to * differentiate calendars. **/ typedef struct { guint16 red; guint16 green; guint16 blue; } GDataColor; causes gtk-doc to emit the following warnings: gtk-doc: Building XML ../../gdata/gdata-types.h:36: warning: Field description for GDataColor::green is not used from source code comment block. ../../gdata/gdata-types.h:36: warning: Field description for GDataColor::blue is not used from source code comment block. ../../gdata/gdata-types.h:36: warning: Field description for GDataColor::red is not used from source code comment block. ../../gdata/gdata-types.h:36: warning: Field description for GDataColor::foo is not used from source code comment block. ./gdata-unused.txt:1: warning: 1 unused declarations.They should be added to gdata-sections.txt in the appropriate place. gtk-doc: Building HTML I can't see what's wrong with the documentation or the C declaration itself. The problem isn't being caused by my use of Unicode characters in the comments, as the same warnings are emitted if the Unicode characters are removed. This might be a regression in gtk-doc, as I'm fairly sure this worked a while ago; it's certainly broken with (master, 145510fe584800d6e8582174d9579cba696e9458) though. The relevant section from gdata-sections.txt[2] is: <SECTION> <FILE>gdata-types</FILE> <TITLE>GData Types</TITLE> GDataColor gdata_color_from_hexadecimal gdata_color_to_hexadecimal <SUBSECTION Standard> GDATA_TYPE_COLOR gdata_color_get_type </SECTION> If there's any more debug info I can provide, please let me know. This was spawned from bug #642983. [1]: http://git.gnome.org/browse/libgdata/tree/gdata/gdata-types.h [2]: http://git.gnome.org/browse/libgdata/tree/docs/reference/gdata-sections.txt
Does this work? /** * GDataColor: * @red: red color intensity, from 0–255 * @green: green color intensity, from 0–255 * @blue: blue color intensity, from 0–255 * * Describes a color, such as used in the Google Calendar interface to * differentiate calendars. **/ struct _GDataColor { guint16 red; guint16 green; guint16 blue; }; typedef struct _GDataColor GDataColor;
(In reply to comment #1) > Does this work? Nope, I still get the same warnings.
Is there any more information I can provide?
No, I'll make a test-case patch for gtk-doc soon and investigate. If you can remember still with which version it worked, that would help.
commit e1030f9f3be5223169c085639119c3a02515f483 Author: Stefan Kost <ensonic@users.sf.net> Date: Tue Mar 29 21:21:35 2011 +0300 tests: add a test case for bug #642998 and btw. the end of the doc comment is "*/" and not "**/" (that's not the issues here). Please re-open if you still see the issue.
(In reply to comment #5) > commit e1030f9f3be5223169c085639119c3a02515f483 > Author: Stefan Kost <ensonic@users.sf.net> > Date: Tue Mar 29 21:21:35 2011 +0300 > > tests: add a test case for bug #642998 > > and btw. the end of the doc comment is "*/" and not "**/" (that's not the > issues here). > > Please re-open if you still see the issue. Still got an issue with (master, 22ecc8ce9d5a739360c03772081991c180c58196). I've done some git bisecting, and this appears to be the gtk-doc commit which first caused the warning messages in libgdata: 836f653025803ca8e26b2069f9b665debbd7c5eb. http://git.gnome.org/browse/gtk-doc/commit/?id=836f653025803ca8e26b2069f9b665debbd7c5eb
Perhaps, it would have saved my 1 day of my time if you would have mentioned that this is a boxed type! This is a known issue, where I am not sure how to fix it in a backwards compatible way. For gritty details see: https://bugzilla.gnome.org/show_bug.cgi?id=605025 For now this should solve it: typedef struct { /* < public > */ guint16 red; guint16 green; guint16 blue; } GDataColor; If you agree, we can close this as a duplicate.
(In reply to comment #7) > Perhaps, it would have saved my 1 day of my time if you would have mentioned > that this is a boxed type! Sorry, that fact didn't come to mind. > This is a known issue, where I am not sure how to fix it in a backwards > compatible way. For gritty details see: > https://bugzilla.gnome.org/show_bug.cgi?id=605025 > > For now this should solve it: > > typedef struct { > /* < public > */ > guint16 red; > guint16 green; > guint16 blue; > } GDataColor; > > If you agree, we can close this as a duplicate. That has fixed the problem, thank you very much! Sorry for wasting your time. :-( *** This bug has been marked as a duplicate of bug 605025 ***
(In reply to comment #8) > (In reply to comment #7) > > Perhaps, it would have saved my 1 day of my time if you would have mentioned > > that this is a boxed type! > > Sorry, that fact didn't come to mind. > > > This is a known issue, where I am not sure how to fix it in a backwards > > compatible way. For gritty details see: > > https://bugzilla.gnome.org/show_bug.cgi?id=605025 > > > > For now this should solve it: > > > > typedef struct { > > /* < public > */ > > guint16 red; > > guint16 green; > > guint16 blue; > > } GDataColor; > > > > If you agree, we can close this as a duplicate. > > That has fixed the problem, thank you very much! Sorry for wasting your time. > :-( > > *** This bug has been marked as a duplicate of bug 605025 *** No worries, also an apology if that came over a bit harsh. gtk-doc maintenance is a bit lonely right now. Most of the bugs RFE's and I'd be really glad about getting votes/opinions from people here that use gtk-doc.