Adding custom content to generated JSDoc docs - jsdoc

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