Hacker News Reader

Side note - it's been a while since i've seen a Docco-style annotated-source-style documentation! http://ashkenas.com/docco/

Backbone.js was the first time i saw it, and I loved it! https://backbonejs.org/docs/backbone.html It demonstrated to me that the libraries I use are just normal code that other people write, and i myself can read it to understand a problem.

View on HN

Thanks for the link! I think in that case it was made with https://pycco-docs.github.io/pycco/

I dislike this style. First off, it’s just a block comment. Secondly, although raw markdown isn’t terrible to read, it makes it slightly hard to read the actual code as text, say in emacs. But the worst thing is that folks who code like this tend away from inline comments, which I find usually more useful in complex code.

IIRC Docco uses line comments, I'm not sure what your complaint is about. Besides, Emacs has two-column editing mode, making it possible to have side-by-side comments without any external tools. Also, third-party packages like separedit allow comment editing in an indirect buffer. My point is - with little regard for how it's written originally, Emacs (more than any other tool) grants ways of making it suitable for you, personally. You can make things more readable, or optimize them for writing.

Reply on news.ycombinator.com