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: Tue, 10 May 2005 10:09:55 +0100

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.






reply via email to

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