Re: Documenting API versions

[Richard Frith-Macdonald]

On 2005-05-09 22:49:32 +0100 Gerold Rupprecht <geroldr@bluewin.ch> wrote:

> > 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)
>
> I think the NEVER indicator better than 9999 - easier to understand.

Yes ... though the exact value is arbitrary, and someone may think of a 
better one to use.

> > > 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 dates are important to document too. This is important to be able 
> to 
> defend the project from any possible litigation. It may also help any other 
> open source project by making it easier to identify "prior art" (help stop 
> software patents!).

Yes ... what I meant was that I don't think we need to introduce anything 
special to deal with them.
1. we probably don't want to list dates as well as version information for 
each method etc in the standard documentation, as this would be overly 
verbose for reading, and  the version information implicitly provides the 
date.
2. the actual dates that things are changed (rather than formal release 
dates) is recorded in the CVS repository anyway.

If we have version information built in to the system, it would be fairly 
simple to extend the documentation tool to have a page containing date (and 
other) information about each release, and have the version information for 
each method, class etc linked into the appropriate point on that common 
page, so that a click on the version name/numbr in the html would take you 
to the description of that version (including release dates).