⚠️ Enforce comments on most of the codebase

Marked as a breaking change because we're unexporting some previously
exported variables or structs.

Signed-off-by: Vince Prignano <[email protected]>

Author: vincepri

.golangci.yml

@@ -44,21 +44,32 @@ issues:
   exclude:
   - "G108: Profiling endpoint is automatically exposed on /debug/pprof"
   - Error return value of .((os\.)?std(out|err)\..*|.*Close|.*Flush|os\.Remove(All)?|.*print(f|ln)?|os\.(Un)?Setenv). is not checked
-  - exported method `.*.Reconcile` should have comment or be unexported
-  - exported method `.*.SetupWithManager` should have comment or be unexported
+  - exported method `.*.(Reconcile|SetupWithManager|SetupWebhookWithManager)` should have comment or be unexported
   # The following are being worked on to remove their exclusion. This list should be reduced or go away all together over time.
   # If it is decided they will not be addressed they should be moved above this comment.
   - Subprocess launch(ed with variable|ing should be audited)
   - (Expect directory permissions to be 0750 or less|Expect file permissions to be 0600 or less)
   - (G104|G307)
-  - exported (method|function|type|const) (.+) should have comment or be unexported
   exclude-rules:
   # With Go 1.16, the new embed directive can be used with an un-named import,
   # golint only allows these to be imported in a main.go, which wouldn't work for us.
   # This directive allows the embed package to be imported with an underscore everywhere.
   - linters:
     - golint
     source: _ "embed"
+  # Exclude some packages or code to require comments, for example test code, or fake clients.
+  - linters:
+    - golint
+    text: exported (method|function|type|const) (.+) should have comment or be unexported
+    source: (func|type).*Fake.*
+  - linters:
+    - golint
+    text: exported (method|function|type|const) (.+) should have comment or be unexported
+    path: fake_\.go
+  - linters:
+    - golint
+    text: exported (method|function|type|const) (.+) should have comment or be unexported
+    path: .*test/(providers|framework|e2e).*.go
   # Disable unparam "always receives" which might not be really
   # useful when building libraries.
   - linters:
@@ -70,9 +81,7 @@ issues:
     text: should not use dot imports
   - path: _test\.go
     text: cyclomatic complexity
-  - path: test/framework.*.go
-    text: should not use dot imports
-  - path: test/e2e.*.go
+  - path: test/(framework|e2e).*.go
     text: should not use dot imports
 
 run:

api/v1alpha3/cluster_types.go

@@ -213,10 +213,12 @@ type Cluster struct {
 	Status ClusterStatus `json:"status,omitempty"`
 }
 
+// GetConditions returns the set of conditions for this object.
 func (c *Cluster) GetConditions() Conditions {
 	return c.Status.Conditions
 }
 
+// SetConditions sets the conditions on this object.
 func (c *Cluster) SetConditions(conditions Conditions) {
 	c.Status.Conditions = conditions
 }

api/v1alpha3/machine_types.go

@@ -252,10 +252,12 @@ type Machine struct {
 	Status MachineStatus `json:"status,omitempty"`
 }
 
+// GetConditions returns the set of conditions for this object.
 func (m *Machine) GetConditions() Conditions {
 	return m.Status.Conditions
 }
 
+// SetConditions sets the conditions on this object.
 func (m *Machine) SetConditions(conditions Conditions) {
 	m.Status.Conditions = conditions
 }

api/v1alpha3/machinedeployment_types.go

@@ -21,6 +21,7 @@ import (
 	"k8s.io/apimachinery/pkg/util/intstr"
 )
 
