Consider migrating to JSDoc 3

[toolness]

@islemaster mentioned this in https://github.com/molleindustria/p5.play/issues/57#issuecomment-203142789 so I thought it might be useful to start a discussion about it here.

JSDoc 3 pros:

• Better tooling? (@islemaster can you be more specific about this?)

JSDoc 3 cons:

• Since we're not currently using it, there may be some work involved in getting our current docs to work with it. @islemaster mentioned that the syntax is really similar though, so it probably won't be much work.
• Default theme doesn't look like p5.js branding at all. This is ultimately @molleindustria's call I think, but I personally feel this is pretty important. If there are lots of compelling reasons to switch to JSDoc 3, I'm interested in writing a custom theme that conforms to the style of p5.js core.

YUIDoc pros:

• It's what we're currently using, so there's no extra effort involved in sticking with it, really.
• It's what p5.js core uses, so it lowers the barrier for p5.js contributors. I don't think there is specific code or theme-ing we can necessarily lift directly from its repository, though.

YUIDoc cons:

• Inability to treat specific methods/properties as private, and therefore hidden. This is actually a problem with our particular YUIDoc theme, I think, but I could be wrong. But basically, we can only treat entire classes or modules as private--and therefore remove them from default docs view--but not individual methods/properties.
• Broken cross-links to other parts of the documentation. Again, this seems to be a problem with our theme rather than YUIDoc itself, but I could be wrong. Filed as crossLink entries don't seem to link to the proper anchor kevinlacotaco/yuidoc-bootstrap-theme#24.
• In general I feel like YUIDoc has a lot of "paper cuts"--minor bugs or lack of helpful features that make writing docs a bit harder than I think it could ideally be. For example, in Fix errors in Sprite docs. #72 I fixed a problem with a duplicate parameter name and another one with an empty method name, but it would've been nice if YUIDoc had actually reported these problems, rather than requiring me to manually find them myself.

[islemaster]

Neither package is a slouch, but by the numbers JSDoc3 is roughly 3-4x as popular, and may be more stable.

	YUIDoc (npm)	JSDoc3 (npm)
Stable version	0.10.0 (16 Jan 2016)	3.4.0 (17 Nov 2015)
Github Stars	727	4,434
NPM Downloads last month	53,947	186,139
Contributors in the last year	6	16

As for tools, both provide their own generator, but JSDoc supports plugins and has been wrapped and extended by tools like jsdox and jsdoc-to-markdown, and JSDoc tags are consumed by competing (possibly better) tools like documentationjs and Dokker.

Google Closure Compiler's type annotations are derived from JSDoc.

Editor support for JSDoc is superior too. Visual Studio and the Jetbrains family of editors now natively understand JSDoc tags. Sublime Text and Atom get support through the docblockr plugin (among others), and vim has plugin jsdoc.vim. I can't find any of this for YUIDoc.

The syntax is remarkably similar, to the point that you could probably run a JSDoc generator against p5.play's source as-is and 90% of it would work out of the box. The biggest syntax difference is that in JSDoc you can omit the @method name tag, because it actually parses the object you're documenting and can usually infer a name and type.

As you've pointed out, the major detriment to switching is how the look and feel of our docs would diverge from p5.js. I'm not sure how much work it would be to port that theme to a jsdoc tool.

Finally, this comparison from 2013 is somewhat out of date but does give a good overview of some of the differences between the documentation engines. Some of their accessibility concerns with JSDoc have been addressed by good plugins and templates since then.

[islemaster]

It looks like the benefit of switching isn't great enough to be decisive 😀. Closing this issue since it doesn't document a 'must fix' issue - and it'll still be around for reference purposes if we want to revisit this.