javascript文档_Docco：快速JavaScript文档

爱被打了一巴掌 2023-02-22 01:18 49阅读 0赞

javascript文档

[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.

[Docco][]是由Node.js驱动的免费JavaScript文档生成工具。 我从不愿意在源文件本身中记录JavaScript方法，但是我的团队决定为新项目走那条路，而我已如火如荼。 将源文档与Docco配对，您将在源代码旁找到漂亮JavaScript文档。

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

您可以使用npm安装Docco或[直接获取存储库][grab the repo directly] 。 使用Docco，您可以创建代码结构，例如：

// 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会生成一个格式良好的页面，左侧带有“内联”注释，右侧带有无注释的代码：

![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.

Docco有一些用于自定义的参数，但转换非常简单，并且具有gulp，grunt和其他实用程序的扩展名。 这种类型的文档生成和显示对于教授JavaScript和团队维护都是很棒的。 您可以在[Service Worker Cookbook][]代码示例中看到使用的Docco。

> 翻译自: [https://davidwalsh.name/javascript-documentation][https_davidwalsh.name_javascript-documentation]

javascript文档

[Docco]: https://jashkenas.github.io/docco/
[grab the repo directly]: https://github.com/jashkenas/docco
[Docco Sample]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9kYXZpZHdhbHNoLm5hbWUvZGVtby9kb2Njby1zYW1wbGUucG5n?x-oss-process=image/format,png
[Service Worker Cookbook]: https://serviceworke.rs/message-relay_index_doc.html
[https_davidwalsh.name_javascript-documentation]: https://davidwalsh.name/javascript-documentation