Docco:Rychlá dokumentace JavaScriptu

Docco je bezplatný nástroj pro generování dokumentace JavaScriptu založený na Node.js. Nikdy jsem se příliš nezabýval dokumentováním metod JavaScriptu v rámci samotných zdrojových souborů, ale můj tým se rozhodl jít touto cestou pro nový projekt a já jsem šel naplno. Spárujte zdrojovou dokumentaci s dokumentem Docco a vedle zdrojového kódu máte pěknou dokumentaci JavaScriptu.

Docco můžete nainstalovat pomocí npm nebo přímo stáhnout repo. S dostupným Docco můžete vytvářet struktury kódu 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);
    });
}

Spuštěním Docco na obsah výše se vygeneruje pěkně naformátovaná stránka s „vloženými“ komentáři vlevo a kódem bez komentářů vpravo:

Docco má několik parametrů pro přizpůsobení, ale převod je poměrně jednoduchý a existují rozšíření pro gulp, grunt a další nástroje. Tento typ generování a zobrazování dokumentů je skvělý jak pro výuku JavaScriptu, tak pro údržbu v týmu. Můžete vidět Docco použité v příkladech kódu Service Worker Cookbook.