|
| From: | Richard Frith-Macdonald |
| Subject: | Re: GNUstep Coding Standard Additions |
| Date: | Mon, 09 May 2005 06:42:53 +0100 |
On 2005-05-08 22:14:51 +0100 Alex Perez <aperez@student.santarosa.edu> wrote:
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...
I'm afraid I've been going through emails in strict order ... so I think I've already adressed this point ... basically you can orf course do that, but saying that nothing was released between the OpenStep specification and the release of MacOS-X is to ignore a few years of NeXT's development of the OPENSTEP operating system. I think there were releases of 4.0, 4.1, and 4.2 ... but I'm not an OPENSTEP user, and I don't know if nthere were other releases or exacttly which releases introduced/removed which features in the API.
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.
Again, I think I addressed this in an earlier reply because I've been going through emails in order ... to clarify. All classes have documentation generated from the .h files. Most also get documentation from the .m files. For technical reasons, using the .h files is mandatory, using the .m files is optional (some parts of the API, such as macros, appear only in the .h files ... because that's just the way C/Objective-C works).
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.
1. using a #if macro .... #endif sequence you can mark a whole chunk of the API in one go, rather than having to markup each API element separately (though if you want to mark each method separately, you still can). A quick fgrep of the base library headers shows under 100 occurrances of the 'STRICT_' prefix which currently generates the information for OpenStep/MacOS-X/GNUstep discrimination in the documentation. Contrast this with the huge number of classes, methods, functions, macros, types, and constants in the base API, and you can see how efficient it is.
2. the macro lets people compile with a particular api version by defining a single preprocessor constant, rather than as suggested by sheldon, us having to write a new tool to get version information from the documentation and examine their code. Nothing wrong with having such a tool ... but we don't yet, and it would not be an extra stage that users would have to run their code through (and unless it was really, really clever, it would be less good at pointing out where in their code the problems lie).
| [Prev in Thread] | Current Thread | [Next in Thread] |