ExplainJS

Try It

Try it out on your own JavaScript file. Just enter the URL to your source:

What It Looks Like

See It In Action

Here are some big time libraries that weren't designed for ExplainJS at all. See how they look:

CURL It

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":""
    },
    ...
  ]
}

NODE/NPM

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);
});
	    

GRUNT PLUGIN

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.

How It Works

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.

Why Does ExplainJS Exist?

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.

Need Help? Have Suggestions?

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.