marijnh/getdocs

Getdocs is not JSDoc

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:

• A JavaScript identifier, optionally followed by any number of properties, which are a dot character followed by a JavaScript identifier. A type name can be followed by a list of type parameters, between angle brackets, as in Object<string> (an object whose properties hold string values).

• An array type, which is a type wrapped in [ and ]. [x] is equivalent to Array<x>.

• A function type, which is written as a parenthesized list of argument types. Each argument type may optionally be prefixed with an argument name, which is an identifier followed by a colon. When an argument is prefixed by the string ..., it is marked as a rest argument. After the closing parenthesis, an optional return type may appear after an arrow, written either → or ->.

• A nullable type, written as a question mark followed by a type.

• An unspecified or “any” type, written as an asterisk *.

• An object type, written as a list of properties wrapped in { and } braces. Each property must start with an identifier, followed by a colon, followed by a type.

• A string literal, enclosed by double quotes, or a number literal.

• A type followed by extends followed by another type, to indicate a sub-type.

Here are some examples of types:

• Math.pow: (base: number, exponent: number) → number

• Element.insertBefore: (newNode: Node, before: ?Node) → Node

• console.log: (...data: *)

• A pair of coordinates: {x: number, y: number}

• An array of strings: [string]

• An array of numbers or a string: union<[number], string> (what the name union means isn't something getdocs is aware of, but you could use it for union types, and maybe render it as [number] | string in your output).

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:

• description: The doc comment for the item.

• loc: A {line, column, file} object pointing at the start of the item.

• exported: Set if the item is exported using ES6 module syntax.

• constructor: For classes with a documented constructor, this points at the constructor function.

• extends: Holds the type of the supertype of a class or other sub-type.

• staticProperties: For classes, this holds properties and methods that appear directly on the constructor.

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

• type: The name of the type. Instances of classes should use the (capitalized) class name. Builtin types will have names like Array or Function. Getdocs does not prescribe a naming of primitive types, but for consistency I recommend you use number, string, and bool.

• properties: An object mapping property names to types.

• params: For function types, this holds an array of parameter types. Parameter types can have these additional properties:

  • name: The name of the parameter.

  • rest: Set when this is a rest parameter.

  • default: The default value of the parameter (as a raw source string).

• returns: For function types, this holds the type that is returned.

• typeParams: For array types or named types with parameters (angle bracket syntax), this holds an array of parameter types.

• optional: Set for nullable types.

• id: The path to this type. For a top-level variable foo this'll be "foo", for the type of the property bar under foo, it'll be "foo.bar", and so on.

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:

• filename: string The filename of the given code. Required.

• items: ?Object An existing items object to add the items found in the given code to.

• onComment: ?(block: bool, text: string, start: number, end: number, startPos: Object, endPos: Object) Will be called for each comment in the code, if given.

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.

getdocs's Issues

Support documentation for parameters and returns

It should be cool if we could add documentation for parameters and returns fucntion. An idea:

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

ternjs has the same issue ternjs/tern#691

Support CommonJS style exports

Recognize that exports is a special object, and treat assignments to it as exported top-level definitions

And equate an assignment to module.exports to a definition of an item named default (which is at least coherent with ES6 module definitions)

md or html

any plan for convert the output JSON into md or html format?

Status/future?

Hey @marijnh, I like what I've seen so far and played with for this project. Curious as to what the status is on things like supporting CommonJS and TernJS integration? Also, have any doc generators been built yet that you are aware of?

Thanks much!

Possible to document arbitrary code files, like cpp, ruby, or typescript?

I'm looking for a tool that won't stumble on the code.

So far, every JSDoc or TSDoc tool has some problems, because they all rely on the underlying code to infer features, or for parsing, or whatever reason, and eventually they all do what I don't want them to do (crash, infer too much, etc).

What I need, is a tool that will take my comments as the source of truth and completely ignore any and all code, including code that it can not understand.

Can I do this with getdocs?

F.e., if I supply names and types, can I make it completely ignore all code source, and only read my comments?

`exported` is not used by builddocs

The exported property is not used by builddocs, so I guess we could just remove it?

Precise definition of "Nullable"

I'd like some clarification on what does nullable mean?

Here's my understanding: (questions in bold)

1. A nullable function parameter can accept null, or not be passed at all. Can it accept undefined?
2. A nullable type is that type or null, e.g. both null and string match ?string, but undefined does not.

What are the rules for nullable object properties, e.g.

// :: Object<string>
const foo = {
  // :: ?"bar"
  bar: "bar",
  // :: "baz"
  baz: "baz"
};

Which of the following adhere to that type:

1. { bar: null, baz: "baz" }
2. { bar: undefined, baz: "baz" }
3. { baz: "baz" }
4. { bar: "bar", baz: "baz" }

I'm guessing 1, 3, 4.

How about class properties? e.g.

class Foo {
  constructor() {
    // :: ?string
    this.str = "";
  }
}

• Can str be absent from a Foo instance? e.g. foo.hasOwnProperty('str') === false?
• Can str be undefined or only null?

Can you think of any other cases that might warrant a more specific description?

Support documentation on destructuring definitions/assignments

Maybe? I don't think I've ever defined an exported item this way. But you could, and getdocs will currently explode if you try to document such a thing.

What if an argument accepts multiple types?

I'm looking to document this function.

The third parameter accepts string, array, or DOM element. How would one document this?

Allow documenting both a getter and a setter for a property

Currently, the tool will complain about the property being defined multiple times. Not sure how important this is, but it's a bug.

Find a way to document abstract methods/properties

In documenting ProseMirror's Fragment class, I am finding that I can't associate documentation for methods and properties that are only defined in subclasses with the class. I was kind of hoping I could do away with having doc comments that don't refer to concrete nodes, but I guess I can't.

One approach would be to have a kind of comment that adds a property or instance property to the node around it (which must be a class, constructor, or object literal). Would that cover all the cases or are there other issues? What would be a good way to recognize such nodes? +:: as a marker?