Re: API documentation

[Richard Frith-Macdonald]

On Friday, April 4, 2003, at 12:44  pm, dleeuw@made-it.com wrote:

> Hi all,
>
> I have read all the discussion on the GNUstep API documentation. I 
> would
> like to volunteer, but since I don't have any programming experience in
> Objective-C and C, I don't think the documentation would improve...
>
> However, we could take the existing OpenStep documentation and add
> comments to that document in e.g. blue or italics that state where
> GNUstep is different from the implementation.

I think there should be *VERY few* places where GNUstep differs from 
the OpenStep
documentation.  Mostly GNUstep adds OPENSTEP and MacOS extensions rather
than changing anything.

>  This way we can imho, and
> correct me if I am wrong, use the existing documentation without being
> in legal trouble. We supply comments on a piece of standard
> documentation.

I don't think that actually provides any legal protection.

IMO the best way a non-programmer could help would be to take the 
class/method
descriptions from the OpenStep specification and rewrite them to say 
the same thing
in different words.  The rewritten descriptions could then be added as 
comments in
the GNUstep source code, and autogsdoc would ensure that they are put 
in the
correct places in the documentation.


What we need programmers to help with is -
1. tutorial style documentation on how to use the classes together in 
combinations.
2. extending the method/class documentation to cover details left 
undefined in the OpenStep spec.
3. examples of usage.