Docco: Quick JavaScript Documentation

By  on  

Docco is a free Node.js-powered JavaScript documentation generation tool.  I was never big into documenting JavaScript methods within the source files themselves, but my team made the decision to go that route for a new project and I've come full swing.  Pair the in-source documentation with the Docco and you have pretty JavaScript documentation along side the source code.

You can install Docco using npm or grab the repo directly.  With Docco available, you can create code structures a la:

// The code in `oninstall` and `onactivate` force the service worker to
// control the clients ASAP.
self.oninstall = function(event) {
  event.waitUntil(self.skipWaiting());
};

self.onactivate = function(event) {
  event.waitUntil(self.clients.claim());
};

// When fetching, distinguish if this is a resource fetch. If so,
// apply the server selection algorithm. Else, let the request reach the
// network. Could should be autoexplanatory.
self.onfetch = function(event) {
  var request = event.request;
  if (isResource(request)) {
    event.respondWith(fetchFromBestServer(request));
  } else {
    event.respondWith(fetch(request));
  }
};

// A request is a resource request if it is a `GET` for something inside `imgs`.
function isResource(request) {
  return request.url.match(/\/imgs\/.*$/) && request.method === 'GET';
}

// Fetching from the best server consists of getting the server loads,
// selecting the server with lowest load, and compose a new request to
// find the resource in the selected server.
function fetchFromBestServer(request) {
  var session = request.url.match(/\?session=([^&]*)/)[1];
  return getServerLoads(session)
    .then(selectServer)
    .then(function(serverUrl) {
      // Get the resource path and combine with `serverUrl` to get
      // the resource URL but **in the selected server**.
      var resourcePath = request.url.match(/\/imgs\/[^?]*/)[0];
      var serverRequest = new Request(serverUrl + resourcePath);
      return fetch(serverRequest);
    });
}

Running Docco on the contents above generates a nicely formatted page with "inline" comments on the left and comment-less code on the right:

Docco Sample

Docco has a few parameters for customization but the conversion is fairly simple and there are extension for gulp, grunt, and other utilities.  This type of doc generation and display is awesome for both teaching JavaScript and for maintenance amongst a team.  You can see Docco used within the Service Worker Cookbook code examples.

Recent Features

  • By
    Interview with a Pornhub Web Developer

    Regardless of your stance on pornography, it would be impossible to deny the massive impact the adult website industry has had on pushing the web forward. From pushing the browser's video limits to pushing ads through WebSocket so ad blockers don't detect them, you have...

  • By
    Write Better JavaScript with Promises

    You've probably heard the talk around the water cooler about how promises are the future. All of the cool kids are using them, but you don't see what makes them so special. Can't you just use a callback? What's the big deal? In this article, we'll...

Incredible Demos

  • By
    Table Cell and Position Absolute

    If you follow me on Twitter, you saw me rage about trying to make position: absolute work within a TD element or display: table-cell element.  Chrome?  Check.  Internet Explorer?  Check.  Firefox?  Ugh, FML.  I tinkered in the console...and cussed.  I did some researched...and I...

  • By
    Select Dropdowns, MooTools, and CSS Print

    I know I've harped on this over and over again but it's important to enhance pages for print. You can do some things using simple CSS but today's post features MooTools and jQuery. We'll be taking the options of a SELECT element and generating...

Discussion

  1. Nibin

    Is there any workaround to support block comments in docco?

Wrap your code in <pre class="{language}"></pre> tags, link to a GitHub gist, JSFiddle fiddle, or CodePen pen to embed!