From a0890c8051f3af77d5270b443846e7955fd2410d Mon Sep 17 00:00:00 2001 From: Sean McGinnis Date: Tue, 7 Dec 2021 19:01:56 -0600 Subject: [PATCH] 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 --- .golangci.yml | 2 +- ...frastructure.cluster.x-k8s.io_dockermachinepools.yaml | 6 ++++++ .../docker/exp/api/v1alpha3/dockermachinepool_types.go | 1 + .../docker/exp/api/v1alpha4/dockermachinepool_types.go | 1 + .../docker/exp/api/v1beta1/dockermachinepool_types.go | 1 + .../docker/internal/docker/kind_manager.go | 9 +++++++++ test/infrastructure/docker/internal/docker/machine.go | 4 ++++ test/infrastructure/docker/internal/docker/types/node.go | 8 ++++++++ 8 files changed, 31 insertions(+), 1 deletion(-) diff --git a/.golangci.yml b/.golangci.yml index 98e97387e251..858d2cf92afe 100644 --- a/.golangci.yml +++ b/.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: diff --git a/test/infrastructure/docker/config/crd/bases/infrastructure.cluster.x-k8s.io_dockermachinepools.yaml b/test/infrastructure/docker/config/crd/bases/infrastructure.cluster.x-k8s.io_dockermachinepools.yaml index 470ffc9a3955..ce97a8f51ffa 100644 --- a/test/infrastructure/docker/config/crd/bases/infrastructure.cluster.x-k8s.io_dockermachinepools.yaml +++ b/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 diff --git a/test/infrastructure/docker/exp/api/v1alpha3/dockermachinepool_types.go b/test/infrastructure/docker/exp/api/v1alpha3/dockermachinepool_types.go index b259c8752557..c84483f69de9 100644 --- a/test/infrastructure/docker/exp/api/v1alpha3/dockermachinepool_types.go +++ b/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 diff --git a/test/infrastructure/docker/exp/api/v1alpha4/dockermachinepool_types.go b/test/infrastructure/docker/exp/api/v1alpha4/dockermachinepool_types.go index 9de65e0d0585..8e0589b72507 100644 --- a/test/infrastructure/docker/exp/api/v1alpha4/dockermachinepool_types.go +++ b/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 diff --git a/test/infrastructure/docker/exp/api/v1beta1/dockermachinepool_types.go b/test/infrastructure/docker/exp/api/v1beta1/dockermachinepool_types.go index 1f8093d20719..bbeda8362fce 100644 --- a/test/infrastructure/docker/exp/api/v1beta1/dockermachinepool_types.go +++ b/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 diff --git a/test/infrastructure/docker/internal/docker/kind_manager.go b/test/infrastructure/docker/internal/docker/kind_manager.go index c6b88c157106..00319c69ae88 100644 --- a/test/infrastructure/docker/internal/docker/kind_manager.go +++ b/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 diff --git a/test/infrastructure/docker/internal/docker/machine.go b/test/infrastructure/docker/internal/docker/machine.go index cba9698fa476..ade73e931e91 100644 --- a/test/infrastructure/docker/internal/docker/machine.go +++ b/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") diff --git a/test/infrastructure/docker/internal/docker/types/node.go b/test/infrastructure/docker/internal/docker/types/node.go index b9655de78f62..f35045d50fa8 100644 --- a/test/infrastructure/docker/internal/docker/types/node.go +++ b/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 }