Re: Documenting API versions

[Richard Frith-Macdonald]

Some thoughts on deprecation and evaluation/testing ...

I think the issue of evaluation/testing proposed new APIs before formally 
adding them is a counterpart to deprecation of existing APIs, and probably 
raises similar issues.  It's reasonably common in free software, though it's 
rarely done formally, an it would be better if it was clearly formalised.

Anyway, it seems to me that documentation of deprecation differs from 
addition/removal of APIs in that, we are unlikley to want to clutter our 
documentation with a detailed audit of it, so we are only concerned with the 
current state of the API rather than the history (we can get the detailed 
audit trail from CVS).

That is to say, we want to know if an API is currently deprecated, but if 
the API has been removed or undeprecated, we are probably no longer 
interested in the fact that it was deprecated in the previous release ... as 
we want to keep documentation clear and simple.
Similarly, in the source code, we want to warn people that the API is 
deprecated NOW, and if in the next release we either remove or undeprecate 
the API, we no longer want to issue a warning.

So, a deprecation (or evaluation) status for an API is naturally a boolean 
rather than a version, and it is not necessarily appropriate to handle it in 
exactly the same way as addition/removal of the api.

Ideally, I'd like a good way to warn about use of deprecated API at compile 
time ... but I don't know of one.  Has anyone got any ideas?

I already introduced a macro to warn once at runtime (only for functions and 
methods), and it would be reasonable to get autogsdoc to recognize the 
presence of deprecation/evaluation variants of this and modify the 
documentation accordingly,
but it all feels a bit fragmentary still ... some way of doing a 
compile-time warning would be nicer.