GNOME Bugzilla – Bug 657444
"enum foo { ... }"; not recognized
Last modified: 2014-04-22 12:19:11 UTC
gtkdoc-scan doesn't recognize plain enums. It recognizes only: > enum _foo { ... }; (note the leading underscore) and > typedef enum ... { ... } foo;
... and the same for structs, apparently.
Well, the convention in GTK+/GNOME related software is to always typedef data types. gtk-doc assumes this convention and IIRC if you do enum _foo { ... }; you anyway get documentation for typedef enum { ... } foo; because that's the convention.
Fair enough, my use is not exactly GNOME-related, so I'll have to somehow deal with it.
Created attachment 273188 [details] [review] gtkdoc-scan.in: allow ordinary structs and enums to be documented Currently, structs will only be documented if they have a type definition, a forward declaration, or the struct name starts with an underscore. Enums are documented if the enum name starts with an underscore or it has a type definition. In both cases, if the enum or struct name begins with an underscore, it is assumed to be the declaration of the struct or enum without the underscore. This patch allows ordinary structs and enums to be documented, without the need for type definitions or forward declarations.
I have tested the patch against gtk+ and glib and it doesn't appear to make any difference to the documentation, with the exception of adding one symbol (a documented struct) to the gio documentation.
Thanks for the patch, out of curiosity, which symbol in gio did you saw.
The symbol is kqueue_notification, which appears in gio/kqueue/kqueue-thread.h. However, the headers in the kqueue directory are not installed and many of the symbols in them already appear in gio-unused.txt. The kqueue directory should probably be added to IGNORE_HFILES in docs/reference/gio/Makefile.am.
Review of attachment 273188 [details] [review]: Looks good. Just a small nit. ::: tests/bugs/src/tester.h @@ +88,3 @@ + * http://bugzilla.gnome.org/show_bug.cgi?id=411739 + */ +struct bug411739 { can please just add another struct and make this bug657444, so that the context is correct.
(In reply to comment #8) > Review of attachment 273188 [details] [review]: > > Looks good. Just a small nit. > > ::: tests/bugs/src/tester.h > @@ +88,3 @@ > + * http://bugzilla.gnome.org/show_bug.cgi?id=411739 > + */ > +struct bug411739 { > > can please just add another struct and make this bug657444, so that the context > is correct. This struct was added for testing bug 411739 and since it now needs to be documented, I renamed it to explicitly reference that bug. Would you prefer it to remain named as it was?
Right, that makes sense. Thanks for clarifying. I'll push this soon.
Hi, can you please re-upload a rebased patch?
Created attachment 274878 [details] [review] gtkdoc-scan.in: allow ordinary structs and enums to be documented
The following fix has been pushed: 598f6d7 gtkdoc-scan.in: allow ordinary structs and enums to be documented
Created attachment 274883 [details] [review] gtkdoc-scan.in: allow ordinary structs and enums to be documented