On Sat, Apr 27, 2013 at 12:02:24PM +0800, Yang Chengwei wrote:
> On Sat, Apr 27, 2013 at 12:24:43AM -0300, Lucas De Marchi wrote:
> > On Fri, Apr 26, 2013 at 11:38 PM, Yang Chengwei <chengwei.yang@xxxxxxxxx> wrote:
> > >
> > > I feel sorry to say that's true from my understand. It recognize
> > > typedef'ed enum and enum _foo {...}; In the later the document generated
> > > also say enum foo (no underscore), it's wrong if there is no typedef
> > > enum _foo foo since in fact no enum foo here.
> > >
> > > For detail, please refer to https://bugzilla.gnome.org/show_bug.cgi?id=657444
> > >
> > > So due to this limitation, the workaround I could say is use typedef as
> > > below:
> > >
> > > typedef enum foo {
> > > ...
> > > } foo;
> > >
> > > Is that acceptable to you? If no, I think I'll drop the second patch
> > > which try to document the exported enums.
> >
> > It's not acceptable in the public header and throughout the source
> > code. Since this is a limitation of gtk-doc and that in C you can add
> > the typedef anywhere, what could be done is to document these enums
> > hidden in the end of the respective .c file. And throughout the source
> > code we continue to use "enum ...". So you wouldn't touch the header,
> > but would have this, for example in the ende of
> > libkmod/libkmod-module.c:
> >
> >
> > /** kmod_module_probe_flags:
> > * @KMOD_PROBE_FORCE_VERMAGIC: remove version magic to force insert module
> > * @KMOD_PROBE_FORCE_MODVERSION: remove interface version to force insert module
> > * ...
> > */
> > typedef enum kmod_module_probe_flags kmod_module_probe_flags;
>
> Hmm, I just checked the latest gtk-doc git repo. It has very limit
> support for enum. Say it support:
>
> 1. plain enum named with underscore prefix.
> enum _foo {
> ...
> };
>
> 2. typedef'ed enum
> typedef enum foo {
> ...
> } foo;
>
> 3. another kind of typedef'ed enum
> typedef enum _foo foo;
> enum _foo {
> ...
> };
>
> Note the unerscore used here. So it doesn't support
> typedef enum kmod_module_probe_flags kmod_module_probe_flags; :-(.
>
> If I understand correctly, your goal is do not use typedef'ed enum like
> foo but enum foo in source code. I agree with you and I think it's fine
> with below:
>
> typedef enum foo {
> ...
> } foo;
>
> We can still use "enum foo" in any place else. But unfortuately, user
> will see that in docuement.
In addition, the document shows in
typedef enum {
...
} foo;
rather than how it write in header
typedef enum foo {
...
} foo;
So the user will get clue to always use "foo" rather than "enum foo",
this just violate kmod coding style! I think I'm giving up the second
patch. :-(, any suggestion?
--
Thanks,
Chengwei
>
> --
> Thanks,
> Chengwei
>
> >
> > Lucas De Marchi
Attachment:
signature.asc
Description: Digital signature
