We appreciate documentation contributions, especially if they follow the common format. We acknowledge that these suggestions are far from complete and welcome input from developers.
Each file should begin with a short summary of its contents; for instance:
/* This file contains the React component which lists and allows * selections of pairs of {id, name}, e.g. for groups and meters * in the chart UI. */
Every function should have JSDoc comments, beginning with /**
, which should include the
@param
and @return
tags to describe parameters and functions.
In TypeScript code, it's unnecessary to declare types for @param
tags.
/** * Converts pairs of timestamps into an array of TimeIntervals. * @param tspairs {[[number, number]]} the pairs of timestamps to be processed * @returns {[TimeInterval]} */ function tspairsToTimeIntervals(tspairs) {
Do your best to use full English sentences. For example, the following could be rewritten:
/** * Middleware function to force authentication * Requires a route to have a valid token or 401 */ async function authenticate(req, res, next) {
as the more readable:
/** * This middleware function forces requests to provide a valid * token. Requests without a valid token will reject with a 401. */ async function authenticate(req, res, next) {