✨ add comments for the exported methods in generated controllers (only v3+)

[bvwells]

Description
Add comments for exported methods in generated controllers in order to provide help for users.

Motivation
Closes #1606.

[k8s-ci-robot]

Welcome @bvwells!

It looks like this is your first PR to kubernetes-sigs/kubebuilder 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/kubebuilder has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @bvwells. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

[bvwells]

Need to sort out issues running make generate...

[camilamacedo86]

I am all in to make the code better and more intuitive by providing an aditional info/doc. However, note that we need to be conscious with its definitions and aligned with the controller-runtime where it is implemented and also would be nice to make it easier to keep maintained. I mean, avoid the doc/text be easily outdated.

So, shows that a good option would add a very generic and small text to point users check its docs in the controller-runtime. Then, the best approach here would we need to use the tag as well to ensure that the users would get the docs according to the controller-runtime dep used. E.g;

https://github.com/kubernetes-sigs/controller-runtime/blob/v0.6.3/pkg/reconcile/reconcile.go

The tag above is v0.6.3. Note that the controller-runtime version used by the projects is defined in:

kubebuilder/pkg/plugin/v3/scaffolds/init.go

Lines 40 to 41 in 903abf8

	ControllerRuntimeVersion = "v0.6.2"
	// ControllerToolsVersion is the kubernetes-sigs/controller-tools version to be used in the project

. And then, to pass the var to the Boilerplate we can do as it is done for the Go.mod. See:

kubebuilder/pkg/plugin/v3/scaffolds/init.go

Line 112 in 903abf8

&templates.GoMod{ControllerRuntimeVersion: ControllerRuntimeVersion},

WDYT?

[bvwells]

Thanks for the review @camilamacedo86. The comment was copied across from operator-framework/operator-sdk prior it aligned with kubebuilder.

I'll see if I can reword the comment as per your suggestions.

[camilamacedo86]

Hi @bvwells,

The comment was copied across from operator-framework/operator-sdk prior it aligned with kubebuilder.

You might be looking at some code that was describing the code/example scaffolded in the old versions. However, in POV SDK and Kube regards the controller/reconcile should be aligned controller-runtime where its implementation came from. I am looking for your improvements. Really thank you for your contribution 🥇

[bvwells]

Hi @camilamacedo86, yes in operator-sdk there was documentation describing the reconcile loop. See here

https://github.com/operator-framework/operator-sdk/blob/53b00d125fb12515cd74fb169149913b401c8995/internal/scaffold/controller_kind.go#L208

I noticed that this documentation disappeared when operator-sdk aligned with kubebuilder in v0.0.19. This is why I submitted the issue.

[bvwells]

I'll try to sketch something out this weekend.

[bvwells]

Hi @camilamacedo86, hope you had a good weekend! Made a few changes to the Reconcile documentation. Let me know what you think. I'm more than happy to iterate on it.

[camilamacedo86]

Really thank you for your contribution.
It shows great for me. 👍 Could you just rebase it with the master and re-gen the testdata with make generate to update this PR?

c/c @gab-satchi @estroz WDYT?

[camilamacedo86]

/ok-to-test

[camilamacedo86]

/approve

However, note it will not pass in the CI before you update it with the master branch.

[bvwells]

Thanks for the reviews @camilamacedo86! All rebased to master.

[Adirio]

LGTM
I'm not setting the lgtm flag to let @camilamacedo86 have the last word as she already set the approved flag and if I set the lgtm one it will get merged.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: Adirio, bvwells, camilamacedo86

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [camilamacedo86]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[camilamacedo86]

I'm not setting the lgtm flag to let @camilamacedo86 have the last word as she already set the approved flag and if I set the lgtm one it will get merged.

Hi @Adirio,

Thank you for your review on that. It shows fine for me as well. I think it might be helpful to end-users in order to address common questions. So,

/lgtm

[bvwells]

Thanks @camilamacedo86 and @Adirio for your help getting this over the line!