Edit

JSDoc Style Guide

Requirements

The Core API Documentation uses JSDoc and a custom version of docdash theme to build its static API docs site.

Running API docs locally

1. Add JSDoc tags to your code
2. Run npm run docs
3. Open file:///tmp/reaction-docs/index.html in your browser.

ProTip: Did you get an error? Run the command in verbose mode to see where the documentation parsing failed: jsdoc . --verbose --configure .reaction/jsdoc/jsdoc.json

Documenting methods

The basics

Document a function by adding comments above the function definition with the following tags:

required

• @method name
• @summary can use Markdown here
• @param {type} name description, use [] square brackets around param for optional params
• @return {type} name description, or @return {undefined}

optional

• @async
• @private
• @default
• @deprecated - since version number
• @since - version number
• @todo - any TODO notes here
• @ignore - if you don't want the function to output docs
• @author - to indicate third-party method authors
• @see - link to relevant third-party documentation

Example of a method

Basic example:

/**
 * quantityProcessing
 * @method
 * @summary perform calculations admissibility of adding product to cart
 * @param {object} product - product to add to Cart
 * @param {number} itemQty - qty to add to cart, defaults to 1, deducts from inventory
 * @since 1.10.1
 * @return {number} quantity - revised quantity to be added to cart
 */

More examples:

/**
 * @method connectors/shopify/webhooks/create
 * @summary Meteor method for creating a shopify webhook for the active shop
 * @async
 * @param {object} options Options object
 * @param {string} options.topic - the shopify topic to subscribe to
 * @param {string} [options.absoluteUrl] - Url to send webhook requests - should only be used in development mode
 * @return {undefined}
 */

Document a React component

1. Add a @module declaration at the top of the file, under imports:

/**
 * @file SortableTable is a React Component wrapper around {@link https://react-table.js.org} ReactTable. Anything functionality from ReactTable should be available in SortableTable out of the box, but may require styling. For more, see {@link https://react-table.js.org/#/story/readme ReactTable docs}
 *
 * @module SortableTable
 * @extends Component
 */

2. Document each method with @property and @param tags:

/**
  * renderComponent
  * @method
  * @summary React component for displaying a not-found view
  * @param {Object} props - React PropTypes
  * @property {String|Object} className - String className or `classnames` compatible object for the base wrapper
  * @property {String|Object} contentClassName - String className or `classnames` compatible object for the content wrapper
  * @property {String} i18nKeyMessage - i18n key for message
  * @return {Node} React node containing not-found view
  */

3. Document propTypes at the bottom, before the propTypes declaration using @property tags:

/**
  * @name SortableTable propTypes
  * @type {propTypes}
  * @param {Object} props - React PropTypes
  * @property {Object} collection collection to get data from
  * @property {Array} data provides array of objects to be used in place of publication data
  * @property {Number} defaultPageSize how many results per page
  * @return {Array} React propTypes
  */

Document a one-file module

1. Add a @module declaration at the top:

/**
 * Reaction transform methods on Collections
 * @file Use transform methods to return Cart and Order calculated values: count, subTotal, shipping, taxes, total. Use these methods on Cart and Orders in templates, `{{cart.getCount}}` and also in code, `Cart.findOne().getTotal()`. These are calculated by using a Mongo Collection's {@link http://docs.meteor.com/api/collections.html#Mongo-Collection transform functionality}.
 * @module cartOrderTransform
 */

2. Document each method. The sidebar and page:

Document a core Schema

1. Add a @namespace schemas declaration at the top:

/**
 * @file Reaction Core schemas
 * Reaction uses {@link https://github.com/aldeed/meteor-simple-schema SimpleSchema} to apply basic content and structure validation to Collections. See {@link https://docs.reactioncommerce.com/reaction-docs/trunk/simple-schema full documentation}.
 * @namespace schemas
 */

2. Document the Schema using @name SchemaName, @type {SimpleSchema} and @property like this:

/**
 * @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({

Document a Schema in a plugin

1. Use @nameSchemaName, @type {SimpleSchema} along with @memberof schemas:

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

Document Meteor methods, grouped together as a @namespace

1. In one file: Create @namespace at the top of the file. A namespace only needs to be declared once across the whole repository:

/**
 * @file Meteor methods for Accounts
 * Reaction extends {@link https://github.com/meteor/meteor/tree/master/packages/accounts-base MeteorAccounts} with Reaction-specific behavior and user interaction.
 * @namespace Meteor/Accounts
 */

2. In all methods: Above the method, add, @memberof NameOfNamespace, along with all the standard method tags.

/**
 * @name NameOfMethod
 * @method
 * @memberof NameOfNamespace
 * @summary Method summary goes here
 * @params {Object} shop - current shop
 * @returns {Object} shop - new shop
 */

Document a third-party packages

1. When incorporating methods from a third-party package, use the @author tag to indicate the author.
2. Use the @see tag to link to relevant documentation.

/**
 * @name Hook
 * @method
 * @author Workpop
 * @see https://github.com/Workpop/meteor-method-hooks
 */