6 ms·

JQuery Annotated Source

pokoleo 13y ago
This is an old version of jQuery run through docco, with a simple page on top of the docco output. docco: http://jashkenas.github.io/docco/ http://jashkenas.github.io/docco/ I just checked out jquery and built it myself. Here's a newer version: http://shalecraig.com/docs/manipulation.html http://shalecraig.com/docs/manipulation.html
jliechti1 13y ago
Hey, this is pretty cool. Does this style of annotation exist for any other libraries/projects? I think the left side could be expanded into a pretty good pedagogical tool using mini-examples and explanations to focus on key concepts in the code.
- muriithi 13y ago
  Backbone.js http://documentcloud.github.io/backbone/docs/backbone.html http://documentcloud.github.io/backbone/docs/backbone.html Underscore.js http://underscorejs.org/docs/underscore.html http://underscorejs.org/docs/underscore.html
- emillon 13y ago
  It's similar to literate programming, which consists in exchanging the focus between code and comments. I believe that Coffeescript just got a literate processor, so the community may benefit from this in the near future. Because GHC supports it, it is also very popular in the Haskell community.
- romaniv 13y ago
  Many (around 5) years ago I wrote a library that parsed PHP files and generated logical "anchors" after classes and functions. I combined that with a simple CRUD application that allowed anyone to view source code in the browser and add/change comments dynamically. No one cared.
  - kristopolous 13y ago
    have the source posted anywhere?
    - romaniv 13y ago
      The main website it was on no longer exists, but there are bits and pieces here and there. http://code.ohloh.net/project?pid=LOfjD4AHjNo&prevcid=1&browser=Default&did=libs%2FDoc&cid=ks-xq0gsZHA http://code.ohloh.net/project?pid=LOfjD4AHjNo&prevcid=1&... doc_code2html() takes PHP code as argument, and uses built-in PHP tokenizer to add CSS classes to code. After that, you can use vanilla CSS to color things up. Up to this day this is the simplest and most accurate PHP highlighter I've seen. doc_getCodeAnchors() takes php code as argument and returns an associative array of anchors. I.e.: array( 'MyClass.methodName' => array('line' => 3, 'type' => 'class', 'name' => "methodName"), ) Comments class was a controller that actually displayed files with highlighting and comments, allowing you to add and edit comments. And yes, I am fully aware of deficiencies of that code, but I still think the core ideas there are pretty cool.
- pavel_lishin 13y ago
  One of backbone.js's example apps does this, and it was my favorite thing about their docs: http://backbonejs.org/docs/todos.html http://backbonejs.org/docs/todos.html
- malingo 13y ago
  raganwald put together annotated source for his coffeescript implementation of hashlife, also using Docco: http://recursiveuniver.se/docs/cafeaulife.html http://recursiveuniver.se/docs/cafeaulife.html
- rossriley 13y ago
  I did one for PHP a while back. Not perfect, but here's the project: https://github.com/oneblackbear/phrocco https://github.com/oneblackbear/phrocco And here's an example: http://media.oneblackbear.com.s3.amazonaws.com/WaxUrl.html http://media.oneblackbear.com.s3.amazonaws.com/WaxUrl.html
