Use markdown for the docstrings

[egli]

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.

[Raynes]

Wild. Didn't think there were people left on the planet who make tedious documentation improvements for random open source projects.

[egli]

It's the classic "scratch your own itch" theme. After having switched between the API docs and source code enough times I thought "Hey doesn't codox support links to the source?" Once I got started I got a bit carried away with the markdown but I hope people down the line will benefit.

Thanks