Commented with the Javadoc syntax

Not precisely commented, there only are the descriptions of the
parameters, return values and throwables. No accurate comment in the
difficult sections.