Eliminate javadoc warnings

[simondelabici]

Get rid of all javadoc warnings .

Note: the goal here is to stop the stream of (over 100) ugly warning messages that get emitted when building the project. Writing good javadoc takes time and is hard. This issue does not seek to address that, but purely to improve things to the point where the build proceeds quietly. This will be accomplished by making small tweaks to the code. Unfortunately without a deep understanding of the underlying implementation it may sometimes be necessary to do things like this:

@param myThingy the thingy of mine.

One can argue that this is meaningless ! In time it is hoped that we can improve the Javadoc so that it provides something meaningful.