Security News
Weekly Downloads Now Available in npm Package Search Results
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
build-docs
Advanced tools
Library to extract inline comments out of your services
With npm:
npm install build-docs --save
With yarn:
yarn add build-docs
const buildDocs = require('build-docs');
const source = `
/*
* 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, 'createUser'), { depth: null }));
// { 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 doc = require('build-docs')(source, name)
source
is a string of source code with comments to parsename
is the name of the actionThe object returned is an object with the following properties:
name
- the name of the action - docsdescription
- the description of the action - docsfullDescription
- a longer description of the action which can be multiline - docsparams
- an array of the @param
comment types - docssecrets
- an array of the @secret
comment types - docsthrows
- an array of the @throws
comment types - docserrors
- an object of all the possible errors from this action - docsreturns
- an object describing the return type - docsconst docs = require('build-docs').parseDirectory(directory)
There is also a function to make build-docs look inside a directory and parse docs out of all JS files in that directory. This uses the filename (minus the extension) for the name of the action.
directory
is the folderThis returns an array of docs in the same format as described above.
name
The name is taken directly from the name you pass in
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}
*/
errors
For the following docs:
/*
* @throws {ErrorType} free form error description
*/
This will return an errors object like the following:
{
ErrorType: function () {}
}
The function is a compiled lodash template: https://lodash.com/docs/4.17.4#template
@returns
We support the same syntax as jsdoc.
/*
* @returns {string} Name of the user
*/
FAQs
Library to extract inline comments out of your services
The npm package build-docs receives a total of 48 weekly downloads. As such, build-docs popularity was classified as not popular.
We found that build-docs demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.