Documenting the GUI library

[Adrian Robert]

Hi,

(Sorry, this is a long message; executive summary for the impatient: if  
you have time please go to http://penguin.med.cornell.edu/assign/ and  
sign up for something..)


Since there seems to be some interest in and energy for GNUstep  
documentation, maybe now is the time to bring up a project I've been  
contemplating for a while: completing the GSdoc for GNUstep-GUI.   
Currently, we have fairly complete GSdoc for base:

http://gnustep.org/resources/documentation/Developer/Base/Reference/ 
index.html

This is in many ways better than using Apple's docs:

- it documents GNUstep-specific behavior and features
- it is installed with GNUstep and can be accessed without web access
- the Javadoc-like frames format is more convenient to navigate than  
Apple's HTML
- when I or someone else gets around to it, we can add a documentation  
panel
  to ProjectCenter similar to Apple's Xcode doc search app

Unfortunately, the equivalent documentation for GUI is not very  
complete:

http://gnustep.org/resources/documentation/Developer/Gui/Reference/ 
index.html

It would be really nice to fill this stuff in, noting the GNUstep  
specifics and perhaps also noting where something is unimplemented so  
everyone knows without looking at the source or finding out by trial  
and error.  In fact, this job is not as bad as it sounds, because a lot  
of the "missing" documentation IS actually written, but doesn't show up  
in the HTML because it's either in the wrong place for GSdoc to find  
it, or doesn't have the right comment marker, or other reasons.  Still  
the job is far too much for one person.

I'd like to propose a distributed effort, where each person who has the  
time and the knowledge just takes responsibility for finishing up one  
or two, maybe three classes, which should not take very much time to  
do, maybe an hour at most.  The payoff will be far greater than this  
amount of time, and for far more people.  To help coordinate the work  
and make sure no-one duplicates the efforts of someone else working on  
the same thing, I made a simple webapp at:

http://penguin.med.cornell.edu/assign/

(Sorry, it runs in Java, not GSWeb.. ;-)

Here, one can (anonymously) claim ownership of one or more classes, so  
that others know not to work on it.  When finished, they can mark the  
class as "complete".  If someone else later looks at this and thinks  
there is more to be done, they can move it back to "taken" and work on  
it themself.  If someone who claims a class ends up not being able to  
finish it, they can reset the ownership to "available" so that someone  
else might take it.  (Yes, the app is guarded against concurrent  
access.)

Note, a copyright assignment is required even for documentation work.   
If someone wants to contribute to this and hasn't sent one in, they  
should contact Adam (fedor@doc.com).  If you have sent a copyright but  
lack CVS commit access, you can send your changes to me or anyone else  
with access to commit for you.  The more people working on this the  
better.

Another note.  While it is OK to refer to Apple's docs when writing  
ours, you cannot copy anything, and it is best to even avoid direct  
paraphrasing when possible.  Other references include the OpenStep spec  
(http://gnustep.org/resources/OpenStepSpec/OpenStepSpec.html), and  
looking at the source code (best).

As far as writing gsdoc itself, there is a brief intro at:

http://gnustep.org/resources/documentation/Developer/Base/ 
ProgrammingManual/manual_9.html#SEC145

A couple of additional points:

- documentation for the class as a whole (at the top in the gsdoc)  
might seem useless to someone experienced with the OpenStep API, but is  
invaluable to newcomers

- gsdoc can be tested by going to the "Documentation" subdir of gui and  
running "make"; the resulting HTML files are built in a subdirectory