Re: [PATCH 2/2] Add document about exported enum definitions

[Yang Chengwei]

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.y...@intel.com> 
> 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.

--
Thanks,
Chengwei

> 
> Lucas De Marchi

signature.asc
Description: Digital signature