This is no longer about Coding Standards so I think it's time for a
new
thread...
We want to document, for each API call, which Cocoa version or
GNUstep
version introduced it. Also, where applicable, which version
deprecated it
and which version removed it.
Richard and I have different views on how it is to be done. My idea
is to
mark methods/functions as appearing (or disappearing) in the comments
as part
of the documentation process. Richards is to use conditional
compilation
within the headers.
Sheldon Way
===========
The way I propose is extending the existing documentation. You'll
grok it
quickly. I'm working on the next Base release and I've added a new
method to
NSProcessInfo which is Cocoa compatible:
/**
* Bit which tells you what this does
*
* Introduced: MacOS 10.2, Base 1.11
*/
- (NSString *) operatingSystemVersionString
I also did some research into NSCharacterSet and so, for example:
/**
* Returns YES if the receiver contains at least one character in the
* specified unicode plane.<p>
*
* Introduced: MacOS 10.2
*/
- (BOOL) hasMemberInPlane: (uint8_t)aPlane;
/**
* Returns a character set containing mathematical symbols, etc..
*
* Introduced: MacOS 10.3
*/
+ (NSCharacterSet*) symbolCharacterSet;
since I don't know which version of Base introduced them.
In the same way we have
* Deprecated:
* Removed:
Thus, we can document throughout the lifecycle for both MacOS and
GNUstep.
We baseline at the OpenStep specification. So that is the implied
Introduced
for all.
I see MacOS versions as "MacOS 10.0", "MacOS 10.1", "MacOS 10.2",
"MacOS
10.3", "MacOS 10.4".
{As long as we have a defined set they could be anything. For example
we
could go "X_0", "X_1"... or "Puma", "Jaguar" etc. I've proposed the
above
because they seem clear, concise and apparent}
For GNUstep the version tracking is a little more complicated because
we have
different version numbers for each library. This we need
"Base #" and "GUI #" etc.
A GNUstep only method can be "Introduced: Base" or "Introduced: Gui"
until a
particular release is identified.
So a method in the OpenStep spec which was dropped for the MacOS
release and
not implemented until -base 0.8 would be
* Introduced: Base 0.8
* Removed: MacOS 10.0
This approach also means the documentation can start being revised
today by
anyone who cares to. Simply and consistently. Since where and how the
markup
is to be placed is very clear CVS commits and diff patches will work
nicely
and be easy to review.
This makes it easy for lots of people to contribute right now, should
they
want to in a distributed way.
The idea is gsdoc is later revised and the "Introduced: x" turned
into
<introduced/>x</introduced> tags so any data processing becomes
easier. {I'm
sure a perl/python wizard will convert the lot in under an hour}
The reason I'm suggesting "Introduced: " rather than going straight
to XML
tags is this: such tags will not be visible in the HTML output of
gsdoc at
the moment. By not tagging now we can immediately improve the
documentation
and move forward. We don't have to wait for a gsdoc revision to see
results.
{BTW, if the consensus is tag now I can live with that}
Advantages as I see them, in summary:
* we began yesterday
* it's easy for anyone to contribute as the technical skill level
required is
low
* handles introduction, deprecation and removal for both MacOS and
GNUstep
* handles complicated cases easily
* it is easy for others to audit and verify
* task can be widely distributed immediately
* will have 0 impact on builds
* approach and any tools developed to support it are equally
applicable to
any other library/project
Richard Way
===========
The headers currently have a few #ifdef to control which prototypes
are
visable to a build. Hence you can check if your program calls APIs
which
aren't available.
STRICT_OPENSTEP, STRICT_MACOS_X, NO_GNUSTEP
are the three defined.
The methods/functions can be grouped into sets according to which
version
introduced them.
To make this work we'd need to define additional symbols. So my
examples
above would be something like
#ifndef STRICT_OPENSTEP
#ifndef NO_GNUSTEP
#ifdef GNUSTEP_BASE_1_11
- (NSString *) operatingSystemVersionString
#endif
#endif
#endif
but I'm really not sure how best to handle the definitions for a
situation
where you've got various versions so one way would be like:
#ifndef STRICT_OPENSTEP
#ifdef STRICT_MACOS_X_3
#define STRICT_MACOS_X_2
#define STRICT_MACOS_X_1
#define STRICT_MACOS_X
#endif
#ifdef STRICT_MACOS_X
#ifdef STRICT_MACOS_X_2
- (BOOL) hasMemberInPlane: (uint8_t)aPlane;
#endif
#ifdef STRICT_MACOS_X_3
+ (NSCharacterSet*) symbolCharacterSet;
#endif
#endif
#endif
except this wouldn't handle deprecation and removal.
gsdoc needs to be revised to parse the conditionals in the header and
change
output accordingly. It'd need to understand the new symbols we've
used and I
guess the symbol set will need to be extendable. There'll be no
change in the
documentation output until it is done.
There also needs to be some easy method to test the logic for all
cases.
Richard has (since I drafted this) posted a further clarification:
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
I shall leave it to him to continue...
Conclusion
==========
There is a general agreement that adding version documentation is a
good and
useful idea. There are two proposals on the table as to how this
should be
done.
Let any interested parties speak up.
Regards,
Sheldon
_______________________________________________
Discuss-gnustep mailing list
Discuss-gnustep@gnu.org
http://lists.gnu.org/mailman/listinfo/discuss-gnustep