jsdoc -c jsdoc.json -r -t docs -d gen/docs lib
-c: use this config file for jsdoc-r: Recurse into subdirectories of the specified source directories-t: Use template in path docs-d: Generated html files put in gen/docslibThe template generation is set up so that:
.tmpl are skipped<?js ?> tags, but this is not requiredThe docs directory is treated as a jsdoc template, in which the html-files are the template files. This allows for a gradual adaptation of the html-files to templates; unchanged html-files will pass through jsdoc unchanged.
The added value of using jsdoc for documentation generation, is that the complete documentation information, as collected by jsdoc from the source, is available for usage. This way, it’s possible to insert technical notes from the source code into the documentation.
This section contains notes on the usage of jsdoc functionality, to aid with the handling of its generated data.
publish()taffyDataA table containing all data collected from the source code, related to jsdoc generation. See below for more info and example outputs.
optExample of opt variable:
{
"_":["../github/vis/lib/network/"],
"configure":"jsdoc.json",
"recurse":true,
"template":"/home/wim/projects/jsdoc/default",
"destination":"./out/",
"encoding":"utf8"
}
tutorialThis does not appear to be of use for the generation of vis.js documentation.
Example of tutorial variable:
{
"longname":"",
"name":"",
"title":"",
"content":"",
"parent":null,
"children":[],
"_tutorials":{}
}
envThis contains addition info for the current execution of jsdoc. Example of env variable:
{
"run":{"start":"2017-09-16T05:06:45.621Z","finish":null},
"args":["-c","jsdoc.json","-r","-t","default","../github/vis/lib/network/"],
"conf":{
"plugins":["/usr/lib/node_modules/jsdoc/plugins/markdown.js"],
"recurseDepth":10,
"source":{"includePattern":".+\\.js(doc|x)?$","excludePattern":""},
"sourceType":"module",
"tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]},
"templates":{"monospaceLinks":false,"cleverLinks":false}
},
"dirname":"/usr/lib/node_modules/jsdoc",
"pwd":"/home/wim/projects/jsdoc",
"opts":{ <<same as parameter 'opt' above>> },
"sourceFiles":[ <<list of full path names of all js-source files used as input>> ],
"version":{"number":"3.5.4","revision":"Fri, 04 Aug 2017 22:05:27 GMT"}
}
This is a parameter to publish(). It’s a table containing all data collected from the source code, related to jsdoc generation.
I can’t find any way to return a list of fields for the data items in the taffyDB docs, therefore below there are examples of items, for better understanding of usage.
Example usage:
var data = taffyData;
var tmp = data().filter({name:'Label'}).get();
Returns an array with all items with name === 'Label'. Example output of one of these items, for a class:
In these examples, block comment endings are redacted to ‘ * /’
{
"comment":"/**\n * A Label to be used for Nodes or Edges.\n * /",
"meta":{
"range":[3770,41303],
"filename":"Label.js",
"lineno":167,
"columnno":0,
"path":"/home/wim/projects/github/vis/lib/network/modules/components/shared",
"code":{
"id":"astnode100065034",
"name":"Label",
"type":"ClassDeclaration",
"paramnames":["body","options","edgelabel"]
}
},
"classdesc":"
A Label to be used for Nodes or Edges.
",
"name":"Label",
"longname":"Label",
"kind":"class",
"scope":"global",
"params":[
{"type":{"names":["Object"]},"name":"body"},
{"type":{"names":["Object"]},"name":"options"},
{"type":{"names":["boolean"]},"optional":true,"defaultvalue":false,"name":"edgelabel"}
],
"___id":"T000002R005289",
"___s":true
}
Example of item for an instance method:
var tmp = data().filter({name:'_drawText'}).get();
Full output returned:
[{
"comment":"/**\n *\n * @param {CanvasRenderingContext2D} ctx\n * @param {boolean} selected\n * @param {boolean} hover\n * @param {number} x\n * @param {number} y\n * @param {string} [baseline='middle']\n * @private\n * /",
"meta":{
"range":[20060,22269],
"filename":"Label.js",
"lineno":652,
"columnno":2,
"path":"/home/wim/projects/github/vis/lib/network/modules/components/shared",
"code":{
"id":"astnode100066427",
"name":"Label#_drawText",
"type":"MethodDefinition",
"paramnames":["ctx","selected","hover","x","y","baseline"]
},
"vars":{"":null}
},
"params":[
{"type":{"names":["CanvasRenderingContext2D"]},"name":"ctx"},
{"type":{"names":["boolean"]},"name":"selected"},
{"type":{"names":["boolean"]},"name":"hover"},
{"type":{"names":["number"]},"name":"x"},
{"type":{"names":["number"]},"name":"y"},
{"type":{"names":["string"]},"optional":true,"defaultvalue":"'middle'","name":"baseline"}
],
"access":"private",
"name":"_drawText",
"longname":"Label#_drawText",
"kind":"function",
"memberof":"Label",
"scope":"instance",
"___id":"T000002R005388",
"___s":true
}]
jsdoc template renderingSee function createRenderer(fromDir, data) in code for usage.
There are two calls for rendering templates:
var html = renderer.render(inFile, docData);var html = renderer.partial(inFile, docData);The difference is that render() will use a default layout template, if present, which will encapsulate all html. This can be set by:
renderer.layout = 'path/to/default/layout.tmpl';
Parameter docData is a hash which is used to pass parameters into a template. The standard way of using this appear to be:
<?js
var data = obj; // Whatever docData is
var self = this;
?>
But it also appear to be possible to use the elements of docData directly:
var docData = {
myTitle: 'Hello, pussycat!'
};
Within the template:
<?js= myTitle ?>