Cleaning up - fixing a lot of build warnings (mostly javadoc)

I'm not good at ignoring warnings... - there are lots of them in the build output, mostly due to invalid javadoc link syntax or missing `@return` descriptions.

This is my attempt at fixing them.