TRUNK-4711: Fix javadoc compilation errors
Fix all the errors that cause the javadoc generation to fail. Leave the
problems that only cause a warning to be reported. Remove the previously
added javadoc error suppression now that all errors are fixed.
Note that javadocs in test classes were not fixed as javadoc generation
does not cover test resources.
Summary of the types of problems fixed:
* @link usage in @see tags
* @return descriptions missing - The new @return descriptions not just
fix the validation issues byt try to be meaningful (to the extent that
the method contract could be easily figured out from the implementation
or method description).
* invalid @link or @see references - Some of the references were not
meaningful any more and were just removed. Others were fixed to point at
a most likely intended target.
