better godocs

Author: Tofel

wasp/alert.go

@@ -23,9 +23,9 @@ type AlertChecker struct {
 	grafanaClient       *grafana.Client
 }
 
-// NewAlertChecker creates and initializes a new AlertChecker.
-// It retrieves GRAFANA_URL and GRAFANA_TOKEN from environment variables, panicking if they are not set.
-// The AlertChecker is configured with the provided testing.T, a Grafana client, and a logger.
+// NewAlertChecker creates a new AlertChecker using Grafana configurations from environment variables.
+// It retrieves GRAFANA_URL and GRAFANA_TOKEN, ensuring they are set.
+// Use this function to set up alert checking in tests.
 func NewAlertChecker(t *testing.T) *AlertChecker {
 	url := os.Getenv("GRAFANA_URL")
 	if url == "" {
@@ -46,9 +46,8 @@ func NewAlertChecker(t *testing.T) *AlertChecker {
 	}
 }
 
-// AnyAlerts retrieves alert groups from Grafana and scans for alerts matching the specified dashboardUUID and requirementLabelValue.
-// If matching alerts are found, it logs their details and marks the test as failed.
-// It returns all alert groups and any error encountered during retrieval.
+// AnyAlerts retrieves alert groups from Grafana and checks for alerts matching the specified dashboard UUID and requirement label value.
+// It returns the matching alert groups, enabling users to identify and respond to specific alert conditions.
 func (m *AlertChecker) AnyAlerts(dashboardUUID, requirementLabelValue string) ([]grafana.AlertGroupsResponse, error) {
 	raised := false
 	defer func() {
@@ -80,8 +79,9 @@ func (m *AlertChecker) AnyAlerts(dashboardUUID, requirementLabelValue string) ([
 	return alertGroups, nil
 }
 
-// CheckDashboardAlerts retrieves alert annotations from a Grafana dashboard identified by dashboardUID within the specified time range.
-// It returns a sorted slice of annotations and an error if the retrieval fails or any alert is in a firing state.
+// CheckDashboardAlerts retrieves alert annotations from a Grafana dashboard within the specified time range.
+// It returns the sorted alerts and an error if any alert is in the alerting state.
+// Use it to verify the status of dashboard alerts after a run.
 func CheckDashboardAlerts(grafanaClient *grafana.Client, from, to time.Time, dashboardUID string) ([]grafana.Annotation, error) {
 	annotationType := "alert"
 	alerts, _, err := grafanaClient.GetAnnotations(grafana.AnnotationsQueryParams{

wasp/buffer.go

@@ -7,12 +7,15 @@ type SliceBuffer[T any] struct {
 	Data     []T
 }
 
-// NewSliceBuffer creates and returns a new SliceBuffer for elements of type T with the specified capacity.
+// NewSliceBuffer creates a new SliceBuffer with the specified capacity.
+// It provides an efficient way to store and manage a fixed number of elements,
+// enabling optimized access and manipulation in concurrent and decentralized applications.
 func NewSliceBuffer[T any](cap int) *SliceBuffer[T] {
 	return &SliceBuffer[T]{Capacity: cap, Data: make([]T, 0)}
 }
 
-// Append adds the element s to the SliceBuffer. If the buffer has not reached its capacity, s is appended to the data slice. Once the capacity is exceeded, Append overwrites the oldest element in the buffer. The internal index is incremented to track the next insertion point.
+// Append adds an element to the SliceBuffer. When the buffer reaches its capacity, it overwrites the oldest item.
+// This function is useful for maintaining a fixed-size, circular collection of elements.
 func (m *SliceBuffer[T]) Append(s T) {
 	if m.Idx >= m.Capacity {
 		m.Idx = 0

wasp/cluster.go

@@ -68,10 +68,8 @@ type ClusterConfig struct {
 	tmpHelmFilePath string
 }
 
-// Defaults initializes default settings for the ClusterConfig.
-// It populates HelmValues and sets necessary file paths if they are not already configured.
-// The parameter a allows for customization during the defaulting process.
-// Returns an error if any defaulting operation fails.
+// Defaults initializes ClusterConfig with default values for any unset fields.
+// It ensures all necessary configuration parameters are provided for proper cluster deployment.
 func (m *ClusterConfig) Defaults(a int) error {
 	// TODO: will it be more clear if we move Helm values to a struct
 	// TODO: or should it be like that for extensibility of a chart without reflection?
@@ -136,8 +134,8 @@ func (m *ClusterConfig) Defaults(a int) error {
 	return nil
 }
 
-// Validate checks that ClusterConfig has all required fields set.
-// It returns an error if Namespace is empty or if the "jobs" entry in HelmValues is missing.
+// Validate checks that the ClusterConfig has all required fields set.
+// It returns an error if any mandatory configuration is missing.
 func (m *ClusterConfig) Validate() (err error) {
 	if m.Namespace == "" {
 		err = errors.Join(err, ErrNoNamespace)
@@ -148,9 +146,9 @@ func (m *ClusterConfig) Validate() (err error) {
 	return
 }
 
-// parseECRImageURI parses an ECR image URI and returns the registry, repository, and tag.
-// It expects the URI to follow the format ${registry}/${repo}:${tag}.
-// If the URI does not match this format, an error is returned.
+// parseECRImageURI parses an ECR image URI into registry, repository, and tag.
+// It returns an error if the URI format is invalid.
+// Use it to extract components for building and deploying Docker images.
 func parseECRImageURI(uri string) (registry, repo, tag string, err error) {
 	re := regexp.MustCompile(`^([^/]+)/([^:]+):(.+)$`)
 	matches := re.FindStringSubmatch(uri)
@@ -168,11 +166,10 @@ type ClusterProfile struct {
 	Cancel context.CancelFunc
 }
 
-// NewClusterProfile creates a new ClusterProfile using the provided ClusterConfig.
-// It validates the configuration, sets default values, and initializes the Kubernetes client.
-// The function parses the test timeout duration and sets up a context with the specified timeout.
-// If UpdateImage is enabled in the configuration, it builds and pushes the image.
-// It returns the initialized ClusterProfile or an error if any step fails.
+// NewClusterProfile creates a new ClusterProfile from the provided ClusterConfig.
+// It validates the configuration, sets default values, and initializes necessary components.
+// Optionally, it builds and pushes images based on the configuration.
+// Use this function to initialize cluster management.
 func NewClusterProfile(cfg *ClusterConfig) (*ClusterProfile, error) {
 	if err := cfg.Validate(); err != nil {
 		return nil, err
@@ -198,9 +195,8 @@ func NewClusterProfile(cfg *ClusterConfig) (*ClusterProfile, error) {
 	return cp, nil
 }
 
-// buildAndPushImage builds and pushes a Docker image based on the ClusterProfile configuration.
-// It parses the ECR image URI, constructs the Docker build and push command,
-// executes the command, and returns any encountered error.
+// buildAndPushImage builds a Docker image using the cluster's configuration and pushes it to the specified registry.
+// It returns an error if the build or push operation fails.
 func (m *ClusterProfile) buildAndPushImage() error {
 	registry, repo, tag, err := parseECRImageURI(m.cfg.HelmValues["image"])
 	if err != nil {
@@ -219,10 +215,8 @@ func (m *ClusterProfile) buildAndPushImage() error {
 	return ExecCmd(cmd)
 }
 
-// deployHelm installs the Helm chart using the provided testName and the ClusterProfile's configuration.
-// It sets the necessary Helm values, namespace, and deployment timeout based on the configuration.
-// The function constructs the Helm install command, logs the execution, and runs the command.
-// Returns an error if the Helm deployment fails.
+// deployHelm installs a Helm chart using the provided test name and the ClusterProfile's configuration.
+// It constructs the Helm install command with specified values, namespace, and timeout, then executes it.
 func (m *ClusterProfile) deployHelm(testName string) error {
 	//nolint
 	defer os.Remove(m.cfg.tmpHelmFilePath)
@@ -237,9 +231,9 @@ func (m *ClusterProfile) deployHelm(testName string) error {
 	return ExecCmd(cmd.String())
 }
 
-// Run deploys the Helm chart using a generated test name and tracks the specified number of jobs.
-// It modifies the test name to ensure it starts with a letter and retrieves job configurations
-// from the cluster profile. Returns an error if deployment or job tracking fails.
+// Run deploys the Helm chart and tracks job execution for the ClusterProfile.
+// It generates a unique ID, deploys via Helm, and monitors jobs in the namespace.
+// Returns an error if deployment or tracking fails.
 func (m *ClusterProfile) Run() error {
 	testName := uuid.NewString()[0:8]
 	tn := []rune(testName)

wasp/cmd.go

@@ -9,17 +9,16 @@ import (
 	"github.com/rs/zerolog/log"
 )
 
-// ExecCmd executes the specified shell command and logs its standard output.
-// It returns an error if the command fails to start or exits with a non-zero status.
+// ExecCmd executes the provided command string and logs its output.
+// It returns an error if the command fails to run or exits with a non-zero status.
 func ExecCmd(command string) error {
 	return ExecCmdWithStreamFunc(command, func(m string) {
 		log.Info().Str("Text", m).Msg("Command output")
 	})
 }
 
-// readStdPipe reads from the provided io.ReadCloser line by line and passes each line to streamFunc.
-// It continuously scans the pipe for newline-delimited input.
-// If streamFunc is nil, the input lines are ignored.
+// readStdPipe reads lines from the provided pipe and sends each line to streamFunc.
+// It is used to handle streaming output from command execution, such as stdout and stderr.
 func readStdPipe(pipe io.ReadCloser, streamFunc func(string)) {
 	scanner := bufio.NewScanner(pipe)
 	scanner.Split(bufio.ScanLines)
@@ -31,9 +30,8 @@ func readStdPipe(pipe io.ReadCloser, streamFunc func(string)) {
 	}
 }
 
-// ExecCmdWithStreamFunc executes the specified command and streams its output.
-// It splits the command string, starts the command, and sends each line from stdout and stderr to outputFunction.
-// Returns an error if the command fails to start or encounters an execution error.
+// ExecCmdWithStreamFunc runs the specified command and streams its output and error lines 
+// to the provided outputFunction. It enables real-time handling of command execution output.
 func ExecCmdWithStreamFunc(command string, outputFunction func(string)) error {
 	c := strings.Split(command, " ")
 	cmd := exec.Command(c[0], c[1:]...)

wasp/dashboard/cmd/main.go

@@ -4,9 +4,8 @@ import (
 	"github.com/smartcontractkit/chainlink-testing-framework/wasp/dashboard"
 )
 
-// main initializes and deploys the default dashboard without NFRs or extensions.
-// It sets required environment variables and deploys the dashboard.
-// The function panics if dashboard creation or deployment fails.
+// main creates and deploys a default dashboard using environment variables for configuration.
+// It sets up the dashboard without extensions or non-functional requirements, enabling straightforward deployment.
 func main() {
 	// just default dashboard, no NFRs, no dashboard extensions
 	// see examples/alerts.go for an example extension