Audit the API documentation

[wallrj]

In https://github.com/jetstack/navigator/pull/244#discussion_r170941157 @kragniz asked:

should this now be marked +optional?

I'm not sure.

Perhaps we should:

• Check that our APIs are fully and consistently documented.
• Maybe add CI checks for missing or incorrect API documentation
• and we should actually generate some API documentation of course :-)

There's a similar issue in Kubernetes with some guidelines: https://github.com/kubernetes/kubernetes/issues/14924

/kind feature