Hey Team,
When deprecating a symbol, like class or method, please included a reference to
the replacement in the java docs. Also please include an example of converting
from the old API to the new. I am finding many many places in the source where
deprecated code has no hints at all. As many of us don’t take the effort to
immediately convert old tests over to the new APIs the context is lost when
someone finally does get around to it. For public APIs this is extremely
important so that users know how to migrate their code with as few roadblocks
as possible.
Here is an example of something that is much better than most of what I am
seeing.
/**
* @deprecated Replaced with something better and safer.
* Replaced by {@link Bar}.
*/
@Deprecated
class Foo {
/**
* Do something.
*
* @deprecated Replaced with something better.
* Replaced by {@link Bar#doSomethingBetter()}
*/
@Deprecated
public void doSomething() {}
/**
* Do something.
*
* @deprecated Implementation is not safe.
* Replaced with {@link Bar#doSomethingBetter()} and {@link
Bar#doSomethingElse()}.
* Migration example, replace:
* <pre>{@code
* Foo foo = new Foo();
* foo.doSomethingAndSomethingElse();
* }</pre>
* with:
* <pre>{@code
* Bar bar = Bar();
* bar.doSomethingBetter();
* bar.doSomethingElse();
* }</pre>
*/
@Deprecated
public void doSomethingAndSomethingElse() {}
}
class Bar {
public void doSomethingBetter() {}
public void doSomethingElse() {}
}
-Jake
