shorter comments

Author: Tofel

wasp/alert.go

@@ -23,10 +23,11 @@ type AlertChecker struct {
 	grafanaClient       *grafana.Client
 }
 
-// NewAlertChecker initializes a new AlertChecker instance by retrieving the Grafana URL and API token from the environment variables. 
-// It panics if either the GRAFANA_URL or GRAFANA_TOKEN environment variable is not set, ensuring that the necessary configuration is available. 
-// The function creates a Grafana client using the provided URL and API token, and sets up the AlertChecker with a default requirement label key and a logger. 
-// It returns a pointer to the newly created AlertChecker instance, which can be used for checking alerts in Grafana.
+// NewAlertChecker initializes and returns a new AlertChecker instance.
+// It retrieves the Grafana URL and API token from environment variables
+// GRAFANA_URL and GRAFANA_TOKEN, respectively. If either is not set, it
+// panics. The function creates a Grafana client using these credentials
+// and sets up the AlertChecker with a logger and a requirement label key.
 func NewAlertChecker(t *testing.T) *AlertChecker {
 	url := os.Getenv("GRAFANA_URL")
 	if url == "" {
@@ -47,12 +48,9 @@ func NewAlertChecker(t *testing.T) *AlertChecker {
 	}
 }
 
-// AnyAlerts checks for alerts associated with a specific dashboard and requirement label. 
-// It retrieves alert groups from the Grafana Alert Manager and scans through the alerts to determine 
-// if any alert matches the provided dashboard UUID and requirement label value. 
-// If an alert is found, it logs the alert details and marks that an alert has been raised. 
-// The function returns the list of alert groups and any error encountered during the retrieval process. 
-// If the test context is active and an alert was raised, it will mark the test as failed.
+// AnyAlerts checks for alerts in Grafana that match the specified dashboard UUID and requirement label value.
+// It returns a slice of AlertGroupsResponse and any error encountered during the retrieval of alert groups.
+// If an alert is found, it logs the alert details and marks the test as failed if a testing object is present.
 func (m *AlertChecker) AnyAlerts(dashboardUUID, requirementLabelValue string) ([]grafana.AlertGroupsResponse, error) {
 	raised := false
 	defer func() {
@@ -84,11 +82,9 @@ func (m *AlertChecker) AnyAlerts(dashboardUUID, requirementLabelValue string) ([
 	return alertGroups, nil
 }
 
-// CheckDashboardAlerts retrieves annotations of type "alert" from a specified Grafana dashboard within a given time range. 
-// It returns a slice of annotations and an error if any occurred during the retrieval process. 
-// If the retrieval is successful, the function sorts the annotations by time from oldest to newest and checks if any alerts are in an "alerting" state. 
-// If at least one alert is found to be firing, it returns the annotations along with an error indicating that an alert was firing. 
-// If no alerts are firing, it returns the annotations with a nil error.
+// CheckDashboardAlerts retrieves and checks alerts from a Grafana dashboard within a specified time range.
+// It returns a slice of annotations representing the alerts and an error if any alert is in the "alerting" state
+// or if there is an issue retrieving the annotations. The alerts are sorted by time from oldest to newest.
 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,17 +7,16 @@ type SliceBuffer[T any] struct {
 	Data     []T
 }
 
-// NewSliceBuffer initializes a new SliceBuffer with the specified capacity. 
-// It returns a pointer to the newly created SliceBuffer, which contains an empty slice of the specified type. 
-// This function is useful for creating a buffer that can hold elements of a generic type T, allowing for dynamic data storage.
+// NewSliceBuffer creates a new SliceBuffer with the specified capacity.
+// It initializes the buffer to hold elements of any type T, starting with an empty slice.
+// The function returns a pointer to the newly created SliceBuffer.
 func NewSliceBuffer[T any](cap int) *SliceBuffer[T] {
 	return &SliceBuffer[T]{Capacity: cap, Data: make([]T, 0)}
 }
 
-// Append adds a new element to the SliceBuffer. If the buffer has reached its capacity, 
-// it will overwrite the oldest element. The function maintains the current index for 
-// the next insertion, wrapping around when the end of the buffer is reached. 
-// This allows for efficient storage of a fixed-size collection of elements.
+// Append adds an element of type T to the SliceBuffer. If the buffer's capacity is reached,
+// it overwrites the oldest element, maintaining a circular buffer. The index is incremented
+// after each append operation, wrapping around to the start if necessary.
 func (m *SliceBuffer[T]) Append(s T) {
 	if m.Idx >= m.Capacity {
 		m.Idx = 0

wasp/cluster.go

@@ -68,13 +68,9 @@ type ClusterConfig struct {
 	tmpHelmFilePath string
 }
 
-// Defaults initializes default values for the Helm configuration and related paths in the ClusterConfig. 
-// It sets the namespace, sync identifier, deployment timeout, resource requests and limits, 
-// and ensures that default chart, Dockerfile, Docker ignore file, and build script are created 
-// if their respective paths are not provided. 
-// If any errors occur during file writing or path resolution, it returns the error encountered. 
-// This function is typically called during the creation of a new ClusterProfile to ensure 
-// that the configuration is complete and valid before proceeding with further operations.
+// Defaults sets default values for the ClusterConfig fields if they are not already set.
+// It initializes Helm values, file paths, and resource requests and limits with default values.
+// It returns an error if any file operations fail during the setup process.
 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?
@@ -139,10 +135,8 @@ func (m *ClusterConfig) Defaults(a int) error {
 	return nil
 }
 
-// Validate checks the ClusterConfig for required fields. 
-// It ensures that the Namespace is not empty and that the "jobs" key in HelmValues is set. 
-// If any of these validations fail, it returns an error detailing the missing fields. 
-// If all validations pass, it returns nil, indicating that the configuration is valid.
+// Validate checks the ClusterConfig for required fields and returns an error if any are missing.
+// Specifically, it ensures that the Namespace and HelmValues["jobs"] fields are not empty.
 func (m *ClusterConfig) Validate() (err error) {
 	if m.Namespace == "" {
 		err = errors.Join(err, ErrNoNamespace)
@@ -153,10 +147,8 @@ func (m *ClusterConfig) Validate() (err error) {
 	return
 }
 
-// parseECRImageURI parses an Amazon ECR image URI into its constituent parts: registry, repository, and tag. 
-// It expects the URI to be in the format ${registry}/${repo}:${tag}. 
-// If the format is invalid, it returns an error indicating the expected format. 
-// On success, it returns the extracted registry, repository, and tag as strings, along with a nil error.
+// parseECRImageURI parses an Amazon ECR image URI into its constituent parts: registry, repository, and tag.
+// It returns an error if the URI does not match the expected format `${registry}/${repo}:${tag}`.
 func parseECRImageURI(uri string) (registry, repo, tag string, err error) {
 	re := regexp.MustCompile(`^([^/]+)/([^:]+):(.+)$`)
 	matches := re.FindStringSubmatch(uri)
@@ -174,11 +166,11 @@ type ClusterProfile struct {
 	Cancel context.CancelFunc
 }
 
-// NewClusterProfile creates a new ClusterProfile instance based on the provided ClusterConfig. 
-// It validates the configuration and sets default values before initializing the ClusterProfile. 
-// If the configuration includes an update for the image, it builds and pushes the image as part of the initialization process. 
-// The function returns a pointer to the newly created ClusterProfile and an error if any issues occur during the process. 
-// If the configuration is invalid or if there are errors in parsing the timeout duration, an appropriate error is returned.
+// NewClusterProfile creates a new ClusterProfile using the provided ClusterConfig.
+// It validates and applies default settings to the configuration. It logs the configuration
+// and sets a context with a timeout based on the test timeout duration specified in the config.
+// If UpdateImage is true, it builds and pushes the image. It returns the ClusterProfile and
+// any error encountered during the process.
 func NewClusterProfile(cfg *ClusterConfig) (*ClusterProfile, error) {
 	if err := cfg.Validate(); err != nil {
 		return nil, err
@@ -204,12 +196,7 @@ func NewClusterProfile(cfg *ClusterConfig) (*ClusterProfile, error) {
 	return cp, nil
 }
 
-// buildAndPushImage builds a Docker image using the specified configuration and pushes it to a container registry. 
-// It constructs the command to execute based on the provided build script, Dockerfile, and context path, 
-// along with the image tag, registry, and repository details parsed from the image URI. 
-// If any errors occur during the parsing of the image URI or the execution of the build command, 
-// the function returns the corresponding error. 
-// On successful execution, it returns nil.
+// buildAndPushImage parses the ECR image URI from the configuration and constructs a command to build and push a Docker image. It returns an error if the URI parsing or command execution fails.
 func (m *ClusterProfile) buildAndPushImage() error {
 	registry, repo, tag, err := parseECRImageURI(m.cfg.HelmValues["image"])
 	if err != nil {
@@ -228,11 +215,10 @@ func (m *ClusterProfile) buildAndPushImage() error {
 	return ExecCmd(cmd)
 }
 
-// deployHelm installs a Helm chart using the specified test name and configuration settings. 
-// It constructs a command to execute the Helm install operation, incorporating any Helm values 
-// provided in the configuration. The function also ensures that the temporary Helm file is 
-// removed after execution. If the command execution fails, it returns an error indicating 
-// the failure of the deployment process.
+// deployHelm installs a Helm chart using the specified testName as the release name.
+// It constructs the Helm command with the chart path, values, namespace, and timeout
+// from the ClusterProfile configuration. It returns any error encountered during the
+// execution of the Helm command.
 func (m *ClusterProfile) deployHelm(testName string) error {
 	//nolint
 	defer os.Remove(m.cfg.tmpHelmFilePath)
@@ -247,12 +233,10 @@ func (m *ClusterProfile) deployHelm(testName string) error {
 	return ExecCmd(cmd.String())
 }
 
-// Run executes the deployment of a Helm chart and tracks the associated jobs. 
-// It generates a unique test name, ensuring it starts with a letter, and then 
-// calls the deployHelm method to initiate the deployment. If the deployment 
-// is successful, it retrieves the number of jobs from the configuration and 
-// invokes the TrackJobs method to monitor the job status. 
-// The function returns an error if any step in the process fails.
+// Run generates a unique test name, modifies it to comply with Helm naming rules,
+// and deploys a Helm chart using this name. It retrieves the number of jobs from
+// the Helm values and tracks these jobs within the specified namespace. It returns
+// an error if any step in the process fails.
 func (m *ClusterProfile) Run() error {
 	testName := uuid.NewString()[0:8]
 	tn := []rune(testName)

wasp/cmd.go

@@ -9,19 +9,18 @@ import (
 	"github.com/rs/zerolog/log"
 )
 
-// ExecCmd executes a command in the shell and logs its output. 
-// It takes a command string as input and returns an error if the command fails to execute or if there are issues with the output streams. 
-// The command's standard output and standard error are processed by a logging function that captures and logs the output in real-time. 
-// If the command completes successfully, ExecCmd returns nil; otherwise, it returns an error detailing the failure.
+// ExecCmd executes the given command string in a shell environment.
+// It logs the command's output using the default logging mechanism.
+// It returns any error encountered during the execution of the command.
 func ExecCmd(command string) error {
 	return ExecCmdWithStreamFunc(command, func(m string) {
 		log.Info().Str("Text", m).Msg("Command output")
 	})
 }
 
-// readStdPipe reads lines from the provided io.ReadCloser pipe and passes each line to the specified streamFunc. 
-// If streamFunc is nil, the lines will be ignored. The function continues reading until the pipe is closed or an error occurs. 
-// It is typically used to handle output from command execution in a streaming manner.
+// readStdPipe reads lines from the provided io.ReadCloser pipe and passes each line to the streamFunc callback.
+// If streamFunc is nil, the lines are not processed. This function is typically used to handle output streams
+// from executed commands, allowing real-time processing of command output.
 func readStdPipe(pipe io.ReadCloser, streamFunc func(string)) {
 	scanner := bufio.NewScanner(pipe)
 	scanner.Split(bufio.ScanLines)
@@ -33,11 +32,9 @@ func readStdPipe(pipe io.ReadCloser, streamFunc func(string)) {
 	}
 }
 
-// ExecCmdWithStreamFunc executes a command specified by the command string and streams its output 
-// to the provided outputFunction. The outputFunction is called with each line of output from both 
-// standard output and standard error streams. The function returns an error if there is an issue 
-// starting the command, creating pipes, or waiting for the command to complete. 
-// If the command executes successfully, it will return nil.
+// ExecCmdWithStreamFunc executes a shell command and streams its output to the provided outputFunction.
+// The command's standard output and standard error are captured and passed to outputFunction line by line.
+// It returns any error encountered during the execution of the command.
 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,6 +4,9 @@ import (
 	"github.com/smartcontractkit/chainlink-testing-framework/wasp/dashboard"
 )
 
+// main initializes a default dashboard without non-functional requirements (NFRs) or extensions.
+// It creates a new dashboard instance and deploys it, using environment variables for configuration.
+// If an error occurs during dashboard creation or deployment, the function panics.
 func main() {
 	// just default dashboard, no NFRs, no dashboard extensions
 	// see examples/alerts.go for an example extension