The DocTree Spec

Many programming languages have related projects for parsing documentation out of specially-formatted comments used to generate human-readable help files and IDE tooltips. This specification aims to standardize a representation of parsed documentation as a language-agnostic abstract syntax tree.

History

Most documentation generators target a single language and produce their own unique output. For projects that incorporate multiple languages this dispairty can make it difficult to find, maintain, and share documentation across all project members.

This specification is the result of the desire to create a single tool capable of producing unified documentation for an entire project regardless of the languages used.

Example

Example JavaScript input:

/**
 * # Utilities
 *
 * A library of utility methods.
 *
 * @class Utilites
 * @static
 */
export const Utilities = {
    /**
     * Escapes the given `html`.
     *
     * @method escape
     * @param {String} html String to escape.
     * @return {String} Escaped html.
     */
    escape(html) {
        return String(html)
            .replace(/&/g, '&')
            .replace(/</g, '&lt;')
            .replace(/>/g, '&gt;');
    }
};

Resulting DocTree AST as JSON:

{
    "type": "Documentation",
    "blocks": [
        {
            "type": "Block",
            "comment": {
                "type": "Comment",
                "description": "# Utilities\n\nA library of utility methods.",
                "tags": [
                    {
                        "type": "Tag",
                        "tag": "class",
                        "name": "Utilities"
                    },
                    {
                        "type": "Tag",
                        "tag": "static"
                    }
                ]
            },
            "code": {
                "type": "Code",
                "code": "export const Utilities = {"
            }
        },
        {
            "type": "Block",
            "comment": {
                "type": "Comment",
                "description": "Escapes the given `html`.",
                "tags": [
                    {
                        "type": "Tag",
                        "tag": "method",
                        "name": "escape"
                    },
                    {
                        "type": "Tag",
                        "tag": "param",
                        "kind": "String",
                        "name": "html",
                        "description": "String to escape."
                    },
                    {
                        "type": "Tag",
                        "tag": "return",
                        "kind": "String",
                        "description": "Escaped html."
                    }
                ]
            },
            "code": {
                "type": "Code",
                "code": "    escape(html) {\n        return String(html)\n            .replace(/&/g, '&amp;')\n            .replace(/</g, '&lt;')\n            .replace(/>/g, '&gt;');\n    }\n};"
            }
        }
    ]
}

In the Wild

• Tunic - A customizable documentation comment parser.

Influences

AST

• ESTree
• Shift AST

Generators

• Docco
• Doxygen
• Javadoc
• JSDoc
• Pandoc
• Perldoc (pod)
• PHPDoc
• RDoc
• Sphinx

---

MIT © Shannon Moeller