3 ms·
Supporters of heavy documentation seem to emphasize its value in communicating functionality to other programmers, whereas opponents seem to emphasize the hassl
by beliu 12y ago
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 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!
- Meai 12y agoSee the image here: http://i.imgur.com/SAwSGaL.png http://i.imgur.com/SAwSGaL.png. What do I get from seeing these properties? It doesnt seem like autogenerated documentation from source code is easy or possible at all. The modules being listed in the modules tab dont seem to be correct, (assert(value: bool, message: string)?
- beliu 12y agoThanks for the feedback! assert is commonly used as a function, but in this case, it turns out to be a module as well. You can see this by clicking on that module link; you'll go to a page that shows assert.js and see that module.exports is assigned to the ok function (which you can click on to jump to its definition). Other attributes are also defined on module.exports, however, so you can see that you can not only do "assert(condition, message)" but also "assert.equal(condition, message)", "assert.notEqual(condition, message)", "assert.deepEqual(condition, message)", etc. You're right, auto-generating docs is not easy! Javascript turns out to be one of the toughest languages to do this for, and we have a long way to go. The properties tab doesn't seem very useful on that page. We're pushing a new change to the UI that will hopefully make this page clearer and more useful in the near future. Please send any more feedback our way!