Re: RDP, GTK+-1.4

[Eric Lemings <eric b lemings lmco com>]

> Damon Chaplin <damon@helixcode.com> writes:
> 
> > Owen Taylor wrote:
> > 
> > > I'm a bit in favor of going to inline docs.
> > 
> > I think inline docs are a bit better, mainly because it makes it more
> > likely that the docs will be written (and by the author of the code, so
> > any unusual/difficult stuff is described).
> > 
> > I think documenting stucts/enums/macros/function typedefs in header
> > files
> > would also be good. They really should be documented there anyway, so
> > I don't think the gtk-doc overhead is too bad.
> 
> Actually, looking it, structs and enums should be quite simple. I'll
> see if I can find some time to do that.
> 
> macros and function typedefs may be a little harder, but not much
> harder.
>                                         Owen

In recent use of gtkdoc, I've noticed that gtkdoc scripts do not handle
struct, union, enum, and typedef declarations very well.  I don't know
exactly how the scripts work internally but I think the scripts assume
that each enum/struct/union is declared within the associated typedef
and that the enum/struct/union tag is not present or is different from
the name of the typedef.  Example,

typedef enum
{
  pfx_false,
  pfx_true,
} pfx_bool;

The following example, however, does not work very well with gtkdoc
although it is perfectly legal (and IMHO good style as well):

enum pfx_bool
{
  pfx_false,
  pfx_true
};

typedef enum pfx_bool pfx_bool;

It's a little more verbose but it seperates the enum declaration (in
this case) from the typedef declaration.  Why would you want to do
that?  Well, the typedef does not always have to be simply an alias for
the associated struct/union/enum.  You might want to make 'pfx_list' a
pointer to 'struct pfx_list' for example.

Just something to consider.

Eric.