Re: RDP, GTK+-1.4

[Owen Taylor <otaylor redhat com>]

Matt Goodall <mgg@isotek.co.uk> writes:

> Owen Taylor wrote:
> > 
> >  Disadvantages:
> > 
> >   - Can lead to paying attention to the function docs while neglecting
> >     structure/enumeration docs and section overview docs which are
> >     not inline.
> 
> Why can't those be inline too? Is that a limitation of gtk-doc?

Yes. It is, of course, a limitation that can be changed. 

I would not want to put the section overview docs inline. We
are talking extensive chunks (pages in some cases) with
examples, links to figures, etc. Stuffing that into a comment
doesn't make much sense.

Putting the structure/enumeration docs inline does make more sense.
My concern here is that while I'm not very concerned about noise
in the .c files (at worst, it forces you to use etags or something
like that), having big blocks of comments in the headers does
make them harder to read. And the headers are the only natural
place to document structures and enumerations.

(Header files have a function as overview documentation as
well as their function as declarations for the compilers.)
 
gtk-doc almost certainly should _allow_ structure/enumeration 
docs inline, in any case, whether we use them for GTK+ or
not.

> >   - Some (timj) consider the inline docs excessive noise in the code,
> >     especially for things like:
> > 
> >      gtk_label_set_text:
> >      @label: a #GtkLabel
> >      @text: the new text for the label
> > 
> >      Sets the text in the label.
> > 
> > I'm a bit in favor of going to inline docs.
> > 
> > I'd appreciate any thoughts, opinions, whatever, on these issues.
> > 
> 
> Many inline documentation tools (don't know about gtk-doc) allow the
> documentation comments to be placed away from the actual code, often at
> the bottom of the header. Would that help? The only problem with this is
> that the documentation isn't right next to the code and so it's easy to
> overlook when things change.

I don't see any advantage of putting the docs in the header file
but away from the code as opposed to in a separate file.

Regards,
                                        Owen