Switch to JSDoc instead of emu/markdown

[mtraynham]

This is just a suggestion, as there isn't really anything wrong with emu/markdown...except that it's just a bit hack-y.

JSDoc is pretty much the defacto standard for Javascript Documentation generation. If we still need to export to Markdown, it has a plugin to do so.

Comparison of other 3rd party documentation generators.
http://blog.fusioncharts.com/2013/12/jsdoc-vs-yuidoc-vs-doxx-vs-docco-choosing-a-javascript-documentation-generator/

Would be a fairly large undertaking to do, but likely more tedious than complex.

[gordonwoodhull]

Yeah, for example we get screwups like #954.

I've been getting annoyed at the docs for a couple reasons:

• The HTML formatting is quite basic. (I usually look at the rendered markdown, but when I see the HTML I get sad.)
• It doesn't generate links to the anchors like e.g. the d3 docs have, which makes it difficult to give help when using a mobile device.

I guess it would be a lot of tedious search and replace and macro action to port to JSDoc, but it might be worth it.

[mtraynham]

We could do a trial run on a single file, then if we like it, I have no issue with divvying up the work :) We don't really annotate the "types" of parameters, so I imagine that would be the largest part.

[mtraynham]

Also would we want to target this undertaking at 'develop' or 'master'?

[gordonwoodhull]

I think we can go ahead with it on master. 2.0 will live for a while, and it shouldn't be too difficult to merge the changes into develop, since it's just comments.

I think this may actually be a lot of work, because of documenting each parameter, optional parameters, etc. etc. I would guess almost a week of work total.

It also looks like JSDoc might be pretty picky about how you structure your code. So we'd definitely want to try it on a more complex file to make sure it works with our code.

Probably @jrideout went with the simple strategy of copying and pasting the existing markdown documentation into comments and using emu because of these complications.

[gordonwoodhull]

Fixed in #978 & #994, 2.0 beta 18