reaction-jsdoc

requirements

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

how to build and test docs

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 it broke: jsdoc . --verbose --configure .reaction/jsdoc/jsdoc.json

how to write docs

document a method

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

other things:

• @ignore - if you don't want the function to output docs
• Lowercase type names, like object, string

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}
 */

/**
 * @method createReactionProductFromShopifyProduct
 * @summary Transforms a Shopify product into a Reaction product.
 * @private
 * @param  {object} options Options object 
 * @param  {object} options.shopifyProduct the Shopify product object
 * @param  {string} options.shopId The shopId we're importing for
 * @param  {[string]} options.hashtags An array of hashtags that should be attached to this product.
 * @return {object} An object that fits the `Product` schema
 *
 * @todo consider abstracting private Shopify import helpers into a helpers file
 */

document a React components

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} columnMetadata provides filtered columns with i18n headers
  * @property {Array} data provides array of objects to be used in place of publication data
  * @property {Number} defaultPageSize how many results per page
  * @property {Boolean} filterType filter by table, column, or both
  * @property {Array} filteredFields provides filtered columns, use columnMetadata instead
  * @property {Boolean} isFilterable show / hide column filter
  * @property {Boolean} isResizeable allow resizing of table columns
  * @property {Boolean} isSortable allow column sorting
  * @property {String} matchingResultsCount provides Count publication to get count from
  * @property {Number} minRows minimum amount of rows to display in table
  * @property {String} noDataMessage text to display when no data is available
  * @property {Function} onRowClick provides function / action when clicking on row
  * @property {String} publication provides publication to get Meteor data from
  * @property {object} query provides query for publication filtering
  * @property {Array} selectedRows provides selected rows in the table
  * @property {Function} transform transform of collection for grid results
  * @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:

A deprecated method:

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/master/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

More on documenting classes from JSDoc: http://usejsdoc.org/howto-es2015-classes.html