@option module

Describes a property of the object, or an argument of the function, that was specified in an @param tag.

@option {TYPE} NAME [DESCRIPTION]

Here's an example of some ways you can use the @option tag:

/**
 * @module {{}} ledger Ledger
 */
module.exports = {
  /**
   * Retrieves a list of orders.
   *
   * @param {{}} params A parameter object with the following options:
   *   @option {String} type Specifies the type of order.
   *   @option {Number} [createdAt] Retrieves orders after this timestamp.
   *
   * @param {function(Orders.List)} [success(orders)] Callback function.
   *   @option orders A list of [Orders] that match `params`.
   */
  find: function(params, success) { /*...*/ }
};

Parameters

  1. TYPE {TYPE-EXPRESSION}:

    A type expression. Examples:

    {String} - type is a String. {function(name)} - type is a function that takes one name argument.

    TYPE does not need to be specified for types that are already described in the @option's corresponding function or object.

    For example, notice how there is no need to specify {String}:

    /**
 * @param {{type: String}} params An object with the following options:
 *   @option kind Specifies the kind of order.
 *   @option label Retrieves only orders with this label.
 */
  2. NAME {NAME-EXPRESSION}:

    A name expression. Examples:

    • age: age is item.
    • [age]: age is item, age is optional.
    • [age=0]: age defaults to 0.
  3. DESCRIPTION {Markdown}:

    Markdown content that continues for multiple lines.

However, omitting TYPE might confuse your team members, so we recommend being explicit and always specifying TYPE for @option.

Usage Examples

/**
 * @module {{}} foo Foo
 */
module.exports = {
  /**
   * A function named bar.
   *
   * @param {{}} params A parameter object with options:
   *   @option {String} aString An arbitrary string.
   *   @option {Number} [oNumber] An optional number.
   */
  bar: function(params) { /*...*/ }
};

Resulting DocObject:

{
  "description": "A function named bar.\n",
  "name": "foo.bar",
  "params": [
    {
      "description": "A parameter object with options:",
      "name": "params",
      "types": [
        {
          "options": [
            {
              "description": "An arbitrary string.",
              "name": "aString",
              "types": [
                {
                  "type": "String"
                }
              ]
            },
            {
              "description": "An optional number.\n",
              "name": "oNumber",
              "optional": true,
              "types": [
                {
                  "type": "Number"
                }
              ]
            }
          ],
          "type": "Object"
        }
      ]
    }
  ],
  "parent": "foo",
  "type": "function"
}

That DocObject an be used in a template like this:

{{#if params}}
  {{#params}}
    {{#types}}
      {{#if options.length}}
        {{#options}}
          <p>
            Option Name: {{name}}
            <br/>
            Option Description: {{description}}
          </p>
        {{/options}}
      {{/if}}
    {{/types}}
  {{/params}}
{{/if}}

See bit-docs-js/templates/signature.mustache for a more complex template that uses the DocObject resulting from @option.