Documenting API versions

[Sheldon Gill]

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