[INVESTIGATE] jsdoc vs yuidoc about js-buy-sdk

[mcpatten]

I'll tag you guys on an upcoming PR so you can see what we're doing on Themes.

We're currently using jsdoc3 in Slate (theme dev framework). Some of the pro's Ive found so far:

• unlike jsdoc(2) it's npm/node specific and written 100% in javascript
• yuidoc is a "superset of jsdoc"... but it's a superset of jsdoc2, and it still uses a number of outdated dependencies. jsdoc3 improves upon a lot of stuff that's not included in yuidoc.
• it's less verbose in-code than yuidoc (marginal, both solutions require a lot of markup).
• The syntax is a bit more flexible & js-specific (yuidoc feels like it was written for classical OO).
• it works inside my IDE, cross linking functions w/tags etc. (yuidoc relies on handlebars helpers)
• it parses code, so you don't need to provide all the tags if your code clarifies them (but it is still flexible so if you do provide tags that differ from your code it will document accordingly).
• we found a pretty good template that gives us similar functionality to the yuidoc template, but we were also able to generate raw json, giving us a lot of flexibility in the future to create our own reusable/generic template with jsdoc data that could be used across Shopify without worrying about working under a less-than-ideal templating paradigm.

The only major con that I've found (and this is true for yuidoc too, although it's slightly worse with jsdoc) is that, ironically, the documentation is quite poor and it takes a while to figure out how to use it. Having code examples seem to be the best way to understand jsdoc, and there are very few robust examples provided in the documentation.

[minasmart]

it's less verbose in-code than yuidoc (marginal, both solutions require a lot of markup).

I don't know that this is an advantage. It can lead you to change things like function signatures, without having docs to update, making an API change less apparent.

The syntax is a bit more flexible & js-specific (yuidoc feels like it was written for classical OO).

Yuidoc actually supports any language that uses /* ... */ style comments. It doesn't walk your code.

it parses code, so you don't need to provide all the tags if your code clarifies them (but it is still flexible so if you do provide tags that differ from your code it will document accordingly).

So with that, one question: how is jsdoc at inferring what a thing is by reading your code? Do you find yourself fighting it a lot, or is it actually pretty intuitive in a good way? I'm a little concerned that this makes it really easy to change your API without really noticing. Explicit documentation serves as a contract between you and whoever uses your API. When things don't match up it gives us a really easy way of saying "Oh. We broke the spec" vs "I don't know when that changed". What are your thoughts?

[mcpatten]

I meant to reply to this, and still do but I've been rediculously busy over the past week. Will get back to you guys soon :)

[minasmart]

I'm going to close this for now. Feel free to reopen if you have something to add @m-ux and @tessalt