discuss-gnustep
[Top][All Lists]
Advanced

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

Re: Documenting API versions


From: Richard Frith-Macdonald
Subject: Re: Documenting API versions
Date: Mon, 09 May 2005 14:08:04 +0100


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.






reply via email to

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