[OGo-Documentation] code documentation

[Adam Tauno Williams]

> I'm going to try to write new development documentations, a bit more high 
> level. While doing that, I have to wade through a lot of source files, 
> figuring out, how things are working. 
> E.g. after get the OGoAddressMapLink using a SkyExternalLink or sth. 
> similar, I wanted to add a plone page, how to create and use OGoUIElements.
> While doing that, I would add documentation comments to the source files, 
> e.g. GSDoc, or doxygen?
> Is there any kind of automatic code generation stuff used already, then I'd 
> stick to that, if not, are there any preferences?
> Well, GSDoc should be fine, as it is designed for GNUstep/Objective-c stuff, 
> but e.g. doxygen might have more features,... (ok, don't know whether these 
> more features are useful at all for the ogo docs)

I'd prefer doxygen since it is widely known and available;  but don't
know how well it works with Objective-C.  If it can't recognize
categories or build cross reference tables allot of the value is lost.

I've never seen GSDoc in action and, personally, I'm hesitant about
GNU-Step stuff in general since maintenance seems to be almost entirely
absent and the documentation is complete trash (excepting Apple's stuff,
which seems to apply about 99.44% to the GNUStep classes).

> If it could be agreed amongst the developers to a documentation system, and 
> that automatic code documentation is sth. wanted, and that documentation 
> comments in the code will be added to the source tree.
> Also I don't think that it is important that the documentation is looking 
> nice, and that the documentation system has lots of nifty features, I think 
> that the important thing first is, that there is some code documentation at 
> all, and it is easily usable.
> any thoughts on that?

Yep.  No fancy features are required but if the automatic documentation
can't do much more than list methods and arguement lists it also isn't
worth much.

This is probably my biggest peeve with anything in Java,  people
generate Javadoc (or whatever it is properly called) and say: "see,
documentation".  To which my reaction is, "Gee, thanks, you listed all
the obvious stuff I can get from just glancing at the code anyway."

Probably the biggest issue I encounter as a part-time developer when
working inside complex applications is object life-cycle.  When does an
object get created, when can it be used [ for example a Gtk widget has
to be realized ], how long does the object last, etc...  The OGo page
cache is a good example.  Is a page object created, processed, and
disposed for each request or does it persist across requests, etc...
That kind of information is really important and requires a much deeper
of analysis of the code to discover.  Same is true with a ZideStore
bundle,  when is the bundle's object(s) created,  what is the purpose of
the bundle's main class, etc...