Adding custom content to generated JSDoc docs

Question

We are working on a rewrite of our API documentation and we would like to add custom content to our generated JSDocs. This custom content could for instance be runnable snippets of code, which is a feature we currently have in our manually written docs (based on Jekyll injecting dynamic content). Is there a way of achieving this directly, using the templating system of JSDoc and some custom code today, alternatively indirectly by post-processing the generated html looking for some kind of symbols? Other JSDoc generators that could handle this is also of interest.

Say, we could have something like this

/**
 * @param {String} foo
 * @runnableExample foo-example
 */

would generate some kind of custom code for that @runnableExample code that would insert a file called ./examples/foo-example.js. This is just a suggestion for a good user experience, but not how it needs to be.

Answer 1

The JSDoc CLI has a useful -X flag which you can use to inspect (and process) the metadata from your annotations:

/**
 * @return {number}
 */
function answer() {
  return 42;
}

$ jsdoc -X tmp/example.js

[
    {
        "comment": "/**\n * @return {number}\n */",
        "meta": {
            "range": [
                28,
                62
            ],
            "filename": "example.js",
            "lineno": 4,
            "columnno": 0,
            "path": "/workspace/dev/tmp",
            "code": {
                "id": "astnode100000002",
                "name": "answer",
                "type": "FunctionDeclaration",
                "paramnames": []
            }
        },
        "returns": [
            {
                "type": {
                    "names": [
                        "number"
                    ]
                }
            }
        ],
        "name": "answer",
        "longname": "answer",
        "kind": "function",
        "scope": "global",
        "params": []
    },
    {
        "kind": "package",
        "longname": "package:undefined",
        "files": [
            "/workspace/dev/tmp/example.js"
        ]
    }
]

But what about custom tags? The -X flag will process them too:

/**
 * @answer 42
 */
function answer() {
  return 42;
}

[
    {
        "comment": "/**\n * @answer 42\n */",
        "meta": {
            "range": [
                22,
                56
            ],
            "filename": "example.js",
            "lineno": 4,
            "columnno": 0,
            "path": "/workspace/dev/tmp",
            "code": {
                "id": "astnode100000002",
                "name": "answer",
                "type": "FunctionDeclaration",
                "paramnames": []
            }
        },
        "tags": [
            {
                "originalTitle": "answer",
                "title": "answer",
                "text": "42",
                "value": "42"
            }
        ],
        "name": "answer",
        "longname": "answer",
        "kind": "function",
        "scope": "global",
        "params": []
    },
    {
        "kind": "package",
        "longname": "package:undefined",
        "files": [
            "/workspace/dev/tmp/example.js"
        ]
    }
]

As you can see the output is pure JSON which makes it very easy to process either via JavaScript or any decent templating systems. I have abandoned JSDoc templates for a long time. I use jsdoc -X and process the annotations myself.

Recently I've been playing with JQ and EJS and fed the result to Slate to generate documentation websites: https://customcommander.github.io/project-blueprint/#project-blueprint-fake-api — This is the documentation website for a fake API.

What you want to achieve is definitely doable. Hopefully this is enough to get you started. If you want to know more: https://github.com/customcommander/project-blueprint