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

[Ryan McDougall <ryan mcdougall telusplanet net>]

Firstly Owen, thanks for the detailed reply!

On Mon, 2004-01-05 at 08:46, Owen Taylor wrote:
> 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.

I know a bit about doxygen and how you guys document the API, but in
general I don't mind putting that sort of stuff directly into the
source, especially Header files -- however I will in future submit
patches on the sgml for that kind of thing.

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

A agree that clear code undocumented is always preferable to sloppy
documented code, but I think we should be raising the bar even further.
Good code is the minimum, and some basic documentation should be added
to the list. What *I* would like to see in the future from all F/OSS
projects, is for each .c/.h pair at least one paragraph about why the
code exists with one example as to how the code solves this problem, one
page design document giving some detail as to how the code was put
together, one paragraph for each non-trivial algorithm, and one comment
block for *each* function and datatype. Each of these will be written,
not for the core/expert hacker, which probably can deduce the above from
the code alone, but for people like myself who have university level
coding skills, but not much "real-world" engineering experience.

The current documentation almost covers all of the above, but not in a
comprehensive fashion. Some parts have most but not all of the above,
but there are many holes that need to be filled.

My goal in seeking this is not to place an onerous burden on the hard
working core hackers like yourself, but to lower the barrier to entry of
mid-level hackers like myself so that we can lessen your burden in the
long term -- and even become core hackers.

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

As above, I disagree here. The audience for source code should be lower
than that, and I don't assume that GTK+ always goes hand-in-hand with
Glib. For example, I have used Glib for several console based apps, but
I have yet to build anything serious with GTK+.

The bar should be lowered, and the documentation level accordingly to
ease the entry of non-expert developers. I actually have a fear, born of
my recent experiences, that in the not too future any moderately popular
F/OSS project will be entirely written and controlled by professional
engineers from big companies. This will not be because of any
maliciousness, but simply the complexity of the code and the demands of
the professionals' time will force them to exclude anyone not from a
recognized entity, like myself. I hope thats not the kind of community
we wish to see in the future -- for my part I want to help lower the bar
with your help!

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

I hope you have the time to answer my other recent email regarding gmem.

Thanks for you time Owen, I hope I can work further with you and the
rest of the GTK+ team!

Cheers,
Ryan