[webkit-dev] class comments should be encouraged

[Per Bothner]

[For the record, in an appropriate thread.  No need to respond
if you feel this has been adequately discussed in the past.
I'm happy to let the thread die.]

The biggest WebKit annoyance I have is lack of class-level comments.
For example what is an Interpreter?  How many instances are there in the 
system?
(I.e. is it a singleton class?  Is there one per window? One per thread?)
What is the relationship to JSGlobalData, JSGlobalObject, RootObject.
There are a lot of these classes, and it takes quite a bit of staring at
the code to figure it out. Worse, it's hard to remember it all, so if I
come back to the codebase after working on something else I have to
figure out all out again: I might remember some aspects (like a class
starting with JS is probably some kind of JavaScript object), but not
a lot of other relationships and properties of the classes.

Documenting what a function/method does is sometimes useful,
but what is really important is documenting what (an instance of)
a class *is* and (preferably) how it relates to other objects.
-- 
	--Per Bothner
per.bothner at oracle.com   per at bothner.com   http://per.bothner.com/