wh-uws 13y ago
Looking through jQuery's test suite provides alot of insight also https://github.com/jquery/jquery/blob/master/test/unit/core.js https://github.com/jquery/jquery/blob/master/test/unit/core....
leeoniya 13y ago
i actually find docco-style docs more difficult to read with mostly single-line notes due to the spacing :( some sort of block folding would help a lot to follow code progression like a story. i'm not certain this is the best display type for all commenting styles.
- chucknelson 13y ago
  Agreed - when there is a comment for every line (or so it seems), it's a bit of comment overload, especially when looking at docco output.
nej 13y ago
This is great.
ori_b 13y ago
Is it strange that I found myself mostly ignoring the comments when I was trying to understand this? The only thing I found the comments useful for understanding was pointing out the IE compatibility behavior.
- bobfunk 13y ago
  Had the same experience, found it easier to just read the code .
  - qpleple 13y ago
    That's the point: you read the code, and when something is not crystal clear, you glance at the comment.
salvadornav 13y ago
Here's a different approach: http://www.keyframesandcode.com/resources/javascript/deconstructed/jquery/ http://www.keyframesandcode.com/resources/javascript/deconst...
scottharveyco 13y ago
If anyone is interested in generating this type of documentation but for larger projects you might want to check out Groc https://github.com/nevir/groc https://github.com/nevir/groc It handles multiple languages and keeps your document structure in the navigation.
marcamillion 13y ago
I absolutely love this. I would love to see a project (a curated version) like this for Rails.

This is an old version of jQuery run through docco, with a simple page on top of the docco output. docco: http://jashkenas.github.io/docco/ http://jashkenas.github.io/docco/ I just checked out jquery and built it myself. Here's a newer version: http://shalecraig.com/docs/manipulation.html http://shalecraig.com/docs/manipulation.html

jliechti1 13y ago

Hey, this is pretty cool. Does this style of annotation exist for any other libraries/projects? I think the left side could be expanded into a pretty good pedagogical tool using mini-examples and explanations to focus on key concepts in the code.

muriithi 13y ago
Backbone.js http://documentcloud.github.io/backbone/docs/backbone.html http://documentcloud.github.io/backbone/docs/backbone.html Underscore.js http://underscorejs.org/docs/underscore.html http://underscorejs.org/docs/underscore.html
emillon 13y ago
It's similar to literate programming, which consists in exchanging the focus between code and comments. I believe that Coffeescript just got a literate processor, so the community may benefit from this in the near future. Because GHC supports it, it is also very popular in the Haskell community.
romaniv 13y ago
Many (around 5) years ago I wrote a library that parsed PHP files and generated logical "anchors" after classes and functions. I combined that with a simple CRUD application that allowed anyone to view source code in the browser and add/change comments dynamically. No one cared.
- kristopolous 13y ago
  have the source posted anywhere?
  - romaniv 13y ago
    The main website it was on no longer exists, but there are bits and pieces here and there. http://code.ohloh.net/project?pid=LOfjD4AHjNo&prevcid=1&browser=Default&did=libs%2FDoc&cid=ks-xq0gsZHA http://code.ohloh.net/project?pid=LOfjD4AHjNo&prevcid=1&... doc_code2html() takes PHP code as argument, and uses built-in PHP tokenizer to add CSS classes to code. After that, you can use vanilla CSS to color things up. Up to this day this is the simplest and most accurate PHP highlighter I've seen. doc_getCodeAnchors() takes php code as argument and returns an associative array of anchors. I.e.: array( 'MyClass.methodName' => array('line' => 3, 'type' => 'class', 'name' => "methodName"), ) Comments class was a controller that actually displayed files with highlighting and comments, allowing you to add and edit comments. And yes, I am fully aware of deficiencies of that code, but I still think the core ideas there are pretty cool.
pavel_lishin 13y ago
One of backbone.js's example apps does this, and it was my favorite thing about their docs: http://backbonejs.org/docs/todos.html http://backbonejs.org/docs/todos.html
malingo 13y ago
raganwald put together annotated source for his coffeescript implementation of hashlife, also using Docco: http://recursiveuniver.se/docs/cafeaulife.html http://recursiveuniver.se/docs/cafeaulife.html
rossriley 13y ago
I did one for PHP a while back. Not perfect, but here's the project: https://github.com/oneblackbear/phrocco https://github.com/oneblackbear/phrocco And here's an example: http://media.oneblackbear.com.s3.amazonaws.com/WaxUrl.html http://media.oneblackbear.com.s3.amazonaws.com/WaxUrl.html

wh-uws 13y ago

Looking through jQuery's test suite provides alot of insight also https://github.com/jquery/jquery/blob/master/test/unit/core.js https://github.com/jquery/jquery/blob/master/test/unit/core....

leeoniya 13y ago

i actually find docco-style docs more difficult to read with mostly single-line notes due to the spacing :( some sort of block folding would help a lot to follow code progression like a story. i'm not certain this is the best display type for all commenting styles.

chucknelson 13y ago
Agreed - when there is a comment for every line (or so it seems), it's a bit of comment overload, especially when looking at docco output.

nej 13y ago

This is great.

ori_b 13y ago

Is it strange that I found myself mostly ignoring the comments when I was trying to understand this? The only thing I found the comments useful for understanding was pointing out the IE compatibility behavior.

bobfunk 13y ago
Had the same experience, found it easier to just read the code .
- qpleple 13y ago
  That's the point: you read the code, and when something is not crystal clear, you glance at the comment.

salvadornav 13y ago

Here's a different approach: http://www.keyframesandcode.com/resources/javascript/deconstructed/jquery/ http://www.keyframesandcode.com/resources/javascript/deconst...

scottharveyco 13y ago

If anyone is interested in generating this type of documentation but for larger projects you might want to check out Groc https://github.com/nevir/groc https://github.com/nevir/groc It handles multiple languages and keeps your document structure in the navigation.

marcamillion 13y ago

I absolutely love this. I would love to see a project (a curated version) like this for Rails.