Re: RDP, GTK+-1.4

[Matt Goodall <mgg isotek co uk>]

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?

>   - 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 understand the "noise" argument but in my experience I've found the
benefits of inline documentation far outway the disadvantages.

Cheers, Matt.

-- 
Matt Goodall             |  Isotek Electronics Ltd
email: mgg@isotek.co.uk  |  Claro House, Servia Road
Tel: +44 113 2343202     |  Leeds, LS7 1NL
Fax: +44 113 2342918     |  England