Re: Documenting the GUI library

[Quentin Mathé]

Le 5 mai 05, à 17:46, Adrian Robert a écrit :

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

Hi Adrian,

I think your mail is welcome. In my opinion, the main problem is we are  
missing a web reference allowing developers to know class by class and  
method by method what is implemented or not in GNUstep vs Cocoa. In a  
better world, we would have every methods in such reference marked with  
Cocoa and GNUstep versions which introduced them.
I planned to write some perl script for this but I haven't managed to  
do it. I have started yesterday to look at Matt Rice methodslist tool  
which is somewhat related.

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

In my experience (with NSComboBoxCell), it can take several hours to  
document a complete class correctly.
Anyway I agree that it can be a good idea to document two or three  
classes in this way. In -gui, however various things are not matching  
documented behavior (OpenStep or Cocoa) or somewhat broken, then if you  
want to annotate documented methods with theses issues (because  
developers can encounter them), documentation work will become more  
boring and time consuming but more useful too.

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

That's great… I even claimed ownership for some classes :-)
It would be better may be to have non anonymous ownership in order we  
can talk more easily with "owner" when we want to do a minor  
documentation fix.

Thanks,
Quentin.

--
Quentin Mathé
qmathe@club-internet.fr