Re: RDP, GTK+-1.4



Owen Taylor wrote:
> 
> 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.

In my experience, inline docs are best when considered as part of
a "Reference Manual" instead of a "User Manual". The flow of the
documentation tends to be wrong for a user manual. Examples and such
often need to be updated because something changed that is unrelated
to the specific function being exampled.

If you want to have examples/"User Manual" information, you could
throw that documentation into the example's source file, and have
some way to automagically generate links in the functions being
exampled back to the example code.

> 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.

It would still be nice to be able to look at the header files and find
out why it is being defined. You could make a program that generates
stripped headers from the real headers if size were a problem
(have a .h.doc header that is used to generate a smaller .h file)

> (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.
> > >
> >

I'm for inline documentation. Things are more likely to have some
documentation if it is right there in front of the programmer,
shaming him if it is just name and nothing more, rewarding him if it is
clear and concise.

> > 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.
> 

Might as well put it in a seperate file instead of doing this.
The nice thing of inline docs is you can see a good description of the
code you are looking at, and it is easier to spot missing documentation
if it is always next to the function.

> 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.
>




[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]