Package Exports

build-docs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (build-docs) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

build-docs

Library to extract inline comments out of your services

Installation

With npm:

npm install build-docs --save

With yarn:

yarn add build-docs

Usage

const buildDocs = require('build-docs');

const source = `
/*
 * createUser: Creates a user in the database
 *
 * This creates a user in the database. Here you can add a
 * full description.
 *
 * @param {string} name Name of the user
 * @secret apiKey This is a secret value that will be required
 * @throws {ValidationError} Must provide all required fields
 * @returns {Object} The created user object
 */`;

console.log(require('util').inspect(buildDocs(source), { depth: null })); // eslint-disable-line no-console
// [ { name: 'createUser',
//     description: 'Creates a user in the database',
//     fullDescription: 'This creates a user in the database. Here you can add a full description.',
//     params:
//      [ { title: 'name',
//          description: 'Name of the user',
//          type: 'string' } ],
//     throws:
//      [ { type: 'ValidationError',
//          description: 'Must provide all required fields' } ],
//     secrets:
//      [ { key: 'apiKey',
//          description: 'This is a secret value that will be required' } ],
//     returns: { description: 'The created user object', type: 'object' } } ]

`const docs = buildDocs(source)`

source is a string of source code with comments to parse

The object returned is an array of objects with the following properties:

name - the name of the action - docs
description - the description of the action - docs
fullDescription - a longer description of the action which can be multiline - docs
params - an array of the @param comment types - docs
secrets - an array of the @secret comment types - docs
throws - an array of the @throws comment types - docs

`name`

The name can be written in 2 different forms:

As a string before your description:

/*
 * name: function description
 */

Or using the @name block tag:

/*
 * @name name
 */

`description`

Description is written as the first line of text in your block comment

/*
 * Function description
 */

`fullDescription`

Full description is written as 2nd first line of text in your block comment

/*
 * Normal description
 *
 * This part becomes the full description
 * and it can be on multiple lines
 */

`@param`

We support the same syntax as jsdoc. We parse your format and output a valid JSON Schema for each @param.

Primitive types:

/*
 * @param {string} name Name of the user
 * @param {number} age Age of the user
 */

`@secret`

If your service requires secret values from your users, this is how you request and access them.

/*
 * @secret key Description of the secret
 */

`@throws`

We support the same syntax as jsdoc.

/*
 * @throws free form error description
 * @throws {ErrorType} free form error description
 * @throws {JustAnErrorType}
 */

`@returns`

We support the same syntax as jsdoc.

/*
 * @returns {string} Name of the user
 */

Credits

Dom Harrington