Writing Documentation

Documentation is very important in making sure that a user can figure out how to use your service. It is really easy to write documentation by entering comments at the top of your endpoint file. This will generate documentation on readme.build as well as let Build know more information about each of your endpoints.

Format

/*
* Description
*
* Longform description
* 
* @param {type} name - Description
* @throws {error_type} Message
* @returns {type} Description
*/

Types

The following types are supported for both @param and @returns

• number
• string
• boolean

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

Arrays

Arrays are specified by succeeding the type with [], so string[] is an array of strings.

Example Data

To specify example data in the documentation, add an equal sign after the parameter name. Without explicit example data, we use json-schema-faker to fill in the code samples.

/*
* @param {string} name="Marc Cuva" Name of the user
* @param {number} age=12 Age of the user
*/

Errors

When documenting an error in the comments, you get some nice benefits from api.error. After defining an error, you are able to reference that error in your code, and an error object will be created using what you entered in the comments.

For example:

/*
  Demos the error
  
  This will return an error with the data passed in.
  
  @param {number} number - Passed in number
  @throws {demoError} You passed in ${x}
*/
api.create('error', (data, api) => {
  api.error('demoError', {x: data.number});
});

If api('service').do('error', { number: 10 }) was called, an error would be returned in the following format.

{ 
  error: 'You passed in 10',
  code: 'demoError',
  data: { 
    handled: true,
    arguments: { number: 10 }, 
    version: '1.0.0' 
  }
}

The error message from the comments is returned, and it can be a template string that is replaced with data at runtime.

However, all of the following error formats are also supported:
api.error('demoError');
api.error('Error message not in comments');
api.error(new Error('an error occurred));`