Hacker News Reader

Comment by maxmcd | Hacker News Reader

This formatting style for annotated sources always seems to work so well: http://robflaherty.github.io/jquery-annotated-source/docs/01...

View on HN

Indeed, that side-by-side annotated style is great. For those who would like to create similar pages, the original program is Docco[0], a Javascript project. However it's been ported over to many other languages and can be found in these projects:

- Pycco[1] Python

- Rocco[2] Ruby

- Shocco[3] POSIX Shell

- Many more, as found here[4]

Note each of these projects support highlighting different languages. For example, the Pycco[1] project uses the Pygments library for language handling, and thus supports many different languages. Others, like Shocco[3] only support one language (Shell in the case of Shocco).

[0] - http://jashkenas.github.io/docco/

[1] - https://github.com/fitzgen/pycco

[2] - http://rtomayko.github.io/rocco/rocco.html

[3] - http://rtomayko.github.io/shocco/

[4] - http://jashkenas.github.io/docco/#partners-in-crime-

I agree, Docco-style docs are really easy to read.

I built srcco, a Docco-style doc generator that links every variable, function, etc. within your project to its definition (similar to sourcegraph.com -- full disclosure: I work at Sourcegraph), to demonstrate how to build things on top of our free/open source language analysis framework, srclib[0].

You might find it interesting (the links in the code have white backgrounds): http://sourcegraph.github.io/srcco/srcco.go.html

It only works for Go because the only Go toolchain keeps track of comment ranges (because srcco removes the comments from the source code), but it wouldn't be too hard to add comment ranges to the other toolchains. If you are interested in language analysis for languages like Java, Python, Haskell, or Javascript, I would be happy to help you make your first contribution. Ping me: samer@sourcegraph.com.

[0] - https://srclib.org/

Here's also a Docco 'implementation' for Java code: https://bitbucket.org/doklovic_atlassian/atlassian-docco

Absolutely agreed - I just had to click 40 times to read 40 comments when I had half a screen's worth of whitespace they could've just been sitting in...

Strangely, the "default" Genius UI seems to be more or less the two column view - e.g., http://genius.com/1258740/Walt-whitman-song-of-myself/I-cele...

Is this intentionally divergent or is it some kind of bug?

Still just as bad tbh, you still need to click through every annotation.

I built https://notedcode.com a while ago. It sets comments in any repo on GitHub or Bitbucket alongside the original source, and allows you to add and share further annotations, keeping them alongside the right section of code even when the code changes.

I think this wouldn't work for anecdotal comments that John is doing here which runs into paragraphs which would result in lot of whitespace on the right. I think an easier fix would be to highlight the current annotation in a different color while docking the comments to the right while keeping it free for user to move around.

I agree that clicking to go to next is annoying. Perhaps mouse over or scrolling should automatically show the annotation.

Seconded, if you are going to annotate source code please go for this format.

What is the tool that produces this?

The Docco ( http://jashkenas.github.io/docco/ ) family of tools.

Reply on news.ycombinator.com