Re: Documenting API versions

[Richard Frith-Macdonald]

Hi ... nice to hear from you again ... I hope you got home from FOSDEM 
without too much trouble.

On 2005-05-09 12:48:52 +0100 Gerold Rupprecht <geroldr@bluewin.ch> wrote:

> First, thanks for your working on this.
>
> I think what you are trying to do is say something along the lines
>
> ValidFromOS xxx                         To:NULL
> ValidFromOSVersion xxx          To:NULL
> ValidityStatus
> ValidFromDate xxx                       To:NULL


I think we are talking about operating system version/release, and are not 
considering specific dates (though I guess we could lookup dates of various 
releases).

> As seem to have the following axes:
> OS,
> OSversion,
> Current / depreciated / removed
> Date.

I think in terms of operating systems, we consider there to be two sets of 
versioning.
First is the OpenStep -> OPENSTEP -> MacOS-X line ... ie 'official' 
NeXT/Apple releases.
Second is the GNUstep line.
We want to consider two GNUstep lines, one for the base library and one for 
the gui library, as we use different versioning for the two.  However, since 
the base and gui headers/documentation are separate, I think we can probably 
manage that quite simply.
We haven't really discussed deprecation ... but extending the scheme to 
include a version of the system at which part of the api was deprecated is 
pretty simple.

> If the constraints are NULL, this would imply that the code is valid for:
> All supported OSes
> All versions
> (Current is implied)

Yes.  Though in the proof of concept code I added, I use a specific marker 
'9999' as meaning the current release ... in a final version I would prefer 
to use a more readable marker or (better) use extra macros with only one 
argument each.
So in the quick hack, the markup for a group of methods introduced in macos 
10.3 and in GNUstep 1.02 would be -

#if OS_API_VERSION(1003, 9999) && GS_API_VERSION(0102, 9999)
// a load of method declaractions here
#endif

but a more plished version might use
#if OS_API_VERSION(1003, NEVER) && GS_API_VERSION(0102, NEVER)
or
#if OS_API_VERSION(1003) && GS_API_VERSION(0102)

> If a date is given, it indicates the date the validity began / ended 
> (removal 
> date or depreciated date).
>
> Can some of the date information be recovered from CVS ?

I don't think we are looking at dates ... just versions.

I think Sheldon's summary of his approach is pretty good (seems clear to 
me), but his summary of mine (as I hope is apparent from my emails) is only 
vaguely similar to what I was suggesting ... In particular, all but the last 
of the advantages he lists for his approach also apply to mine because, as I 
keep trying to make clear, I'm advocating a superset of the functionality 
(adding compile-time checking that a program doesn't use api it shouldn't) 
and a modest simplification of the markup task (markup a whole chunk of the 
api in one go)  ... It could be easily modified to be applicable to other 
projects too I guess.

The reason for this is easy to understand ... my approach was to take 
Sheldon's suggestion of having more detailed versioning, combine it with the 
best points of the existing versioning, and refine that with suggestions 
from David, Adrian et al, with the aim of maximising both functionality and 
simplicity.