Cluster-api-provider-azure: Enforce documentation for public APIs

[devigned]

/kind feature

Describe the solution you'd like
The build / verification scripts should verify that every public API in the project has a non-trivial comment.

Anything else you would like to add:
The easy part is probably turning on verification. The more time consuming part is writing comments for public APIs which are not documented.

see also: https://github.com/kubernetes-sigs/cluster-api-provider-azure/pull/938#discussion_r492182584

[CecileRobertMichon]

/help

[k8s-ci-robot]

@CecileRobertMichon:
This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[mboersma]

/assign

[mboersma]

@devigned do you think simply requiring comments as we did in #996 is sufficient here? It doesn't guarantee they won't be trivial, so perhaps you were looking for additional checks.

[CecileRobertMichon]

Hopefully we should be able to rely on reviewers to evaluate the quality of code documentation. It's easier to see that something is non-descriptive than it is to notice that something is missing in a PR diff IMO.

[devigned]

Like @CecileRobertMichon said, I find it easier spot bad comments than missing ones. As part of CI, it would make folks aware of the expectation and hopefully cause them to think about the comments a little more.

[CecileRobertMichon]

Already calling me out on my copy pasting https://github.com/kubernetes-sigs/cluster-api-provider-azure/pull/974/commits/971c7e6bc128a545e8e0e695cc82b837f8be1291 😛