Supporters of heavy documentation seem to emphasize its value in communicating functionality to other programmers, whereas opponents seem to emphasize the hassle of writing it and keeping it up-to-date.

I think a key to documentation that is both easy to understand and easy to maintain is to have good usage examples of the code. They are a very straightforward and concise way of conveying both 1) what something does and 2) how to use it. I like to say, "the right usage example can be worth 1000 words of documentation."

Check out https://sourcegraph.com (disclaimer: I am one of the creators). It parses/analyzes the code to identify function calls, type references, etc., and uses that to show you how a piece of code is used. Currently supports Python, node.js, Go, and Ruby. Would love to hear anyone's feedback!