func.yaml Inline Documentation

[lkingland]

The func.yaml file written to a new project should include (commented) examples of the settings available to the Function developer. Ideally showing the static defaults should the developer choose to leave the section commented.

One simple solution is to create an example func.yaml on .Write which is a large, commented block at the head of the document. This is simple, intuitive and fairly easy to implement, but lacks nuance. A second solution would to be to use the _example structure used in, for example, the config maps (you can see this in action by kubectl edit configmap config-features -n knative-serving. This caused me, personally, a bit of confusion at first, and continues to do so every time I open the file for manual editing. A third option is to use a manually-created func.yaml template (using the golang templating system). This is a bit of manual work to put together, but could potentially be automated and offers a better user experience than the prior two options (if we maintain the docs meticulously. See #1853 where Zbynek links to how this is being used currently. The final, and likely most complete but predictably most complex example is to use a godoc/javadoc style comment block parser for func.yaml which injects comment blocks above each attribute, and if the attribute does not exist injects the comment along with a commented example.

I am leaning towards either a simple block at the top showing a fully-populated example, or the template. Comments and suggestions welcome!