API reference: clarify optional vs required properties and parameters

Our JSDoc templates don't do a good job of making it clear what properties or parameters are required, and what are optional.

In the JSDoc spec, you declare an optional property or parameter in square brackets, like this:

* @param {string} [color]
* @property {string} [nickName]

But if you look at our documentation, all we do is display the property in square brackets, and who knows what that means?

Sometimes we explicitly say things are (Optional) in the description.:

This is kinda fine but we're not consistent. Also the context is different. When describing parameters, the parameters are required unless otherwise stated. But when describing an object, I'd say the properties are OPTIONAL unless otherwise stated (because objects are usually called options and if they were required, well, they wouldn't be options.

So for this issue, we need to:

• Visualise required properties and params differently to optional ones (and agree the standard)
• Consistently mark optional stuff the same way across our adaptors
• Document our rules clearly somewhere (perhaps in a wiki referenced in the readme)

Start by reviewing the JSDoc templates and the existing adaptor documentation examples, including the required and optional notation described in this issue. Agree on a consistent visual standard for properties and parameters, apply it across the adaptors, and document the rules in a clearly referenced wiki or README section. Done means required and optional items are consistently distinguishable and the convention is documented.