+// MachineDeploymentStrategyType defines the type of MachineDeployment rollout strategies.
 type MachineDeploymentStrategyType string
 
 const (

api/v1alpha3/machinehealthcheck_types.go

@@ -132,10 +132,12 @@ type MachineHealthCheck struct {
 	Status MachineHealthCheckStatus `json:"status,omitempty"`
 }
 
+// GetConditions returns the set of conditions for this object.
 func (m *MachineHealthCheck) GetConditions() Conditions {
 	return m.Status.Conditions
 }
 
+// SetConditions sets the conditions on this object.
 func (m *MachineHealthCheck) SetConditions(conditions Conditions) {
 	m.Status.Conditions = conditions
 }

api/v1alpha4/cluster_types.go

@@ -211,14 +211,17 @@ type Cluster struct {
 	Status ClusterStatus `json:"status,omitempty"`
 }
 
+// GetConditions returns the set of conditions for this object.
 func (c *Cluster) GetConditions() Conditions {
 	return c.Status.Conditions
 }
 
+// SetConditions sets the conditions on this object.
 func (c *Cluster) SetConditions(conditions Conditions) {
 	c.Status.Conditions = conditions
 }
 
+// GetIPFamily returns a ClusterIPFamily from the configuration provided.
 func (c *Cluster) GetIPFamily() (ClusterIPFamily, error) {
 	var podCIDRs, serviceCIDRs []string
 	if c.Spec.ClusterNetwork != nil {
@@ -287,6 +290,7 @@ func ipFamilyForCIDRStrings(cidrs []string) (ClusterIPFamily, error) {
 	}
 }
 
+// ClusterIPFamily defines the types of supported IP families.
 type ClusterIPFamily int
 
 // Define the ClusterIPFamily constants.

api/v1alpha4/cluster_webhook.go

@@ -36,6 +36,7 @@ func (c *Cluster) SetupWebhookWithManager(mgr ctrl.Manager) error {
 var _ webhook.Defaulter = &Cluster{}
 var _ webhook.Validator = &Cluster{}
 
+// Default satisfies the defaulting webhook interface.
 func (c *Cluster) Default() {
 	if c.Spec.InfrastructureRef != nil && len(c.Spec.InfrastructureRef.Namespace) == 0 {
 		c.Spec.InfrastructureRef.Namespace = c.Namespace

api/v1alpha4/machine_types.go

@@ -245,10 +245,12 @@ type Machine struct {
 	Status MachineStatus `json:"status,omitempty"`
 }
 
+// GetConditions returns the set of conditions for this object.
 func (m *Machine) GetConditions() Conditions {
 	return m.Status.Conditions
 }
 
+// SetConditions sets the conditions on this object.
 func (m *Machine) SetConditions(conditions Conditions) {
 	m.Status.Conditions = conditions
 }

api/v1alpha4/machinedeployment_types.go

@@ -21,6 +21,7 @@ import (
 	"k8s.io/apimachinery/pkg/util/intstr"
 )
 
+// MachineDeploymentStrategyType defines the type of MachineDeployment rollout strategies.
 type MachineDeploymentStrategyType string
 
 const (

api/v1alpha4/machinehealthcheck_types.go

@@ -144,10 +144,12 @@ type MachineHealthCheck struct {
 	Status MachineHealthCheckStatus `json:"status,omitempty"`
 }
 
+// GetConditions returns the set of conditions for this object.
 func (m *MachineHealthCheck) GetConditions() Conditions {
 	return m.Status.Conditions
 }
 
+// SetConditions sets the conditions on this object.
 func (m *MachineHealthCheck) SetConditions(conditions Conditions) {
 	m.Status.Conditions = conditions
 }

bootstrap/kubeadm/api/v1alpha3/kubeadmconfig_types.go

@@ -143,10 +143,12 @@ type KubeadmConfig struct {
 	Status KubeadmConfigStatus `json:"status,omitempty"`
 }
 
+// GetConditions returns the set of conditions for this object.
 func (c *KubeadmConfig) GetConditions() clusterv1.Conditions {
 	return c.Status.Conditions
 }
 
+// SetConditions sets the conditions on this object.
 func (c *KubeadmConfig) SetConditions(conditions clusterv1.Conditions) {
 	c.Status.Conditions = conditions
 }

bootstrap/kubeadm/api/v1alpha4/kubeadmconfig_types.go

@@ -136,10 +136,12 @@ type KubeadmConfig struct {
 	Status KubeadmConfigStatus `json:"status,omitempty"`
 }
 
+// GetConditions returns the set of conditions for this object.
 func (c *KubeadmConfig) GetConditions() clusterv1.Conditions {
 	return c.Status.Conditions
 }
 
+// SetConditions sets the conditions on this object.
 func (c *KubeadmConfig) SetConditions(conditions clusterv1.Conditions) {
 	c.Status.Conditions = conditions
 }

bootstrap/kubeadm/controllers/kubeadmconfig_controller.go

@@ -77,6 +77,7 @@ type KubeadmConfigReconciler struct {
 	remoteClientGetter remote.ClusterClientGetter
 }
 
+// Scope is a scoped struct used during reconciliation.
 type Scope struct {
 	logr.Logger
 	Config      *bootstrapv1.KubeadmConfig

bootstrap/kubeadm/main.go

@@ -77,6 +77,7 @@ var (
 	healthAddr                  string
 )
 
+// InitFlags initializes this manager's flags.
 func InitFlags(fs *pflag.FlagSet) {
 	fs.StringVar(&metricsBindAddr, "metrics-bind-addr", ":8080",
 		"The address the metric endpoint binds to.")

bootstrap/kubeadm/types/utils.go

@@ -55,6 +55,7 @@ var (
 	}
 )
 
+// KubeVersionToKubeadmAPIGroupVersion maps a Kubernetes version to the correct Kubeadm API Group supported.
 func KubeVersionToKubeadmAPIGroupVersion(version semver.Version) (schema.GroupVersion, error) {
 	switch {
 	case version.LT(v1beta1KubeadmVersion):

cmd/clusterctl/api/v1alpha3/provider_type.go

@@ -151,30 +151,35 @@ type ProviderList struct {
 	Items           []Provider `json:"items"`
 }
 
+// FilterByNamespace returns a new list of providers that reside in the namespace provided.
 func (l *ProviderList) FilterByNamespace(namespace string) []Provider {
 	return l.filterBy(func(p Provider) bool {
 		return p.Namespace == namespace
 	})
 }
 
+// FilterByProviderNameAndType returns a new list of provider that match the name and type.
 func (l *ProviderList) FilterByProviderNameAndType(provider string, providerType ProviderType) []Provider {
 	return l.filterBy(func(p Provider) bool {
 		return p.ProviderName == provider && p.Type == string(providerType)
 	})
 }
 
+// FilterByType returns a new list of providers that match the given type.
 func (l *ProviderList) FilterByType(providerType ProviderType) []Provider {
 	return l.filterBy(func(p Provider) bool {
 		return p.GetProviderType() == providerType
 	})
 }
 
+// FilterCore returns a new list of providers that are in the core.
 func (l *ProviderList) FilterCore() []Provider {
 	return l.filterBy(func(p Provider) bool {
 		return p.GetProviderType() == CoreProviderType
 	})
 }
 
+// FilterNonCore returns a new list of providers that are not in the core.
 func (l *ProviderList) FilterNonCore() []Provider {
 	return l.filterBy(func(p Provider) bool {
 		return p.GetProviderType() != CoreProviderType

cmd/clusterctl/client/alpha/rollout.go

@@ -21,6 +21,7 @@ import (
 	"sigs.k8s.io/cluster-api/cmd/clusterctl/client/cluster"
 )
 
+// MachineDeployment is a resource type.
 const MachineDeployment = "machinedeployment"
 
 var validResourceTypes = []string{MachineDeployment}

cmd/clusterctl/client/client.go

@@ -105,20 +105,22 @@ type clusterctlClient struct {
 	alphaClient             alpha.Client
 }
 
-// RepositoryClientFactoryInput represents the inputs required by the
-// RepositoryClientFactory.
+// RepositoryClientFactoryInput represents the inputs required by the factory.
 type RepositoryClientFactoryInput struct {
 	Provider  Provider
 	Processor Processor
 }
+
+// RepositoryClientFactory is a factory of repository.Client from a given input.
 type RepositoryClientFactory func(RepositoryClientFactoryInput) (repository.Client, error)
 
-// ClusterClientFactoryInput reporesents the inputs required by the
-// ClusterClientFactory.
+// ClusterClientFactoryInput reporesents the inputs required by the factory.
 type ClusterClientFactoryInput struct {
 	Kubeconfig Kubeconfig
 	Processor  Processor
 }
+
+// ClusterClientFactory is a factory of cluster.Client from a given input.
 type ClusterClientFactory func(ClusterClientFactoryInput) (cluster.Client, error)
 
 // Ensure clusterctlClient implements Client.

cmd/clusterctl/client/cluster/client.go

@@ -104,6 +104,7 @@ type clusterClient struct {
 	processor               yaml.Processor
 }
 
+// RepositoryClientFactory defines a function that returns a new repository.Client.
 type RepositoryClientFactory func(provider config.Provider, configClient config.Client, options ...repository.Option) (repository.Client, error)
 
 // ensure clusterClient implements Client.
@@ -218,6 +219,7 @@ func newClusterClient(kubeconfig Kubeconfig, configClient config.Client, options
 	return client
 }
 
+// Proxy defines a client proxy interface.
 type Proxy interface {
 	// GetConfig returns the rest.Config
 	GetConfig() (*rest.Config, error)

cmd/clusterctl/client/cluster/components.go

@@ -35,6 +35,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client"
 )
 
+// DeleteOptions defines delete options.
 type DeleteOptions struct {
 	Provider         clusterctlv1.Provider
 	IncludeNamespace bool

cmd/clusterctl/client/cluster/proxy.go

@@ -217,14 +217,17 @@ func listObjByGVK(c client.Client, groupVersion, kind string, options []client.L
 	return objList, nil
 }
 
+// ProxyOption defines a function that can change proxy options.
 type ProxyOption func(p *proxy)
 
+// InjectProxyTimeout sets the proxy timeout.
 func InjectProxyTimeout(t time.Duration) ProxyOption {
 	return func(p *proxy) {
 		p.timeout = t
 	}
 }
 
+// InjectKubeconfigPaths sets the kubeconfig paths loading rules.
 func InjectKubeconfigPaths(paths []string) ProxyOption {
 	return func(p *proxy) {
 		p.configLoadingRules.Precedence = paths

cmd/clusterctl/client/cluster/template.go

@@ -54,6 +54,7 @@ type templateClient struct {
 // ensure templateClient implements TemplateClient.
 var _ TemplateClient = &templateClient{}
 
+// TemplateClientInput is an input struct for newTemplateClient.
 type TemplateClientInput struct {
 	proxy        Proxy
 	configClient config.Client

cmd/clusterctl/client/config/provider.go

@@ -83,6 +83,7 @@ func (p *provider) Less(other Provider) bool {
 		(p.providerType.Order() == other.Type().Order() && p.name < other.Name())
 }
 
+// NewProvider creates a new Provider with the given input.
 func NewProvider(name string, url string, ttype clusterctlv1.ProviderType) Provider {
 	return &provider{
 		name:         name,

cmd/clusterctl/client/init.go

@@ -27,6 +27,7 @@ import (
 	logf "sigs.k8s.io/cluster-api/cmd/clusterctl/log"
 )
 
+// NoopProvider determines if a provider passed in should behave as a no-op.
 const NoopProvider = "-"
 
 // InitOptions carries the options supported by Init.

cmd/clusterctl/client/repository/template.go

@@ -70,6 +70,7 @@ func (t *template) Yaml() ([]byte, error) {
 	return utilyaml.FromUnstructured(t.objs)
 }
 
+// TemplateInput is an input struct for NewTemplate.
 type TemplateInput struct {
 	RawArtifact           []byte
 	ConfigVariablesClient config.VariablesClient

cmd/clusterctl/client/repository/template_client.go

@@ -38,6 +38,7 @@ type templateClient struct {
 	processor             yaml.Processor
 }
 
+// TemplateClientInput is an input strict for newTemplateClient.
 type TemplateClientInput struct {
 	version               string
 	provider              config.Provider

cmd/clusterctl/client/tree/options.go

@@ -38,6 +38,7 @@ func (o *addObjectOptions) ApplyOptions(opts []AddObjectOption) *addObjectOption
 // e.g. control plane for KCP.
 type ObjectMetaName string
 
+// ApplyToAdd applies the given options.
 func (n ObjectMetaName) ApplyToAdd(options *addObjectOptions) {
 	options.MetaName = string(n)
 }
@@ -46,6 +47,7 @@ func (n ObjectMetaName) ApplyToAdd(options *addObjectOptions) {
 // when adding the node's children.
 type GroupingObject bool
 
+// ApplyToAdd applies the given options.
 func (n GroupingObject) ApplyToAdd(options *addObjectOptions) {
 	options.GroupingObject = bool(n)
 }
@@ -54,6 +56,7 @@ func (n GroupingObject) ApplyToAdd(options *addObjectOptions) {
 // same Status, Severity and Reason of the parent's object ready condition (it is an echo).
 type NoEcho bool
 
+// ApplyToAdd applies the given options.
 func (n NoEcho) ApplyToAdd(options *addObjectOptions) {
 	options.NoEcho = bool(n)
 }