Re: Documenting API versions

[David Ayers]

Sheldon Gill wrote:
> This is no longer about Coding Standards so I think it's time for a new
> thread...
> 
> We want to document, for each API call, which Cocoa version or GNUstep
> version introduced it. Also, where applicable, which version deprecated
> it and which version removed it.
> 
> Richard and I have different views on how it is to be done. My idea is
> to mark methods/functions as appearing (or disappearing) in the comments
> as part of the documentation process. Richards is to use conditional
> compilation within the headers.
> 
[snip]
> 
> Conclusion
> ==========
> 
> There is a general agreement that adding version documentation is a good
> and useful idea. There are two proposals on the table as to how this
> should be done.
> 
> Let any interested parties speak up.

I'd prefer a versioning that allows declarations to be hidden at compile
time of my code that aren't part of the API which I specify.  For me the
selectable API would ideally be OPENSTEP 4.2, OPENSTEP 4.5 (actually
this would be WebObjects 4.5) and Cocoa current.  I'm sure others would
like more fine grained control over Cocoa versions.

I don't think we should have duplicate (and therefor potentially
inconsistent) ways of assigning API versions to declarations.  Therefor
my vote goes for the preprocessor approach.  I also like Richards
proposal of how to simplify the macro declarations for easy maintenance
and higher readability.

Cheers,
David