Supporting standard `---` convention for comments to not be included in public APIs

[naemono]

We recently had a PR elastic/cloud-on-k8s#8020 where we wanted to include a comment in a public CRD, but didn't want it to be included in the public-facing API docs. It seems that the controller-tools supports using --- to preface comments to not be included. I think this tooling may want to support this as well to be consistent.