atom / atomdoc

Atom's documentation parser for JavaScript / CoffeeScript

Atom and all repositories under Atom will be archived on December 15, 2022. Learn more in our official announcement

AtomDoc parser

Parse atomdoc with JavaScript / CoffeeScript.

Atomdoc is a code documentation format based on markdown. The atom team writes a lot of markdown, and its rules are deep in our brains. So rather than adopting some other format we'd need to learn, we decided to build a parser around a few markdown conventions.

Usage

It's on npm.

npm install atomdoc

It has only one method, parse:

AtomDoc = require 'atomdoc'

docString = """
  Public: My awesome method that does stuff, but returns nothing and has
  no arguments.
"""
doc = AtomDoc.parse(docString)

# Alternatively, you can avoid parsing "Returns" statements in documentation (useful for class-level documentation):
doc = AtomDoc.parse(docString, {parseReturns: false})

doc will be an object:

{
  "visibility": "Public",
  "description": "My awesome method that does stuff, but returns nothing and has\nno arguments.",
  "summary": "My awesome method that does stuff, but returns nothing and has\nno arguments."
}

Maximal example

Using all the features.

AtomDoc = require 'atomdoc'

docString = """
    Public: My awesome method that does stuff.

    It does things and stuff and even more things, this is the description. The
    next section is the arguments. They can be nested. Useful for explaining the
    arguments passed to any callbacks.

    * `count` {Number} representing count
    * `callback` {Function} that will be called when finished
      * `options` Options {Object} passed to your callback with the options:
        * `someOption` A {Bool}
        * `anotherOption` Another {Bool}

    ## Events

    ### contents-modified

    Public: Fired when this thing happens.

    * `options` {Object} An options hash
      * `someOption` {Object} An options hash

    ## Examples

    This is an example. It can have a description.

    ```coffee
    myMethod 20, ({someOption, anotherOption}) ->
      console.log someOption, anotherOption
    ```

    Returns null in some cases
    Returns an {Object} with these keys:
      * `someBool` a {Boolean}
      * `someNumber` a {Number}
"""
doc = AtomDoc.parse(docString)

doc will be an object:

{
  "visibility": "Public",
  "summary": "My awesome method that does stuff.",
  "description": """
    My awesome method that does stuff.
    It does things and stuff and even more things, this is the description. The
    next section is the arguments. They can be nested. Useful for explaining the
    arguments passed to any callbacks.
  """,
  "arguments": [
    {
      "name": "count",
      "description": "{Number} representing count",
      "type": "Number",
      "isOptional": false
    },
    {
      "children": [
        {
          "name": "options",
          "description": "Options {Object} passed to your callback with the options:",
          "type": "Object",
          "isOptional": false
          "children": [
            {
              "name": "someOption",
              "description": "A {Bool}",
              "type": "Bool",
              "isOptional": false
            },
            {
              "name": "anotherOption",
              "description": "Another {Bool}",
              "type": "Bool",
              "isOptional": false
            }
          ],
        }
      ],
      "name": "callback",
      "description": "{Function} that will be called when finished",
      "type": "Function",
      "isOptional": false
    }
  ],
  "events": [
    {
      "name": "contents-modified",
      "summary": "Fired when this thing happens.",
      "description": "Fired when this thing happens.",
      "visibility": "Public",
      "arguments": [
        {
          "children": [
            {
              "name": "someOption",
              "description": "{Object} An options hash",
              "type": "Object",
              "isOptional": false
            }
          ],
          "name": "options",
          "description": "{Object} An options hash",
          "type": "Object",
          "isOptional": false
        }
      ]
    }
  ],
  "examples": [
    {
      "description": "This is an example. It can have a description",
      "lang": "coffee",
      "code": "myMethod 20, ({someOption, anotherOption}) ->\n  console.log someOption, anotherOption",
      "raw": "```coffee\nmyMethod 20, ({someOption, anotherOption}) ->\n  console.log someOption, anotherOption\n```"
    }
  ],
  "returnValues": [
    {
      "type": null,
      "description": "Returns null in some case"
    },
    {
      "type": "Object",
      "description": "Returns an {Object} with the keys:\n\n* `someBool` a {Boolean}\n* `someNumber` a {Number}"
    }
  ]
}

Notes

The parser uses marked's lexer.

atomdoc's Issues

using wrong function description

On the Task documentation the ::once function is showing documentation for the .once function.

The function

The documentation

How do you handle arrays?

Suppose my method returns an array of {Widgit}s. How would I state this considering that the link parsing regex is: /\{([\w.]+)\}/

• Returns {Array} of {Widget} sets the type as 'Array'
• Returns {Array{Widget}} and other combinations of nested either indicate type to be {Widget} or fail.

Issue parsing 'Returns' in description

Moved from atom/atom#15101

The Atom Workspace documentation lists a workspace item's required methods but does not list the optional methods listed in the comments of /src/workspace.js.

Once the parser hits the Returns keyword after getTitle() it thinks the description is over.

Documenting things other than functions

Mostly a question, but why does atomdoc not have support for classes (coffeescript, or es6), variables, or class properties?

How exactly do I use this with my project?

From readme I only saw that this package turn a string into an object. Even though I still don't know what exact procedure to make that happen. Can it be more beginner-friendly and add more elaborate examples that I can follow? Thx.

Add support for services

With atom/atom#5165 and atom/atom#5277 merged, we should have a method of documenting services provided akin to events.

I'm thinking something along the lines of:

## Service `status-bar` v0.57.0

### `consumeStatusBar`

Essential: Provides a reference to the status bar to the consuming package.

* `statusBar` Status bar {Object}
    * `addLeftTile` A {Function} for adding a tile to the left side of the status bar
    * `addRightTile` A {Function} for adding a tile to the right side of the status bar
    * `getLeftTiles` A {Function} for getting the list of tiles on the left.
    * `getRightTiles` A {Function} for getting the list of tiles on the right.

Function name

There seems to be a lack of support for the function name. Just wondering why. The AtomDoc comment wouldn't need to specify it I guess, maybe it should just come from the js/coffeescript itself, when parsed.

Should AtomDoc then support or expect it?

`undefined` is rendered as ``

It seems that when `undefined` is in the comment, it is rendered as ``.

Source:

Result: