Re: @deprecated

[Stuart Ballard]

On 9/2/05, Mark Wielaard <address@hidden> wrote:
> I am all for breaking psychological milestones (although wasn't there a
> saying that the last 10% of the work will be the other 90% of effort
> needed?) But I am not a big fan of producing generated comments by
> scripts that are supposed to explain what our code actually does. And
> often these kind of automagically generated doc strings never get
> properly updated. The problem is that you want to really describe why
> something is deprecated, what the replacement and/or reason for it is
> and/or how the behavior might have changed from earlier versions. 

Ok. No promises, but if I do write a script then it'll be an
interactive one which uses human intervention to get a correct and
complete deprecation comment. Would you agree that it's fine to refer
to Sun's documentation to write these, as long as the actual text
chosen is written from scratch to convey the same information?

> There
> is also the problem that in a couple of places we do actually implement
> the deprecated behavior or don't yet have the replacement behavior. In
> such cases marking our implementation deprecated is not helping our
> users.

Hmm, I'm not sure I agree with this. Seems to me that even if we
haven't yet implemented a replacement, it's useful for users to know
if they're using a deprecated API, because then they'll be aware that
eventually they're likely to want to switch, once the replacement does
get implemented. A good deprecation comment might also make the users
aware of fundamental problems with the API itself, such as in the case
of Thread.stop(), which might lead them to take an entirely different
approach even if a direct replacement isn't (yet or ever) available.

Stuart.

-- 
http://sab39.dev.netreach.com/