Re: Documenting API versions

[Sheldon Gill]

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

I was thinking a separate page/pages could list releases and dates. In 
the GNUstep case I was thinking it could also provide a link to the 
tarball where available, along with MD5 sums.

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

Not OS but Library/Package

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

Yes, thats my view too with the addition that it should extend beyond 
just -base and -gui.

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

Oh, I thought we had discussed deprecation. It certainly is clearly laid 
out in my proposal.

> 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).
> >  [Gerald]
> > Can some of the date information be recovered from CVS ?

For GNUstep yes it is possible. I don't think there is much value in 
trying to obtain version info too many releases ago.

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

Well, I disagree that all but one of the same advantages apply:

I still hold that my approach is cognitively and practically simpler. 
Hence easier to review and audit.

Your proposal has yet to clearly specify handling depreciation.

Parsing and calculating has some (perhaps small) impact on builds when 
compared to comments which are entirely skipped. {Minor point, yes}

Anyway, let the discussion continue.


Regards,
Sheldon