Documentation

[Alexander Malmberg]

Hi,

This topic has been approached before in the lists, but the discussions
have been very inflamed, and nothing has really come of it. (And just as
I'm about to send this, another flamewar starts. Oh well :/.)

Anyway, I'm a bit worried about the lack of detailed overall
documentation. The short comments on each function in apple's
documentation and the openstep spec aren't enough, and it looks like the
gsdoc documentation will be similar.

What I'm looking for is detailed specifications of exactly how different
classes are supposed to work, including how they're supposed to work
with other classes, what all the different options really mean
everywhere, in what order things are supposed to be done, and things
like that (or statements that something is implementation-/un-defined).
Since GNUstep seems to be neither exactly OpenStep nor Cocoa, I guess
you could call this the GNUstep specification.

As an example, I've worked on NSFontPanel this weekend, and found that
the [NSPanel -becomesKeyOnlyIfNeeded] mechanism was completely
unimplemented in GNUstep. The OpenStep spec didn't say anything useful,
and apple's docs barely mentioned [NSView -needsPanelToBecomeKey] (which
wasn't in NSView.h, but I added it). I couldn't find anything saying
when -needsPanelToBecomeKey is supposed to be called, what views are
supposed to return YES, or how this changes the behavior of other parts
of the panel (eg. the return value of -canBecomeKey used to depend on
this setting).

This case was easy enough that I could make educated guesses, and some
persons in #GNUstep helped me by testing on mac osx and OpenStep, but
this does effectively stop me from doing much about more complex things
(the text system), or more subtle things (eg. the view
drawing/updating/flushing issues, or alpha overdraw issues) without
running a great risk of not making everything fit together properly.

A complete implementation might help, but even then, the code might be
incorrect or not work as intended. Even when there's a working
implementation in GNUstep, I can't really tell whether it's correct, or
just a stop-gap implementation. I guess access to an OpenStep or mosx
system or development experience with OpenStep might help, but I have
neither, and most newcomers (ie. people without prior OpenStep
experience) will probably face the some problem.

So I guess what I want is a complete and sufficiently detailed GNUstep
specification (from a developer pov; implementation notes wouldn't
belong there). I realize that it'd take time to completely write such a
thing, and it wouldn't be fully static, but I think it'd be very useful
for many things (developing for GNUstep; making sure GNUstep does what
it's supposed to; making sure the design fits together), maybe even
critical. If persons who know how things are 'supposed' to work (eg. to
match unspecified OpenStep behavior) could help verify things, I could
help write it.

Anyway, I do think that a specification would be a good thing, and that
it'd be a good idea to at least start as soon as possible. GNUstep is
usable to write apps now, and I don't think we want to burn people with
subtle interface and behavior changes after they've started writing
apps. I'd much prefer to make a clean and stable 1.0 release, as opposed
to releasing what we've got now (even if it mostly works) and cleaning
it up for 2.0 (kindof like gtk+, I guess :).

- Alexander Malmberg