|
From: | Alex Perez |
Subject: | Re: GNUstep Coding Standard Additions |
Date: | Sun, 08 May 2005 11:26:12 -0700 |
User-agent: | Mozilla Thunderbird 1.0.2 (Windows/20050317) |
Richard Frith-Macdonald wrote:
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).
I agree with this, with one exception. If a class or method came from OS X, we should note when it was implemented in GNUstep, (which *release* version of base or GUI), don't you think? I think that's going to be important, going forward.
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.
Yes, this is essentially what Sheldon and I also thought would be the right thing to do, so it seems we're all in agreement on this point.
That is to say, we have three categories - 1. Things from the original openstep implementation 2. GNUstep specific additions 3. NeXT/Apple additionsHowever, 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.
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)
Most of what they have "removed" they have actually deprecated, but yes, they have removed *some* stuff, and I plan to note it.
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.
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.
Not a bad idea, but I'm not sure if I'm willing to do this just yet.
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 #endifThe GSVERSION macro might handle versioning of GNUstep specific additions, separately from the OSVERSION macroDefining 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
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.
Cheers, Alex Perez
[Prev in Thread] | Current Thread | [Next in Thread] |