I had recently noticed in a java code methods that are only been deprecated with javadoc's @deprecated tag. Starting from java 1.5 there was @Deprecated annotation added.

To my mind, the main difference here is that @Deprecated annotation in put into compiled classes. End users will know the method is deprecated even is there is no javadoc or sources attached.

Unfortunately, @Deprecated annotation does not support parameters ( link that is done in .NET Framework's [Obsolete] annotation.

I think the best way is to put both @deprecated javadoc tag and @Deprecated annotation to make deprecation visible both in javadoc and in .class files.