Add documentation

[ojkelly]

We need some documentation explaining the project as a whole and how to use parts.

We also need something like JSDoc to generate documentation for all the functions that we export.

Finally, this needs to be hosted somewhere.

[ojkelly]

Theres a bunch of JSDoc things, this also looks interesting https://typedoc.org

[thoiberg]

Typedoc looks good, but unfortunately it uses its own version of Typescript, rather than the version kerosene uses and the current stable version is pinned to Typescript 3.2, which causes problems when it tries to parse the 3.4 syntax (like readonly array) in kerosene.

The latest master branch of Typedoc is using Typescript 3.5 so once that gets released we should be able to add it to the project. However, this raises issues if we would want to use Typedoc at all, given we don't want to be prevented from using improvements in later versions of Typescript if it breaks doc generation.

[ojkelly]

I wonder if we try going the golang way. Take the comment above the function, and render that.

[nhardy]

Might be able to use something like https://www.npmjs.com/package/@microsoft/api-extractor and https://www.npmjs.com/package/@microsoft/api-documenter