[OGo-Documentation] code documentation

[Sebastian Reitenbach]

Hi,

documentation@opengroupware.org wrote: 
> > 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.
When I go take a look into the gnustep-base sources, there it is full of 
GSDoc documentation. I think should find a good place in ogo sources, where 
I can add both, so that we can compare.

Is there a class that uses protocols, and categories and other objective-c 
stuff, that would be good for a test document to show all the features?
I'd take OpenGroupware+CTI.m or sth. like that, but there might be sth. 
better I am not aware of.

Then I'd document that using doxygen and gsdoc, and then lets see what both 
can do for us.
I never used gsdoc before. As I last tried to start that, I used doxygen, 
but that is a long time ago, and new features will be in there I think.
> 
> 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).
yeah, but I think I've seen on the gnustep-ml, at least someone is working 
on manual pages.

> 
> > 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."
yeah, just a list is not worth that much, but some added details, what the 
inventor had in mind, when writing this method... just that would help.
Well, its a bit hard to document later, but we will see.

> 
> 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
The whole memory management is sth. that I also did not yet understood, 
besides the most basic things.

Maybe a good chapter for the developer docs ;).

> 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...
yeah, the same things I am facing when trying to add things to the WebUI.
My hope is, that when I start that documenting, that at the end, all the 
small pieces will find together to the large picture.

cheers
Sebastian