Re: GNUstep Coding Standard Additions

[Richard Frith-Macdonald]

On 2005-05-07 08:59:45 +0100 Alex Perez <aperez@student.santarosa.edu> wrote:

> Sheldon, Richard, Adam, et. al:
>
> Alex Perez wrote:
> > Sheldon Gill wrote:
> > > I'd be very happy to create a write up for you and help/mentor the 
> > > process. I may be able to assist with a few tools as well.
> >
> >
> > The sooner this is done, and agreed to by most, the sooner I can get 
> > started.
>
> My apologies for replying to my own post, but I'd like to push this 
> forward. 
> Can we all please go over roughly what we want to have me do, what exactly 
> we 
> want documented, and how we want to document it, so I can get cookin'? I'd 
> like to get going on this tomorrow, although I realize that may not happen.

I don't think we have complete agreement yet ... but I think we *are* agreed 
that knowing the MacOS-X release version for each class/method is good.  I'm 
less sure about the GNUstep release version... I don't think this has been 
discussed thoroughly, and I worry that tracking two separate sets of 
versioning might be too much of an overhead.  Certainly it would get 
confusing if you put in both MacOS-X and GNUstep version information for the 
same method ... so probably GNUstep versioning information should be 
restricted to those classes/methods which are GNUstep additions (not in 
MacOS-X/OpenStep).

So, for each class/method, we need to know which version of MacOS-X it was 
introduced at, or whether it is from the original OpenStep spec.  I think, 
for simplicity, we might categorize methods/classes introduced by 
NeXT/OPENSTEP after the OpenStep specification was published as being 
'MacOS-X' methods.

That is to say, we have three categories -
1. Things from the original openstep implementation
2. GNUstep specific additions
3. NeXT/Apple additions

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 we are agreed that we want to categorise a method/class by the 
version where it was introduced, and the version where it was removed 
(NeXT/Apple have removed some things from their APIs)

Now, I guess you could just build up a table of this information, or you 
could edit the headers...

I would say the headers should be rearranged so that methods appear in order 
of the version in which they first appeared, and alphabetically within a 
version.   That way, adding/findng methods for a particular version range is 
trivial.

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.

eg.

#if OSVERSION(0, 0)
// OpenStep methods which were never implemented in OPENSTEP or MacOS-X
#else if OSVERSION(0, 10.3)
// OpenStep methods which were removed in MacOS-X 10.3
#else if OSVERSION(4.2, 10.3)
// Methods not in OpenStep, but present in OPENSTEP 4.2, then removed in 
MacOS-X 10.3
#else if OSVERSION(10.0, 10.4)
// MacOS-X methods introduced in MacOS-X 10.0 and removed in 10.4
#else if OSVERSION(10.0, FUTURE)
// MacOS-X methods introduced in MacOS-X 10.0 and still present
#else if GSVERSION(0, FUTURE)
// GNUstep additions
#endif

The GSVERSION macro might handle versioning of GNUstep specific additions, 
separately from the OSVERSION macro

Defining the STRICT_OPENSTEP macro would select methods where the starting 
version is 0.0.
Defining STRICT_MACOS_X would select methods where the ending version > 10.0
Defining a MACOS_VERSION would select methods where start version <= 
MACOS_VERSION and end version > MACOS_VERSION