Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

build-docs

Package Overview
Dependencies
Maintainers
5
Versions
17
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

build-docs

Library to extract inline comments out of your services

  • 2.2.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
120
increased by60%
Maintainers
5
Weekly downloads
 
Created
Source

build-docs

CircleCI

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 = `
/*
 * 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 parse
  • name is the name of the action

The object returned is an object 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
  • errors - an object of all the possible errors from this action - docs
  • returns - an object describing the return type - docs

const 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 folder

This 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
 */

Credits

Dom Harrington

FAQs

Package last updated on 12 Jan 2018

Did you know?

Socket

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.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc