Enforce godoc comments for exported functions

This updates a filter in our golangci-lint configuration to start
enforcing the presence of godoc comments on any functions or variables
that are exported. This aligns with most of the rest of the codebase and
makes it so there is (somewhat) useful documentation for anything that
can be accessed externally from a package.

Signed-off-by: Sean McGinnis <[email protected]>

.golangci.yml

@@ -115,7 +115,7 @@ issues:
   - linters:
     - revive
     text: exported (method|function|type|const) (.+) should have comment or be unexported
-    path: "(framework|e2e|infrastructure/docker)/.*.go"
+    path: "(framework|e2e)/.*.go"
   # Disable unparam "always receives" which might not be really
   # useful when building libraries.
   - linters:

test/infrastructure/docker/config/crd/bases/infrastructure.cluster.x-k8s.io_dockermachinepools.yaml

@@ -135,6 +135,8 @@ spec:
                 description: Instances contains the status for each instance in the
                   pool
                 items:
+                  description: DockerMachinePoolInstanceStatus contains status information
+                    about a DockerMachinePool.
                   properties:
                     addresses:
                       description: Addresses contains the associated addresses for
@@ -317,6 +319,8 @@ spec:
                 description: Instances contains the status for each instance in the
                   pool
                 items:
+                  description: DockerMachinePoolInstanceStatus contains status information
+                    about a DockerMachinePool.
                   properties:
                     addresses:
                       description: Addresses contains the associated addresses for
@@ -500,6 +504,8 @@ spec:
                 description: Instances contains the status for each instance in the
                   pool
                 items:
+                  description: DockerMachinePoolInstanceStatus contains status information
+                    about a DockerMachinePool.
                   properties:
                     addresses:
                       description: Addresses contains the associated addresses for

test/infrastructure/docker/exp/api/v1alpha3/dockermachinepool_types.go

@@ -83,6 +83,7 @@ type DockerMachinePoolStatus struct {
 	Conditions clusterv1.Conditions `json:"conditions,omitempty"`
 }
 
