Add documentation generator

[micuat]

currently testing here: https://naotohieda.com/hydra-yuidoc-test/classes/GlslFunctions.html

repo: https://github.com/micuat/hydra-yuidoc-test

annotated code looks like

/**
* This is a test object that contains GLSL functions.
*
* @class GlslFunctions
*/
const glslFunctions = {};

/**
* noise (source)
*
* @method noise
* @param {Number} scale=10 Scale
* @param {Number} offset=0.1 Morphing speed
* @return {Object} Returns a source
*/
glslFunctions.noise = {
  name: 'noise',
  type: 'src',
  inputs: [
    {
      type: 'float',
      name: 'scale',
      default: 10,
    },
    {
      type: 'float',
      name: 'offset',
      default: 0.1,
    }
  ],
  glsl:
`   return vec4(vec3(_noise(vec3(_st*scale, offset*time))), 1.0);`
}

/**
* voronoi (source)
*
* @method voronoi
* @param {Number} scale=5 Scale
* @param {Number} speed=0.3 Morphing speed
* @param {Number} blending=0.3 Variation within each cell
* @return {Object} Returns a source
*/
glslFunctions.voronoi = {
  name: 'voronoi',
  type: 'src',
  inputs: [
    {
      type: 'float',
      name: 'scale',
      default: 5,
    },
    {
...

[ojack]

Oooh cool! I definitely think we should add a documentation generator, i.e. a set of scripts that process multiple resources into the resulting documentation.

Some questions and thoughts about YUIdoc / jsdoc annotations:

1. how does this fit in with the docsify documentation? I can imagine a script that parses the jsdoc comments from hydra-synth into markdown that gets used within the interactive documentation. i.e. https://github.com/jsdoc2md/jsdoc-to-markdown

2. The jsdoc/yuidoc notation seems really useful for documenting the additional functions (i.e. s0.initCam, render(), setFunction(), etc.), so I would love to start adding that in to the other parts of hydra-synth. For this specific example, ​isn't it possible to auto-generate js-doc formatting from the existing glsl-functions.js? (If necessary, we could also add a description field for each input parameter). But maybe this way is more readable.

3. I want to make sure this stays in sync with the ideas at: https://github.com/ojack/hydra/issues/109 , specifically around using the function reference as part of Intellisense / autocomplete and adding type definitions.

[micuat]

@ojack

1. yes we can add those modules and configure package.json to automate the process - I will check how this works (and if necessary I will switch it to jsdoc)
2. it feels you need to add an extra step to convert the js file to another js file that yui/jsdoc can load. I don't know if it's a good idea. I will check if there is an option to load parameters/descriptions from other sources (in our case, js object)
3. sure, I need to see what others have been doing (by the way using cm6 has been a nightmare, I was almost crying because of lack of examples)