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
*
* @param {string} name Name of the user
* @throws {ValidationError} Must provide all required fields
* @returns {Object} The created user object
*/`;
console.log(require('util').inspect(buildDocs(source), { depth: null }));
// [ { name: 'createUser',
// description: 'Creates a user in the database',
// params:
// [ { title: 'name',
// description: 'Name of the user',
// type: 'string' } ],
// throws:
// [ { type: 'ValidationError',
// description: 'Must provide all required fields' } ],
// returns: { description: 'user 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 - docsdescription
- the description of the action - docsparams
- an array of the@param
comment types - docsthrows
- 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
*/
@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
*/
Arrays:
/*
* @param {string[]} interests Interests of the user
*/
Objects with nested properties:
/*
* @param {Object} address Address of the user
* @param {string} address.street Street of the user
* @param {string} address.city City of the user
* @param {string} address.state State of the user
* @param {string} address.zip Zip code of the user
*/
Arrays of objects with nested properties
/*
* @param {Object[]} favouriteFoods Favourite foods of the user
* @param {string} favouriteFoods[].cuisine Name of the cuisine
* @param {string} favouriteFoods[].dish Favourite dish
*/
@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
*/