+// DockerMachinePoolInstanceStatus contains status information about a DockerMachinePool.
 type DockerMachinePoolInstanceStatus struct {
 	// Addresses contains the associated addresses for the docker machine.
 	// +optional

test/infrastructure/docker/exp/api/v1alpha4/dockermachinepool_types.go

@@ -83,6 +83,7 @@ type DockerMachinePoolStatus struct {
 	Conditions clusterv1.Conditions `json:"conditions,omitempty"`
 }
 
+// DockerMachinePoolInstanceStatus contains status information about a DockerMachinePool.
 type DockerMachinePoolInstanceStatus struct {
 	// Addresses contains the associated addresses for the docker machine.
 	// +optional

test/infrastructure/docker/exp/api/v1beta1/dockermachinepool_types.go

@@ -83,6 +83,7 @@ type DockerMachinePoolStatus struct {
 	Conditions clusterv1.Conditions `json:"conditions,omitempty"`
 }
 
+// DockerMachinePoolInstanceStatus contains status information about a DockerMachinePool.
 type DockerMachinePoolInstanceStatus struct {
 	// Addresses contains the associated addresses for the docker machine.
 	// +optional

test/infrastructure/docker/internal/docker/kind_manager.go

@@ -30,10 +30,16 @@ import (
 	"sigs.k8s.io/kind/pkg/cluster/constants"
 )
 
+// KubeadmContainerPort is the port that kubeadm listens on in the container.
 const KubeadmContainerPort = 6443
+
+// ControlPlanePort is the port for accessing the control plane API in the container.
 const ControlPlanePort = 6443
+
+// DefaultNetwork is the default network name to use in kind.
 const DefaultNetwork = "kind"
 
+// Manager is the kind manager type.
 type Manager struct{}
 
 type nodeCreateOpts struct {
@@ -47,6 +53,7 @@ type nodeCreateOpts struct {
 	IPFamily     clusterv1.ClusterIPFamily
 }
 
+// CreateControlPlaneNode will create a new control plane container.
 func (m *Manager) CreateControlPlaneNode(ctx context.Context, name, image, clusterName, listenAddress string, port int32, mounts []v1alpha4.Mount, portMappings []v1alpha4.PortMapping, labels map[string]string, ipFamily clusterv1.ClusterIPFamily) (*types.Node, error) {
 	// gets a random host port for the API server
 	if port == 0 {
@@ -81,6 +88,7 @@ func (m *Manager) CreateControlPlaneNode(ctx context.Context, name, image, clust
 	return node, nil
 }
 
+// CreateWorkerNode will create a new worker container.
 func (m *Manager) CreateWorkerNode(ctx context.Context, name, image, clusterName string, mounts []v1alpha4.Mount, portMappings []v1alpha4.PortMapping, labels map[string]string, ipFamily clusterv1.ClusterIPFamily) (*types.Node, error) {
 	createOpts := &nodeCreateOpts{
 		Name:         name,
@@ -95,6 +103,7 @@ func (m *Manager) CreateWorkerNode(ctx context.Context, name, image, clusterName
 	return createNode(ctx, createOpts)
 }
 
+// CreateExternalLoadBalancerNode will create a new container to act as the load balancer for external access.
 func (m *Manager) CreateExternalLoadBalancerNode(ctx context.Context, name, image, clusterName, listenAddress string, port int32, ipFamily clusterv1.ClusterIPFamily) (*types.Node, error) {
 	// gets a random host port for control-plane load balancer
 	// gets a random host port for the API server

test/infrastructure/docker/internal/docker/machine.go

@@ -102,6 +102,7 @@ func NewMachine(cluster *clusterv1.Cluster, machine, image string, labels map[st
 	}, nil
 }
 
+// ListMachinesByCluster will retrieve a list of all machines that are part of the given cluster.
 func ListMachinesByCluster(cluster *clusterv1.Cluster, labels map[string]string) ([]*Machine, error) {
 	if cluster == nil {
 		return nil, errors.New("cluster is required when listing machines in the cluster")
@@ -181,6 +182,8 @@ func (m *Machine) ProviderID() string {
 	return fmt.Sprintf("docker:////%s", m.ContainerName())
 }
 
+// Address will get the IP address of the machine. If IPv6 is enabled, it will return
+// the IPv6 address, otherwise an IPv4 address.
 func (m *Machine) Address(ctx context.Context) (string, error) {
 	ipv4, ipv6, err := m.container.IP(ctx)
 	if err != nil {
@@ -275,6 +278,7 @@ func kindMounts(mounts []infrav1.Mount) []v1alpha4.Mount {
 	return ret
 }
 
+// PreloadLoadImages takes a list of container images and imports them into a machine.
 func (m *Machine) PreloadLoadImages(ctx context.Context, images []string) error {
 	// Save the image into a tar
 	dir, err := os.MkdirTemp("", "image-tar")

test/infrastructure/docker/internal/docker/types/node.go

@@ -131,16 +131,19 @@ func (n *Node) Kill(ctx context.Context, signal string) error {
 	return nil
 }
 
+// ContainerCmder is used for running commands within a container.
 type ContainerCmder struct {
 	nameOrID string
 }
 
+// GetContainerCmder gets a new ContainerCmder instance used for running commands within a container.
 func GetContainerCmder(containerNameOrID string) *ContainerCmder {
 	return &ContainerCmder{
 		nameOrID: containerNameOrID,
 	}
 }
 
+// Command is the command to be run in a container.
 func (c *ContainerCmder) Command(command string, args ...string) *ContainerCmd {
 	return &ContainerCmd{
 		nameOrID: c.nameOrID,
@@ -176,6 +179,7 @@ func (c *ContainerCmd) RunLoggingOutputOnFail(ctx context.Context) ([]string, er
 	return out, errors.WithStack(err)
 }
 
+// Run will run a configured ContainerCmd inside a container instance.
 func (c *ContainerCmd) Run(ctx context.Context) error {
 	containerRuntime, err := container.NewDockerClient()
 	if err != nil {
@@ -197,18 +201,22 @@ func (c *ContainerCmd) Run(ctx context.Context) error {
 	return nil
 }
 
+// SetEnv sets environment variable settings to define in a node.
 func (c *ContainerCmd) SetEnv(env ...string) {
 	c.env = env
 }
 
+// SetStdin sets the io.Reader to use for receiving stdin input.
 func (c *ContainerCmd) SetStdin(r io.Reader) {
 	c.stdin = r
 }
 
+// SetStdout sets the io.Writer to use for stdout output.
 func (c *ContainerCmd) SetStdout(w io.Writer) {
 	c.stdout = w
 }
 
+// SetStderr sets the io.Writer to use for stderr output.
 func (c *ContainerCmd) SetStderr(w io.Writer) {
 	c.stderr = w
 }