OED Code Documentation Expectations

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) {