Re: Documenting API versions

[Richard Frith-Macdonald]

On 2005-05-09 03:52:10 +0100 Sheldon Gill <sheldon@westnet.net.au> wrote:

> 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.

I'd use two ... one to specify the NeXT/Apple version one to specify the 
GNUstep version .... and phase out use of the old on es (or retain for 
backward compatibility, but map them to the new ones).

> 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.

I'd do none of that ... as I suggested you would use one (or both) of two 
macros, and use numeric parameters.  For the sake of exposition in my 
earlier email I left out the detail, but the common way of expressing 
versions for use in macro conditionals is to expect to have major, minor, 
and subminor version numbers, and use two digits for each, so version 10.0.3 
would be written as 100003.  We *could* use symbols, but then autogsdoc 
would need to have each symbol coded into it ... and the numeric version is 
pretty clear anyway.  We could also take a view that, either API will never 
be changed on a subminor version number, or we will never document  to that 
detail ... and only use major and minor numbers, reducing the number of 
digits neede to four (I think that's my preference).
It would probably be nice to use a symbol for the case where something has 
not been removed from the API though (something like FUTURE or NEVER, rather 
than 9999 which is the obvious numeric value to use).

So, the markup would be -

#if OS_API_VERSION(1002,NEVER)
- (BOOL) hasMemberInPlane: (uint8_t)aPlane;
// other methods introduced at version 10.2 could be placed here
#endif
#if OS_API_VERSION(1003,NEVER)
+ (NSCharacterSet*) symbolCharacterSet;
// other methods introduced at version 10.3 could be placed here
#endif


> gsdoc needs to be revised to parse the conditionals in the header and 
> change 
> output accordingly.

It already handles this for the existing STRICT_... macros, so it's easy to 
extend it.

> There'll be no change in the 
> documentation output until it is done.

I might do it after breakfast ... it only looks like about fifteen minutes 
work.

> There also needs to be some easy method to test the logic for all cases.

I'm guessing you are assuming the sort of scheme (with multiple preprocessor 
constants defined, one for each release), you outlined above ... but that's 
not what I was thinking of, and the actual logic required is very simple ...

if (no release is selected) or (added <= selected and removed > selected) 
then API is available

I don't expect any difficulty testing that logic.