Standardize API docs

Today the standard in which the different APIs are documented varies quite a bit throughout the documentation. For consistency, it would be best to align on one way to document each API method.

Here’s a proposal given in the form of an example of a documented API method where the first argument is required and the two latter arguments are optional. The style is mainly inspired by the official Node.js documentation.

[[apm-my-function]]
==== `agent.myFunction(foo[, options][, callback])`

[small]#Added in: v1.2.3#

* `foo` {uri-number}[`<number>`] Some description of this argument.
* `options` {uri-object}[`<Object>`]
** `bar` {uri-string}[`<string>`] Some description of this argument. **Default:** 42.
** `baz` {uri-boolean}[`<boolean>`] | {uri-symbol}[`<symbol>`] Some description of this argument.
* `callback` {uri-function}[`<Function>`]
** `err` {uri-error}[`<Error>`]
** `exitCode` {uri-number}[`<integer>`]
* Returns: <<agent-api,`<Agent>`>>

Full description goes here...

Somewhere central we need to define these attributes:

:uri-number: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type
:uri-string: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
:uri-boolean: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type
:uri-symbol: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Symbol_type
:uri-object: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
:uri-function: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
:uri-error: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error

Here’s the rendered result:

Obviously, this documentation could maybe be generated based on a TypeScript Declaration File or JSDoc. So we should consider that as well. The TypeScript file would only have the signatures and types of course, but nothing of the actual documentation, so that might be a no-go.

@Qard @bmorelli25: What do you think?

[watson]

Let’s not spend too much time researching the “Added in” field for now. We can add those later in separate PRs.

[watson]

I’ve removed the discuss label as I think we’ve reached a conclusion. Let’s go ahead with this 💯