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:

```js
{
  "_":["../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:

```js
{
  "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:

```js
{
  "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:

```js
  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 ' * /'*

```js
{
  "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:

```js
  var tmp = data().filter({name:'_drawText'}).get();
```

Full output returned:

```js
[{
  "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:
 
```js
  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:

```js
var docData = {
  myTitle: 'Hello, pussycat!'
};
```
 
Within the template:

```
  <?js= myTitle ?>
```