Add documentation generator
micuat opened this issue · comments
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,
},
{
...
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:
-
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
-
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.
-
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.
- 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)
- 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)
- 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)