tern-node-api-doc

A plugin for generating Node.js API docs on-the-fly and associating them with the corresponding modules and functions in the tern JavaScript code analysis engine.

It's currently only useful when you are using tern to edit or analyze the node.js standard library itself.

Why? Node.js API documentation exists in external Markdown files, not in docstrings embedded in the code. This plugin lets tern parse the Markdown documentation and associate it with the corresponding module, function, or variable. Without this plugin, if you use tern to edit or analyze the node.js standard library, most things will not have associated documentation.

Documentation on Sourcegraph

Usage

git clone git://github.com/sourcegraph/tern-node-api-doc.git

Install dependencies

Run npm install to fetch tern.

Configure for use with tern

The plugin requires 3 paths to be specified as configuration options in your .tern-project file:

• apiDocDir: the directory containing node.js API documentation (doc/api in the node.js git repository).
• apiSrcDir: the directory containing the node.js API modules (lib/ in the node.js git repository).
• generateJSPath: the path to the tools/doc/generate.js script in the node.js git repository.

The easiest way to satisfy these requirements is to clone the github.com/joyent/node repository. If you cloned it to /home/alice/node, then you would use the following configuration:

{
  "apiDocDir": "/home/alice/node/doc/api",
  "apiSrcDir": "/home/alice/node/lib",
  "generateJSPath": "/home/alice/node/tools/doc/generate.js"
}

With tern's condenser

To use this plugin with tern's condenser, specify the configuration on the command line as the following example demonstrates.

$ node_modules/tern/bin/condense --plugin node-api-doc='{"apiDocDir":"testdata/doc/api","apiSrcDir":"testdata/lib","generateJSPath":"testdata/tools/doc/generate.js"}' --plugin node --plugin doc_comment testdata/lib/foo.js

The output is:

{
  "!name": "testdata/lib/foo.js",
  "!define": {
    "!node": {
      "testdata/lib/foo`js": {
        "fizz": {
          "!type": "fn()",
          "!span": "8[0:8]-12[0:12]",
          "!doc": "<p>Fizzes the foo.\n\n</p>\n"
        },
        "Bar": {
          "zip": {
            "!type": "fn(pow: ?)",
            "!span": "118[9:4]-121[9:7]",
            "!doc": "<p>Zips the pow.\n\n</p>\n"
          },
          "prototype": {
            "baz": {
              "!type": "fn(string: ?, offset: ?)",
              "!span": "192[13:14]-195[13:17]",
              "!doc": "<p>Bazzes the bar.\n\n</p>\n<p>See <code>bar.length</code> above.\n\n</p>\n"
            }
          },
          "!type": "fn(arg: ?)",
          "!span": "58[3:8]-61[3:11]",
          "!doc": "<p>Bar is a class.\n\n</p>\n"
        },
        "Bar2": {
          "!type": "fn()",
          "!span": "78[5:8]-82[5:12]",
          "!doc": "<p>A second Bar.\n</p>\n"
        },
        "CON": {
          "!type": "number",
          "!span": "255[16:8]-258[16:11]",
          "!doc": "<p>A bar constant.\n\n</p>\n"
        }
      }
    }
  }
}

All of the docstrings came from external Markdown files in the testdata/doc/api directory.

Running tests

Run npm test.

Authors

Contributions are welcome! Submit a GitHub issue or pull request.

• Quinn Slack (sqs)