@seneca/doc

Documentation helper for Seneca plugins.

Usage no npm install needed!

<script type="module">
  import senecaDoc from 'https://cdn.skypack.dev/@seneca/doc';
</script>

README

seneca-doc

Npm Travis Coveralls Maintainability

Documentation helper for Seneca plugins.

Install

$ npm install @seneca/doc -D

Add to your package.json:

{
  "scripts": {
    "seneca-doc": "seneca-doc"
  }
}

And run with

$ npm run seneca-doc

Usage

This utility plugin updates the README.md file in a Seneca plugin repository with auto-generated documentation. Special HTML comment markers are used to indicate the insertion point, and all markdown within these markers is replaced.

  • <!--START:action-list--> ... <!--END:action-list-->
    • Inserts a list of action patterns defined by the plugin
  • <!--START:action-desc--> ... <!--END:action-desc-->
    • Inserts more detailed action descriptions (linked to by action-list)

In the top level folder of your project, create a module called plugin-doc.js where plugin is the name of your plugin. This should return an object whose keys are the names of the action functions in your plugin. Each key should define an action description with properties as defined below. For an example, see doc-doc.js which defines the documentation for this plugin.

Alternatively, return the same data structure from your plugin definition under the doc property.

The export doc/generating will be true if documentation is being generated. You can use this handle cases where your plugin has additional dependencies that fail when it is loaded direcly by seneca-doc.

See the unit tests for examples of usage.

NOTE: Plugins must be loaded via seneca.use() for validation to activate (as well as depending on a validation plugin such as as seneca-joi). In particular, when testing, ensure that the plugin under test is loaded with seneca.use('..') (assuming tests are within a test subfolder).

NOTE: must be loaded before seneca-joi so that the rules are available to seneca-joi.

Arguments

The seneca-doc command takes the following command line arguments:

  • -p - fully qualified plugin name (can be used for multiple plugins) that is needed by the plugin definition function. Example:
    seneca-doc -p seneca-entity -p @seneca/graph -p @seneca/owner

Supported documentation properties

The following properties can be optionally attached to the action function of a given message:

  • desc: String describing the action.
  • examples: An object, where the keys are example paramers, and the values are description strings.
  • validate: The validation object supported by seneca-joi.
  • reply: A literal object showing the reply object structure.

See the source of seneca-doc.js itself for a good example of using these.

NOTE: plugin options are not currently supported - that would make a great pull request! :)

The Action Patterns and Action Descriptions sections below are examples of the generated output, run on the seneca-doc plugin itself.

Options

  • test : boolean false

Set plugin options when loading with:



seneca.use('doc', { name: value, ... })

Note: foo.bar in the list above means { foo: { bar: ... } }

Action Patterns

Action Descriptions

« sys:doc,describe:pin »

Provide introspection data for actions matching a pin (a sub pattern).

Examples

  • sys:doc,describe:pin,pin:"a:1,b:2"
    • Describe actions matching at least a:1,b:2.

Parameters

  • pin : alternatives " " : The pin sub pattern in string or object format.

Replies With

{
  pin: 'pin parameter',
  actions: [
    '{ Seneca action definition }'
  ]
}

« sys:doc,describe:plugin »

Provide introspection data for a plugin and its actions.

Examples

  • sys:doc,describe:plugin,plugin:entity

    • Describe the seneca-entity plugin.

  • sys:doc,describe:plugin,plugin:entity$foo

    • Describe the seneca-entity plugin instance with tag foo.

Parameters

  • plugin : string " " : The full name of the plugin (if tagged, use the form name$tag).

Replies With

{
  plugin: 'plugin parameter',
  actions: [
    '{ Seneca action definition }'
  ]
}