.README.md

{"gitdown": "contents"}

Purpose

With this plugin, you write your examples as plain javascript, and then include them

• in your jsdoc documentation with the @examples tag, and
• in your test suites with a simple test file.

You'll need to be familiar with JSDoc, and with a testing framework such as jest, jasmine, or mocha (or any other framework that can supply globals for describe, expect, and it that work in the usual way).

Here's a look at the end result

Installation

npm install --save-dev jsdoc-examples

Note that the example directory contains a complete usage example for the plugin for both documentation, and for testing in each of the three test frameworks mentioned above.

Usage option 1: all examples for a module in a single file

All of the examples for a module may be placed in a single file. The examples object contains entries for each function that you wish to include examples for in your documentation and tests. Optionally, a setup function can be specified. The setup code will be added to the top level module documentation, and will be called before each example when tests are run.

Each item in the examples object is itself an array of specifications corresponding to the examples you wish to document/test for a particular function. Each object has a key for the example code, and optionally, an expect key whose value is the expected result of running the example. There is no need to include the expect entry if the example does not return a result.

The examples file must export a single function named f, which takes an instance of the module as its sole argument. If no setup is required, f may return the examples array directly. If setup code is required, f must return an object with the form {examples: examples, setup: setup}. The export must be of the form module.exports =, even if your project uses es6 modules. This example provides more details:

{"gitdown": "include", "file": "./example/test/data/examples/core-examples.js"}

In order to include the examples in your documentation, simply add an @examples tag containing the path to your examples in the top-level module documentation, as shown here:

{"gitdown": "include", "file": "./example/src/core.js"}

To include the examples in your testing, create a .test.js file that uses this plugin's testAll to run the tests, as in this example:

{"gitdown": "include", "file": "./example/test/examples.test.js"}

Usage option 2: examples for each function in a separate file

Alternatively, separate examples files can be used to document a module's functions. To use this method for a module, create a directory for the examples files. Then, for each function, add a file (named for the function) to contain the examples for that function. The format of these files is similar to the one above, but here, there is no need to tag the example with the function name. So, examples is now just the array of specifications described above. As above, each file may include a setup function, and must export the function f. Here's an example with more details:

{"gitdown": "include", "file": "./example/test/data/examples/Foo/Foo.js"}

In order to include the examples in your documentation, simply add an @examples tag containing the path to your examples directory in the top-level module documentation, as shown here:

{"gitdown": "include", "file": "./example/src/Foo.js"}

As for option 1, to include the examples in your testing, create a .test.js file that uses this plugin's testAll to run the tests.