search

leonidas / transparency

Transparency is a semantic template engine for the browser. It maps JSON objects to DOM elements by id, class and data-bind attributes.
http://leonidas.github.com/transparency/
MIT License
969 stars 112 forks source link

Document Transparency using CoffeeDoc #47

Open miohtama opened 12 years ago

miohtama commented 12 years ago

Document transparency.coffeescript using CoffeeDoc or similar API documentation tool

https://github.com/omarkhan/coffeedoc

This will greatly help to understand the source code.

pyykkis commented 12 years ago

Thanks for the proposal.

To be honest, I'm not a big fan of source code comments, because of http://www.codinghorror.com/blog/2008/07/coding-without-comments.html, http://www.codinghorror.com/blog/2006/12/code-tells-you-how-comments-tell-you-why.html and the related links.

I feel readme and wiki are better places for API documentation, which is a reason not to use CoffeeDoc. Otherwise, source code comments should only be 'why' comments. If 'why' (comments) or 'what' (code) are unclear, I'd love to get more detailed pointers or even better, contributions. =)

Cheers, Jarno

miohtama commented 12 years ago

The articles you linked show what may happen if inexperienced people write comments. Please think the matter from the perspective that this is not the case with Transparency.js project and this would reduce the future workload to keep code and (Wiki) docs sync :)

E.g. For good examples what documentation can achieve see here:

http://docs.sencha.com/ext-js/4-0/#!/api/Ext.Ajax