Use markdown for the docstrings

This allows for proper code blocks for the examples, courier font for arguments, cross-referencing between functions, links to Java Classes where appropriate, etc. It makes the documentation much more user friendly IMHO.

It appears that this pull request also contains the changes from my previous one, but since it depends on the other changes anyway I guess that's OK.