Home

Awesome

Getdocs

Getdocs is like JSDoc or documentation.js, running over ES6 code to extract information and inline documentation in order to generate docs, but without all the @s. It takes source files and outputs JSON.

For example, if you have this file, foo.js:

// :: (number, number) → number
// Add two numbers
export function plus(a, b = 2) {
  return a + b
}

You can say getdocs foo.js to get this JSON:

{
  "plus": {
    "type": "Function",
    "params": [
      {
        "type": "number",
        "name": "a"
      },
      {
        "type": "number",
        "default": "2",
        "optional": true,
        "name": "b"
      }
    ],
    "returns": { "type": "number" },
    "description": "Add two numbers",
    "exported": true
  }
}

The idea is to then feed this into a system (can be a simple set of templates) that massages it into actual human-readable documention files.

A getdocs doc comment starts with a double colon, optionally prefixed with a name (foo::) and followed by a type. It can be either a block comment or a continuous sequence of line comments. When you don't want to specify a type, for example because the type can be inferred from the code (as with a class declaration), you can write a single dash after the colons, instead of a type.

When no name is given, such a doc comment applies to the next program element after it. That element should be something with a name, like a variable, function, or class declaration, or an assignment that can be statically resolved.

The documented items found in the files passed to getdocs will be returned as part of a big JSON object. Nesting is only applied for class and object properties, where the properties are moved under the properties object of the item they are part of. A single namespace is assumed for the documented identifiers in the group of files.

Inside a doc comment, properties of the thing being defined can be added by writing nested, indented doc comments. For example:

// Plugin:: interface
//
// Objects conforming to the plugin interface can be plugged into a
// Foo
//
//   mount:: (Foo) → bool
//   Mount the plugin in this Foo. The return value indicates whether
//   the mount succeeded.
//
//   unmount:: (Foo)
//   Unmount the plugin from a Foo.

Further nesting below such a property (by adding more indentation) is supported.

Type syntax

A type can be:

Here are some examples of types:

Tags

It is possible to add tags to a documented item. These are words prefixed with a # character, appearing at the start of the comment — that is, immediately after the type.

A tag like #deprecated, for example, will result in a $deprecated: "true" property on the given item. The property is named by prepending the tag's name with a dollar sign.

You can give tags an explicit value other than "true" by writing an = character followed either by a word (a sequence of characters without whitespace) or a quoted JavaScript-style string. For example #chapter=selection or #added="2.1.0".

The #static tag can be used to indicate that a given class member is static (which is only necessary for doc comments that aren't tied to a syntactic element in the code).

Output JSON

The returned object maps item names to item descriptions. The following properties can appear in a description for a documented item:

In addition, they may have these properties, which can also appear on nested types:

Interface

The module exports the following function:

gather: (code: string, options: Object) → Object

It takes a code file, extracts the docs, and returns an object describing the documented items.

Options can have the following properties:

parseType: (input: string, start: number, loc: {file: string, line: number}) → {type: Object, end: number}

Parse a type in getdocs syntax into its object representation. start indicates where in the string the parsing should start. The returned object tells you where the type ended.

Will throw a SyntaxError when the type isn't valid.

stripComment: (comment: string) → string

Strips leading indentation and asterisks (as in the common block comment style where each line gets an asterisk) from a string.