Add some more javadocs documentation to user-facing classes.

Some of the comments are copied (and adopted) from the old API.
I'm not so sure if this pull request is really helpful, but I already made the work, so I should at least try it ;)