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

[Owen Taylor <otaylor redhat com>]

On Mon, 2004-01-05 at 12:56, Ryan McDougall wrote:
> 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.

(We don't use doxygen, actually)

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

You can often find "design docs" by searching the archives of
gtk-devel-list, especially for things added within the last 5 years
or so. (Note that the archive search on mail.gnome.org doesn't work
currently, so use google.)

> 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 audience for source code certainly includes less experienced 
people. But I don't think we can afford to comment the code for
those people, because at some level too many comments hinders
readability. 

If I comment:

 /* Override the realize method so we can create extra GdkWindow's */
 widget->realize = gtk_entry_realize;

Then I've suddenly made the code much longer and harder to read.

Reading source code typically is a bit of a stretch. But if there
is documentation at the level I've sketched out in my first mail,
I think it should be accessible. If it's not, then it's likely
the fault of the code, not the docs. (gtk+/gdk/x11/gdkgeometry-x11.c
is really, really hard to figure out, and the two page block 
comment at the top doesn't fix that.)

By "GTK+ (resp. GLib)", I just meant "the project at hand"

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

I think you are underestimating the power of contributors to figure
out complex code. The best way, IMO, to get familar with a complex
piece of code is to find some problem that you want to solve, and then
figure out how you'd go about solving it. Working through code "in
action" rather than in the abstract can make it make a lot more sense.

Should there be more comments in the GTK+ sources?
Yes! Much of GTK+ isn't nearly up to the level of commenting that
I sketched out in my last mail.

Should there be more documentation of GTK+ internals? Certainly! Given
sufficient resources, I'd love to see many of the text files from
gtk+/docs/ updated and extended and turned into a nice "hacking
GTK+" manual.

But in general, I think that the public interface to GTK+ is the 
API docs, and the internals are 

[...]

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

Unfortunately, no, I don't, though I may respond with a pointer or
two that may help clarify.

						Owen