Re: @deprecated

[Mark Wielaard]

Hi Stuart,

On Thu, 2005-09-01 at 23:54 -0400, Stuart Ballard wrote:
> hence getting an almost instant 0.3% improvement in japi scores which
> incidentally would push us over 90% of 1.4, which is a nice little
> psychological milestone :)
> 
> The downside of such a script would be that, at least if done naively,
> none of the @deprecated tags would get any comments indicating *why*
> the item is deprecated or what should be used instead.
> 
> So I'm interested in feedback on whether it's worthwhile to write a
> script to add these @deprecated tags or not; basically, is an empty
> deprecated tag better or worse than no deprecated tag at all on
> something that is deprecated in the JDK?

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. 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.

I would prefer an approach were someone goes over the list by hand,
reading our implementation to see what we actually do and write real
@deprecated explanations and possibly write the changed/replacement
methods when needed. That is a bit more work, but produces real valuable
documentation for our users.

Cheers,

Mark

signature.asc
Description: This is a digitally signed message part