Consolidate Javadoc

[occupant23]

At the moment our Javadoc is not very uniform.

Review the whole Javadoc of the project, especially regarding the following subjects:

• Consolidate upper/lower case in the beginning of lines to the standard (review some Javadoc documents of bigger well maintained projects to decide)
• Add an section heading "Example:" to all examples
• Add a new Javadoc to functions, that are part of our API but have none
• Update/Clarify the wording of the Javadoc in order the be better understandable
• Recheck our Wiki and update phrases used in both documentations accordingly

Please create a own branch for this issue since this task will be ongoing and merged with every release in between.

[h-arlt]

IMO we should stick with JavaDoc convention used by JDK itself.
That means: all text passed to doclets (that stuff beginning with '@') should start lower-case.