[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documenting the GUI library
From: |
Quentin Mathé |
Subject: |
Re: Documenting the GUI library |
Date: |
Fri, 6 May 2005 01:29:33 +0200 |
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