Deprecation, javadoc

Can Atlassian please try to be stricter about they way you use deprecated annotations in the Java APIs? If something is deprecated and there is a recommended replacement, even if it is not a direct replacement, then please use the javadoc to add that information.

In addition, there is very little class level or method level javadoc that tells us what the basic purpose of the classes are and what the contract of the methods are.

If an API user needs to read the source code of the API implementation to figure out how to use the API then, IMO, it is an unfinished API. Troubleshooters using debuggers don’t have time to read all of the source code in a class hierarchy and sometimes it isn’t even possible to walk the debugger deep enough to see the where the thing is implemented… not without inside knowledge. The interface at the top needs to specify the contract to the caller… by using javadoc.

I realize everyone is moving a light speed in enterprise software but I strongly believe that making frameworks easier for developers to use is a huge multiplier when it comes to adoption. This would benefit everyone. Please make it easier for us by putting some fit and finish polish on your APIs.