Show state in docs

[josephjclark]

This PR enables a table of state mutations to be shown in the JSDoc for an adaptor.

This makes it easier to understand how an operation manipulates state.

Issues

Closes #602

How it works

In an adaptor's JSDoc, just add @state annotations to describe every property of state that is modified by that operation:

/**
 * Make a GET request
 * @param {string} path - Path to resource
 * @param {RequestOptions} params - Query, Headers and Authentication parameters
 * @param {function} callback - (Optional) Callback function
 * @state data - the response body will be written to state.data
 * @state response - the response from the HTTP server, including headers, statusCode, body, etc
 * @state references - the last response, without the body, will be pushed to references
 * @returns {Operation}
 */
export function get(path, params, callback) {
  return sendRequest('GET', path, params, callback);
}

You can also reference an object as a TypeDef, enabling re-usable definitions:

/**
 * Make a GET request
 * @param {string} path - Path to resource
 * @param {RequestOptions} params - Query, Headers and Authentication parameters
 * @param {function} callback - (Optional) Callback function
 * @state HttpState
 * @returns {Operation}
 */
export function get(path, params, callback) {
  return sendRequest('GET', path, params, callback);
}

Each @state key acts a bit like a mixin. Properties will override each other and the last to be applied will win. So you could go crazy and do something like this:

/**
 * Make a GET request
 * @param {string} path - Path to resource
 * @param {RequestOptions} params - Query, Headers and Authentication parameters
 * @param {function} callback - (Optional) Callback function
 * @state BaseState
 * @state HttpState
 * @state data - the GET response body will be written to state.data
 * @returns {Operation}
 */
export function get(path, params, callback) {
  return sendRequest('GET', path, params, callback);
}

Neat.

Defaults

As a final note, you can also do @state data or @state refereces and just set the name - in which case a default string will be loaded from tools/build/jsdoc/state-defaults.cjs.

This is a convenience which is probably made redundant by the typedefs thing. But I'll leave it in.

QA

I have updated the HTTP adaptor with full state docs as part of this PR.

I have tested state overrides but didn't leave any in because the docs don't actually need them in this case.