Re: code documentation

Hi,

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

-- 
OpenGroupware.org Documentation
documentationopengroupware.org
http://mail.opengroupware.org/mailman/listinfo/docum
entation