Add jsdoc documentation

[danigb]

Hi,

This pull request moves the documentation inside the js source files and converts it to a jsdoc format. The documentation is added to the beginning of the file, just after the use strict declaration and no code was modified. Unfortunately my editor removes the whites paces from the end of the lines, so the diff are not so clear as I would desired.

This commit includes the following changes:

• Convert the documentation in docs/docs.md to jsdoc format
• Include the documentation of each function inside each source file
• Add incomplete documentation
• Add FIXME tags to signal where the documentation needs to be written or completed
• Add a jsdoc3 configuration file (named: .jsdoc3.json)
• Add a script to package.json to generate the documentation: npm run docs

The html jsdoc3 documentation is generated inside docs/api. If you set a github pages at master's docs/ you can look at the documentation directly from the browser: https://danigb.github.io/genish.js/api/

Some work would be necessary after the merge: I've added some FIXME tags to mark the parts of the documentation I could resolve myself.

Hope you like it.

[danigb]

Update: I come back to a review and I found a couple of errors (a missing module export and a repeated name). I fixed them in a second commit.

I would need some help to finish this work. In fact, I don't know in which module should I put the following modules (and thats why they appear as global in the generated documentation):

• memo
• mix
• mstosamps
• mtof
• pan
• prop
• rate
• sah

Cheers

[charlieroberts]

I like the way the your jsdocs look! To be honest sometimes I get annoyed editing files with the docs inlined, but with these simple files it makes a lot of sense.

I do always run into problems with my JS style not really playing very nicely with JSDoc (or ESDoc, or any of the other doc systems I've tried). With genish.js the problem comes from the fact that everything is basically a 'global' object. Identifying a function as a static method of a non-existent object (for example, eq is listed as a static method of the comparison object) is problematic :)

There are a few solutions that I could see:

1. Figure out how to get a nicely organized jsdocs page with the correct terminology... basically a collection of global objects that are organized by category.
2. Organize the ugens into collection objects (genish.comparison, genish.control etc). I am fairly opposed to this.

Anyways, I have beat my head against the wall trying to get jsdocs to work for me on many projects. In other libraries I've written jsdoc just hates the way I use prototype objects and mixins... no matter what I try I can't get it to represent the libraries correctly.

Basically I'm saying... if you can figure this out (via option 1), great! I'm happy to accept a pull request. But I don't want to be the one to fight with jsdocs :)

[danigb]

Hi Charlie,

Yes, I understand the pain of use jsdoc. I've been struggling with it for a while until I got decent results in my projects. In any case, for me, having an standard, parseable documentation in the same file as the code compensates long the problems. In my experience, keeping code and documentation separate ends in that the documentation is never updated. On the other hand, using and standard that lot of people are use to read reduces the barrier of entry when reading the code.

Anyway, I understand your concerns. My libraries are usually a bunch of global functions (as I like the functional style) and my solution was do what I did here: divide in "modules" (this is the jsdoc terminology) and say explicitly in the readme that they are all global to a namespace. If you can't live with "modules" instead of "categories", we are in a dead end with jsdoc. The only solution (I can imagine) is to write a template that outputs the html the way you like (because jsdoc alone outputs json) ... And I think is not worth the work.

For completeness sake, do you mind to think in which "category" should we put the functions not categorized yet? (memo, ...) That way at least we can update the missing documentation in your docs.md file.

Cheers, Dani

[charlieroberts]

Just to be clear, my problem is really that docs lists ugens as static methods of non-existent objects. That's incorrect; if I was just reading the docs I would assume that genish.comparison was a valid JS object containing the associated methods. I'm not 100% against organizing the library that way, although I think it would require some thinking. But having the docs be incorrect is bad.

I'll leave this open for a while in case I get some free time to play around and see if there's way to get jsdocs to organize the information without having to use additional container objects in the library.

[danigb]

Hi Charlie,

First of all, I don't want to make changes you will after regret, so it's ok to think about it carefully. Also, I don't think is THAT important: my goal was to learn how the code was organized while helping with the documentation, and it's done. Said that, a couple of things:

First of all, I think you're misunderstanding the concept of "module" and "static method". As far as I know, the concept of module in jsdoc doesn't imply there's an object where all the functions belongs, it is just code organization: http://usejsdoc.org/tags-module.html. It says "All symbols in the file are assumed to be members of the module" but not that a module is a JS object.

Second, how the documentation is organized right now is my own decision (because I decided to split it in modules). I think it helps to have the functions grouped by category (module), but we can make the jsdoc output just a list of functions by removing the "@memberof" tag from the jsdoc comments. In this way, I think is clear the non-hierachy relation of functions, but it looses the category organization. If you prefer, I can try this way.

Anyway, If you decided to go back to the older documentation, here is a list of undocumented ugens that would be nice to have into the main docs.md file:

• attack
• conditional
• decay
• delta
• env
• memo
• mix
• mstosamps
• mtof
• pan
• prop
• rate
• sah

Cheers, Dani

[charlieroberts]

Interesting. I guess I disagree... I think JSDoc is assuming a "module" is file with an export. "When an exported symbol is defined as a member of module.exports, exports, or this, JSDoc infers that the symbol is a static member of the module." In genish everything gets exported as module.exports, so it is making that assumption.

delta, rate -> filter env, attack, decay -> envelope mix, sah -> routing mstosamps, mtof, memo, pan -> utilities

I think "prop" is now deprecated, but need to go through the examples and make sure. I'll create an issue to add these to the docs.

[danigb]

Hi @charlieroberts,

I've removed the @module tag from the jsdoc and generate a flat result. You can take a look to the result here: https://danigb.github.io/genish.js/api/

This is the best I can get with jsdoc (remember the html output is using a template you can change at any time. Now it uses https://github.com/postmanlabs/postman-jsdoc-theme but they are a lot in github). If still is not good to you, I think we can close this PR and continue with other more productive stuff ;-)

I've also merged the latests changes from master.

Saludos, Dani