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

[Owen Taylor <otaylor redhat com>]

On Sat, 2004-01-03 at 15:19, Ryan McDougall wrote:
> 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.

This type of stuff generally belongs in the API docs. We intentionally
use an API documentation system that allows us to put arbitrary amounts
of introductory text and examples before the function-by-function
documentation.

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

We generally value clarity far more than comments in code. If the
API is documented, and the code is written in a clear style, there
isn't always a lot left to comment. 

My general feeling on what should be documented:

- Files that implement a complex algorithm should get a block 
  comment describing that algorithm at the top.
- static functions that have non-obvious parameters or purpose
  should have a small (one or two line comment) before them.
  (Virtual function implementations can generally be considered to
  have obvious parameters and purpose.)
- Interfile entry points should generally be documented
  like public API functions, with doc-comment blocks.
- Any non-obvious lines of code or sequences should get a short
  comment. What's non-obvious is clearly dependent on the 
  reader.

  The reader I'd generally envision:

   - Is an expert programmer with GTK+ (resp. GLib)
   - Has hacked on other parts of the GTK+ source code,
     but not necessarily this file.

- When a single function does more than one thing, there should
  be a comment heading each separate "thing" that the function does.


Comment style guidelines that I follow are:

  /* Comment on a single line of code */
  a = 1 + 1;

  or:

  a = 1 + 1;    /* Short comment on a single line of code */

  /* Comment on a block of code
   */
  for (i = 0; i < 10; i++)
    {
    }
 
> 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?

I'd probably have to see an example to say.

Regards,
					Owen