6 ms·

For layout purposes, have you seen Docco[1] based on Rocco[2]? Coffeescript uses this[3] and the documentation looks very similar. The longform comments are a s

For layout purposes, have you seen Docco[1] based on Rocco[2]? Coffeescript uses this[3] and the documentation looks very similar. The longform comments are a style choice in this case, as these packages just pull comments from the code. Literate style code[4] is another example of comments being a primary actor in programming. If having long comments inline is a problem, most text editors could hypothetically be extended to have automatically collapsed/collapsible comments after the first line. [1]: http://jashkenas.github.io/docco/ http://jashkenas.github.io/docco/ [2]: http://rtomayko.github.io/rocco/rocco.html http://rtomayko.github.io/rocco/rocco.html [3]: http://coffeescript.org/documentation/docs/coffee-script.html http://coffeescript.org/documentation/docs/coffee-script.htm... [4]: https://raw.githubusercontent.com/jashkenas/journo/master/journo.litcoffee https://raw.githubusercontent.com/jashkenas/journo/master/jo...

JohnBooty 12y ago
Whoa, thanks! I hadn't seen any of those. Those all produce some really nice output. Ultimately, I think the two can and should coexist. The benefit (and, I guess, potential drawback) of the OmniRef/RapGenius approach is that it allows the whole world to comment on code (and perhaps ask questions as well) versus generators like Docco/Rocco that (of course) can only display comments in the code that are provided by the code's maintainers. Genius.com has a feature where they have verified contributors - for example, Genius/GZA from Wu-Tang sometimes explains his own lyrics on there. Those comments are displayed much like everybody elses' comments but are given special visual prominence because they're assumed to be authoritative. OmniRef could do something like that too - longform inline comments could be displayed on the sidebar (ala http://coffeescript.org/documentation/docs/coffee-script.html http://coffeescript.org/documentation/docs/coffee-script.htm...) as a part of the stream of comments, and given special precedence.
- timr 12y ago
  We actually do give project members the ability to claim their code and make "verified" annotations -- we're just not doing the greatest job of surfacing that right now. I'll add that to our to-do list. Thanks!

JohnBooty 12y ago

Whoa, thanks! I hadn't seen any of those. Those all produce some really nice output. Ultimately, I think the two can and should coexist. The benefit (and, I guess, potential drawback) of the OmniRef/RapGenius approach is that it allows the whole world to comment on code (and perhaps ask questions as well) versus generators like Docco/Rocco that (of course) can only display comments in the code that are provided by the code's maintainers. Genius.com has a feature where they have verified contributors - for example, Genius/GZA from Wu-Tang sometimes explains his own lyrics on there. Those comments are displayed much like everybody elses' comments but are given special visual prominence because they're assumed to be authoritative. OmniRef could do something like that too - longform inline comments could be displayed on the sidebar (ala http://coffeescript.org/documentation/docs/coffee-script.html http://coffeescript.org/documentation/docs/coffee-script.htm...) as a part of the stream of comments, and given special precedence.

timr 12y ago
We actually do give project members the ability to claim their code and make "verified" annotations -- we're just not doing the greatest job of surfacing that right now. I'll add that to our to-do list. Thanks!