5 ms·

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

by maxmcd 12y ago

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

gearhart 12y ago
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...
Mahn 12y ago
Seconded, if you are going to annotate source code please go for this format.
lelandbatey 12y ago
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/ http://jashkenas.github.io/docco/ [1] - https://github.com/fitzgen/pycco https://github.com/fitzgen/pycco [2] - http://rtomayko.github.io/rocco/rocco.html http://rtomayko.github.io/rocco/rocco.html [3] - http://rtomayko.github.io/shocco/ http://rtomayko.github.io/shocco/ [4] - http://jashkenas.github.io/docco/#partners-in-crime- http://jashkenas.github.io/docco/#partners-in-crime-
- nosefrog 12y ago
  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 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/ https://srclib.org/
- moondowner 12y ago
  Here's also a Docco 'implementation' for Java code: https://bitbucket.org/doklovic_atlassian/atlassian-docco https://bitbucket.org/doklovic_atlassian/atlassian-docco
rodw 12y ago
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-celebrate-myself-and-sing-myself-and-what-i-assume-you-shall-assume http://genius.com/1258740/Walt-whitman-song-of-myself/I-cele... Is this intentionally divergent or is it some kind of bug?
- asdfaoeu 12y ago
  Still just as bad tbh, you still need to click through every annotation.
zkhalique 12y ago
What is the tool that produces this?
- cromo 12y ago
  The Docco ( http://jashkenas.github.io/docco/ http://jashkenas.github.io/docco/ ) family of tools.
myth_buster 12y ago
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.
- deleted 12y ago
  [deleted]
psm42 12y ago
I built https://notedcode.com 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.

by maxmcd 12y ago

gearhart 12y ago

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...

Mahn 12y ago

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

lelandbatey 12y ago

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/ http://jashkenas.github.io/docco/ [1] - https://github.com/fitzgen/pycco https://github.com/fitzgen/pycco [2] - http://rtomayko.github.io/rocco/rocco.html http://rtomayko.github.io/rocco/rocco.html [3] - http://rtomayko.github.io/shocco/ http://rtomayko.github.io/shocco/ [4] - http://jashkenas.github.io/docco/#partners-in-crime- http://jashkenas.github.io/docco/#partners-in-crime-

nosefrog 12y ago
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 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/ https://srclib.org/
moondowner 12y ago
Here's also a Docco 'implementation' for Java code: https://bitbucket.org/doklovic_atlassian/atlassian-docco https://bitbucket.org/doklovic_atlassian/atlassian-docco

rodw 12y ago

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-celebrate-myself-and-sing-myself-and-what-i-assume-you-shall-assume http://genius.com/1258740/Walt-whitman-song-of-myself/I-cele... Is this intentionally divergent or is it some kind of bug?

asdfaoeu 12y ago
Still just as bad tbh, you still need to click through every annotation.

zkhalique 12y ago

What is the tool that produces this?

cromo 12y ago
The Docco ( http://jashkenas.github.io/docco/ http://jashkenas.github.io/docco/ ) family of tools.

myth_buster 12y ago

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.

deleted 12y ago
[deleted]

psm42 12y ago

I built https://notedcode.com 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.