Docs: Update config.go comments #1636
Conversation
aimeeu
changed the title
✅ Deploy Preview for vcluster-docs canceled.
|
aimeeu
changed the title
| @@ -678,7 +678,7 @@ type EtcdDeploy struct { | |||
| // Enabled defines that an external etcd should be deployed. | |||
| Enabled bool `json:"enabled,omitempty"` | |||
|
|
|||
| // StatefulSet holds options for the external etcd statefulSet. | |||
| // Options for the external etcd StatefulSet. See https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/stateful-set-v1/ | |||
There was a problem hiding this comment.
nit: go comments prefer to start the comment with the name of the exported field/type/func. Or at least mention the name in the first sentence. See: https://go.dev/doc/comment#type
This already applies to most of the fields here. So it might be good to stick with this keeping it consistent, WDYT?
| Deployment CoreDNSDeployment `json:"deployment,omitempty"` | ||
|
|
||
| // OverwriteConfig can be used to overwrite the coredns config | ||
| // Overwrite default config. Path to a custom Corefile. See https://coredns.io/2017/07/23/corefile-explained/. |
| @@ -870,7 +871,7 @@ type ControlPlaneAdvanced struct { | |||
| // upload all required vCluster images to a single private repository and set this value. Workload images are not affected by this. | |||
| DefaultImageRegistry string `json:"defaultImageRegistry,omitempty"` | |||
|
|
|||
| // VirtualScheduler defines if a scheduler should be used within the virtual cluster or the scheduling decision for workloads will be made by the host cluster. | |||
| // Defines if a scheduler should be used within the virtual cluster or the scheduling decision for workloads will be made by the host cluster. | |||
|
Thanks for your comments @johannesfrey For example: I can work within Go comment style guidelines if if I have to. For user-facing text, this is a case of deciding whether to strictly follow Go comments style or present content that's more user-friendly but doesn't strictly follow Go comment style rules. We aren't generating a Go API guide or Go library docs, if you see my point. Probably better to let this PR sit until engineering is done updating the YAML structure. Then we can decide how to structure the comments, and I can update in a single attempt (I don't like merging/rebasing lol). |
Your welcome 🙂 . Yes I totally get your point. Indeed we should rather strive for user-friendliness instead of strictly following the go style guidelines. Especially as we are using them verbatim as user-facing docs, which I forgot while doing the review. |
Add content to comments that belongs with the field rather than separate content on the docs page.
/kind documentation
Part of ENG-3147