Kill JSDoc?

[dreeves]

Pros for JSDoc

1. It magically turns all the comments in the source code into pretty, hyperlinked documentation
2. Uluc worked hard to set it all up
3. The output gives you a nice list of member methods for classes, which is a bit hard to extract from js source unlike C++ and such

Cons for JSDoc

1. It makes the comments in the code slightly uglier
2. It makes the README when viewed in GitHub slightly uglier
3. We never trust it and in practice just look at the code directly since that's the ground truth
4. At least for all the bgraph properties, the descriptions are not adjacent to the code so that's particularly doomed to get out of sync. (Also the comments that are are adjacent to the code have JSDoc syntax but aren't actually picked up by JSDoc so we need to clean that up / DRY things up if we do keep JSDoc.)

Action items if we kill JSDoc

• [ ] Convert things including tutorials/*.md to wikis here in the repo.

Action items if we keep JSDoc

• [ ] DRY up comments / documentation for things including bgraph properties

[dreeves]

If we killed JSDoc we'd need to be careful not to lose any documentation, especially the stuff in Tutorials, where Uluc tended to put things that didn't relate to one specific piece of code.

Maybe things like tutorials/*.md could be converted to wikis here in the repo? I'd be happy to do that as part of the price of killing jsdoc if jsdoc bugged me enough to be serious about killing it.

There's also one more open question about the value of that @param syntax if we ever wanted to migrate to typescript.