jsdoc: document all top-level schemas

[machikoyasuda]

What this PR does:

1. Adds a @typedef for the SimpleSchema class. This does not need to be defined anywhere else.
2. Adds examples of how to document SimpleSchema classes in Core (e.g. TaxSettings, Profile, Email...)
3. Adds examples of how to document SimpleSchema classes in plugins, using the connectors-shopify as an example.
4. Adds all the top level schemas

How that renders:

1. The Type Definition: Anytime someone adds {SimpleSchema}, it will create a link to here:
   

2. Core schemas and schema helper methods in the sidebar:
   

3. Core schemas defined, all on one Schema page: The SimpleSchema will link to Type Definition from 1.
   

4. Schema helper methods at the bottom of the Schema page:
   

5. Package schemas defined in its own package page, example: connectors-shopify:
   

How to do it:

• To document a schema in a plugin, use @type {SimpleSchema}

/**
 * @name Webhook
 * @type {SimpleSchema}
 * @property {Number} shopifyId required, Shopify webhook ID
 * @property {String[]} integrations required, Array of integration strings using this webhook
 * @property {Boolean} invited optional
 */
 const Webhook = new SimpleSchema({

• To document a core schema, use @type {SimpleSchema} along with @memberof schemas

/**
 * @name TaxSettings
 * @memberof schemas
 * @type {SimpleSchema}
 * @property {String} exemptionNo optional
 * @property {String} customerUsageType optional
 */

💡 ProTip: Specify an Array of Strings with this syntax: {String[]}. ⚠️ {[String]} will break!

[machikoyasuda]

@aaronjudd Here's a stab at creating a template for documenting Schemas.

@spencern Added you as a reviewer so you can look at how I documented Schemas in the connectors-shopify package.

[spencern]

This looks good to me. I like that you're finding ways to organize Schemas together like this, feels like a straightforward and clean way to do this.

Only question that I've got so far is how could we link schemas that are connected when a property for a schema is a the other schema's type

[spencern]

For properties that are arrays of other schemas, is there a good way to link to the other schema from the description of this property?

[machikoyasuda]

This is possible!

Looks like this in the code:
* @property {Metafield[]} metafields optional

Rendered:

And if jsdoc finds a Metafield symbol, it will link to the symbol accordingly.

So that line could be rewritten like:
* @property {Webhooks[]} webhooks Array of registered Shopify webhooks

and that will link to the Webhooks Schema

[machikoyasuda]

The less automagical way to link from one symbol to another in the code is like this:

@see {@link foo} for further information.

http://usejsdoc.org/tags-see.html

[spencern]

the automagical way is pretty cool

[machikoyasuda]

WIP - Will have this done by end of day.

[machikoyasuda]

Updated + finished documenting all top-level schemas.

[machikoyasuda]

updated screenshot with all the schemas!

[aaronjudd]

This is pretty sweet!
I did notice a , after many of the properties in the schema.

[aaronjudd]

Will wait a bit to see if there is a fix for the commas, but ok with merging anytime.

[machikoyasuda]

@aaronjudd Fixes all the ,s and adds some schemas I forgot... most importantly Shops!