Updating documentation

[Johan Tibell]

The Python documentation style guide can be found at:

  http://www.python.org/dev/peps/pep-0257/

There Java one is also good

  http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

Like the Javadoc guide, I would encourage people documenting Haskell
libraries to not hyperlink too much. Only hyperlink identifier if you
think the reader might want to click on the link for some reason. For
example, only hyperlink an identifier the first time it's mention in a
piece of documentation. Avoid hyperlinking standard, well-know
identifiers such as Int or String.

Johan