Instant side-by-side view of your comments and code.
Try it out on your own JavaScript file. Just enter the URL to your source:
Here are some big time libraries that weren't designed for ExplainJS at all. See how they look:
Want the raw data for yourself? Add .json to the request URL to get the raw comment blocks:
> curl http://explainjs.com/explain.json?src=http://cdnjs.cloudflare.com/ajax/libs/backbone.js/1.0.0/backbone.js
{ "src": "http://cdnjs.cloudflare.com/ajax/libs/backbone.js/1.0.0/backbone.js", "title":"backbone.js", "sections": [ { "comments":"<p>Backbone.js 1.0.0</p>", "code":"" }, ... ] }
If you want to run it yourself, checkout 'explainjs' on NPM.
npm install explainjs --save
var explainjs = require('explainjs'); var js = '//My Library\n doSomething();'; explainjs(js, function(error, results){ // <p>My Library</p> console.log(results.sections[0].comments); // doSomething(); console.log(results.sections[0].code); });
If you're looking for a Grunt plugin to automate this on your project, Collin Forrester built a very nice grunt-explainjs plugin.
Check out grunt-explainjs on GitHub or NPM.
ExplainJS downloads your source code and separates the comments from the code. Comments can be in the form of /* */ or //.
Then each comment is grouped with the following code block. The comment is converted to HTML using the markdown syntax.
Most JavaScript libraries seem to start with a list of data about the repo. For example, the title, url, author, license, description etc. For that reason ExplainJS enforces line breaks on the first comment.
For the rest of the comments, two line breaks cause a newline but one line break is ignored.
I built ExplainJS as a documentation generator for JavaScript, but it actually does ok with other JavaScript-like source files. It works ok with CSS/LESS too.
I was jealous of how underscore and backbone showed their annotated source code. I tried some 3rd party libraries to do the conversion from code -> documentation but it was a pain to setup. Ultimately I wasn't happy with the results and wanted it to be as easy as it could be.
So I figured it couldn't be that hard to build it myself. And I'm pretty obsessed with Node & NPM so I decided to post it with Heroku, NodeJS, and NPM.
Tweet at me: @BendyTree
Also, the full source is on GitHub. Feel free to send me a pull request with a test that shows a problem or requests a feature.