Standardize API docs

[watson]

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?

[Qard]

TSDoc is what vs code uses to embed more elaborate docs in auto-complete details. You can get both types and docs with that.

All those a markdown-based though. Are we not fairly tied to asciidoc?

[watson]

Oh, interesting. I didn't consider getting docs inside the editor, but that would be user nice! I'll have to look more into TSDoc i guess

[bmorelli25]

Thanks for putting this together @watson. I'm in favor. My only concern: are the links to JavaScript data types and data structures really necessary? I see why they would be needed in the official Node docs, but I'm not quite sold that it makes sense for our use. I'll defer to your judgement though.

[watson]

are the links to JavaScript data types and data structures really necessary?

@bmorelli25 they are not really necessary no. However I don't see a difference between the official Node.js docs and this in regards to this. I was honestly a bit surprised my self when I learned that they were links in the Node.js docs. All I wanted was a visual distinct style for the types. And making them links ensured that. If we have a way to make their style different from regular code blocks, we can do that as well.

That being said, I do like that the types which are non-standard-JavaScript types (like the Agent in the above example) are linked to the relevant documentation. With that in mind, it might look weird if the styles of the standard-JavaScript types was rendered differently than our internal types if they were not links. So therefore it might make sense to keep the links as is just to get the same visual style?

[bmorelli25]

I agree, the visual distinction does look really nice. I'll do some research, but I'm almost positive we don't have a way to do this as-is (without using links). And if we did, you're right, it might be weird if they looked like links but weren't. Let's go with links.

[bmorelli25]

What's the play from here? Is auto-generation a real option in the short-term?

[bmorelli25]

Something else I just thought of. Instead of using [small]#Added in: v1.2.3#, we should use the added tag: added[0.90.4]. Looks like this:

No hover:

On Hover:

[watson]

Ah, I didn't know we already had a custom style for "added". Could you share a link to one of our documentation pages where I can see it in context?

[bmorelli25]

https://www.elastic.co/guide/en/kibana/6.7/beats-page.html

[watson]

Hmm I'm not a big fan of the way it's stuffed at the end of a sentence and that you have to hover over it to see what it means.

It also doesn't scale well if there's more than one change. I didn't bring it up before because I was thinking we could tackle it separately, but at some point in the not too distant future I expect that we might want to expand on just a simple "Adding in x.y.z" label to a history of changes like we have in the Node.js core docs.

In the Node.js docs, if there have been no changes to how the method works since it was added, we just show the "Added in x.y.z" label:

But if there have been any changes, we show a "History" fold-out:

Here's that in the folded out state:

[bmorelli25]

I did some playing around with the added[] tag this evening, and you're right, there's not a lot of customization options. Let's run with your original small[] solution.