jrtechs-vis/docs/README.md

Command line usage example

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/docs
• Source files to parse are taken from directory lib

Notes

The template generation is set up so that:

• Files ending in .tmpl are skipped
• All non-html files are plain copied
• html-files can contain <?js ?> tags, but this is not required

Intention

The 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.

---

Usage of and Notes on Source Code

This section contains notes on the usage of jsdoc functionality, to aid with the handling of its generated data.

Parameters of publish()

Parameter taffyData

A table containing all data collected from the source code, related to jsdoc generation. See below for more info and example outputs.

Parameter opt

Example of opt variable:

{
  "_":["../github/vis/lib/network/"],
  "configure":"jsdoc.json",
  "recurse":true,
  "template":"/home/wim/projects/jsdoc/default",
  "destination":"./out/",
  "encoding":"utf8"
}

Parameter tutorial

This 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":{}
}

Global variable env

This 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"}
}

taffyData

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 rendering

See 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 ?>