API reference: clarify optional vs required properties and parameters

[josephjclark]

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)