I enjoy Literate CoffeeScript and that's where I picked up the concept of Literate coding.

I believe that literate style of code writing has many benefits in any language.

Basically mix markdown with the codebase and export the documentation from the same file.

For a very well executed and interactive example check out

http://dave.kinkead.com.au/modelling-the-boundary-problem/