Re: GNUstep Coding Standard Additions

[Alex Perez]

Richard Frith-Macdonald wrote:
> On 2005-05-08 19:26:12 +0100 Alex Perez <aperez@student.santarosa.edu> 
> wrote:
>
> > > However, for simplification, we can treat the opriginal OpenStep spec 
> > > as MacOS-X version 0.0 and the NeXT releases of the OPENSTEP system 
> > > as being versions 4.0, 4.1, 4.2 (can't remember if OPENSTEP ever got 
> > > beyond 4.2).
> >
> >
> > I think whether or not a class was introduced in OPENSTEP 4.0, 4.1, or 
> > 4.2, at this point, is completely irrelevant, and I personally am not 
> > going to research this. Besides, we work off the OpenStep 
> > specification, not anything else, when it comes to the original API 
> > documentation. For the newer apple-added stuff, we just need to note 
> > which version of OS X the API was introduced, as well as which version 
> > of of GNUstep it was implemented in.
>
>
> So what do you advocate for the parts of the API which were introduced 
> after OpenStep, but before MacOS-X, and the parts of the API which were 
> in OpenStep but were removed before MacOS-X was released?

It should be obvious, but I can spell it out if it's really necessary. 
If something that did not exist in the OpenStep spec first appeared in 
OS X 10.0, which was the first *RELEASED* product to contain the API 
addition or modification, it will be marked as being introduced in OS X 
10.0, which is absolutely correct, since it was the first released OS to 
 contain the changes. If something was removed "before" OS X 10.0 was 
released, for instance, it is not a part of OS X  10.0, and would either 
be marked as deprecated or removed as of OS X 10.0 in our documentation. 
This seems plainly obvious...

> > > Now, I guess you could just build up a table of this information, or 
> > > you could edit the headers...
> >
> >
> > I plan to document it in the same place where the method documentation 
> > is, for the sake of consistency, which is not in the headers.
>
>
> Except where it IS in the headers...

You're kidding, right? Some GNUstep classes have the documentation in 
the headers, and some have it in the source? that's so utterly wrong and 
needs to be fixed, if so.

> > > We could define a standard macro to handle versioning, taking two 
> > > arguments indicating the version at which the method was introduced, 
> > > and the version at which it was removed.
>
>
> > I am not at all convinced that implementing these over-the-top and 
> > IMHO unnecessary/not-very-useful macros are worth my time. If you 
> > really think they are of value to you, I would of course encourage you 
> > or anyone else who needs this level of functionality to implement 
> > this, but I myself am not willing to invest the needed time into this 
> > specific aspect of things.
>
>
> I am quite happy to implement this simple macro ... I was suggesting 
> that you use it to produce the documentation markup, as it would be (as 
> far as I can see) the simplest/quickest way of producing the markup.

I don't really see how, at all.

Alex