discuss-gnustep
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Documenting API versions


From: Sheldon Gill
Subject: Documenting API versions
Date: Mon, 09 May 2005 10:52:10 +0800
User-agent: Mozilla Thunderbird 1.0 (Windows/20041206)

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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]