Re: [GLIB Documentation] Improved Source docs for Glib?

[Ryan McDougall <ryan mcdougall telusplanet net>]

On Sat, 2004-01-03 at 10:57, Sven Neumann wrote:

> The correct place to put such an introductory comment is in the API
> reference. The GIOChannel introduction would go into
> docs/reference/glib/tmpl/iochannel.sgml. However there is some fairly
> complete documentation there already. Nevertheless there is of course
> always interest to see this improved.
> 
> 
> Sven

Thanks for replying, I was beginning to think no one wanted my efforts.
I see your point. I guess the poor state of source code documentation
had frustrated me to the point that what I email was overlapping with
whats there, although even when the API is decently documented there is
rarely anything about *why* one would use the API, or *why* the API is
the way it is. I will however merge what I emailed into the sgml.

You didn't specify anything about the source comments, so I'll wait
until I have a patch before I expect a comment. However, I really think
that to remedy the bad state of comments, I don't think the project
should accept undocumented code. Any patch should be *atleast*
internally commented, if not accompanied by a simple design doc, if the
complexity of the patch warrants it.

Also, if I am going through with comments I would very much like take a
little license with the order of declarations. For example place
commented delineaters separating and grouping certain sections to
improve readability. Is there an existent standard for such things (as
there is for coding style)? Are people even interested in me doing such
work?

Please let me know (don't ignore help)!

Cheers,
Ryan