Re: Documenting a struct with gtk-doc

[David Nečas <yeti physics muni cz>]

On Mon, Dec 14, 2009 at 06:05:56PM +0100, Aleksander Morgado wrote:
> So, I want to document the contents of a standard C struct in gtk-doc. The
> problem is that I don't typedef it, so rather than:
> 
> typedef struct {
>    int a;
> } my_struct;
> 
> the code is actually:
> 
> struct my_struct {
>    int a;
> };
> 
> 
> Now, if I use the typedef-version of the struct, I can successfully get the
> gtk-doc comment like, like
> /**
>  * my_struct:
>  * @a: whatever
>  *
>  * Pretty struct
>  */
> 
> But... what if I use the one without typedef, directly with the "struct"
> keyword?  If tried the above gtk-doc comment, and also one with "struct
> my_struct:" in first line of comment, but cannot get it properly compiling
> in gtk-doc html documentation...
> 
> Also, I know I can just:
> typedef struct my_struct {
>    int a;
> } my_struct_name2;
> 
> And document my_struct_name2... but anyway, is the non-typedef option
> possible?

gtk-doc does not understand much declarations beyond what is common in
Gtk+/Gnome code.  This is not (in fact, I can recall only two places
where non-typedefed structs are common: kernel and libc).  On the
contrary, there are some special conventions for naming of structs and
their typedefed types, such as that for type MyFoo the struct is called
_MyFoo, that gtk-doc must know about and apply.

I suggest to add a request for enhancement to Bugzilla.  Note however
the `gtk' in gtk-doc.  If your style deviates too much from the Gtk+
conventions, it might be never supported by gtk-doc.

Yeti