It's easy to deprecate classes in Java.. a little too easy. All you have to do is add a Javadoc-style comment with the @deprecated tag. That leads to problems... Something I see over and over again.. example:

/**
 * @deprecated
 */
 public String getSomeValue(int id);

The problem here? This method is now deprecated, but no reason stated as to why, no date or version provided as of when and no alternative call. In other words zero useful information but it will generate compiler warnings when called.

I see that as a big problem... I think Java should require *more* information before allowing for this to compile and generate compile errors otherwise.

When I deprecate a method I like to provide either a "as of" version or date and an alternative to use. Really, the most important part is the alternative method. Otherwise any programmer who is going to attempt using this code will either have to leave compile warnings (something I really don't like as it can lead to bugs) or do (possibly extensive) detective work to figure out what he/she should be using instead.

This is all really easily fixed by proper commenting -- but we all know how many programmers really utilize proper commenting.

I think Java should at the very least require the use of the @see tag with the @deprecated tag.

/** 
 * @deprecated as of version 1.1
 * @see getSomeOtherValue
 */
 public String getSomeValue(int id);

Javadoc documentation recommends this usage but it is not enforced by the compiler.

More info about Javadocs here.