docs with o1-mini

Author: Tofel

wasp/alert.go

@@ -23,11 +23,9 @@ type AlertChecker struct {
 	grafanaClient       *grafana.Client
 }
 
-// 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.
+// 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.
 func NewAlertChecker(t *testing.T) *AlertChecker {
 	url := os.Getenv("GRAFANA_URL")
 	if url == "" {
@@ -48,9 +46,9 @@ func NewAlertChecker(t *testing.T) *AlertChecker {
 	}
 }
 
-// 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.
+// 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.
 func (m *AlertChecker) AnyAlerts(dashboardUUID, requirementLabelValue string) ([]grafana.AlertGroupsResponse, error) {
 	raised := false
 	defer func() {
@@ -82,9 +80,8 @@ func (m *AlertChecker) AnyAlerts(dashboardUUID, requirementLabelValue string) ([
 	return alertGroups, nil
 }
 
-// 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.
+// 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.
 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,16 +7,12 @@ type SliceBuffer[T any] struct {
 	Data     []T
 }
 
-// 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.
+// NewSliceBuffer creates and returns a new SliceBuffer for elements of type T with the specified capacity.
 func NewSliceBuffer[T any](cap int) *SliceBuffer[T] {
 	return &SliceBuffer[T]{Capacity: cap, Data: make([]T, 0)}
 }
 
-// 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.
+// 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.
 func (m *SliceBuffer[T]) Append(s T) {
 	if m.Idx >= m.Capacity {
 		m.Idx = 0

wasp/cluster.go

@@ -68,9 +68,10 @@ type ClusterConfig struct {
 	tmpHelmFilePath string
 }
 
-// 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.
+// 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.
 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?
@@ -135,8 +136,8 @@ func (m *ClusterConfig) Defaults(a int) error {
 	return nil
 }
 
-// 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.
+// 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.
 func (m *ClusterConfig) Validate() (err error) {
 	if m.Namespace == "" {
 		err = errors.Join(err, ErrNoNamespace)
@@ -147,8 +148,9 @@ func (m *ClusterConfig) Validate() (err error) {
 	return
 }
 
-// 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}`.
+// 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.
 func parseECRImageURI(uri string) (registry, repo, tag string, err error) {
 	re := regexp.MustCompile(`^([^/]+)/([^:]+):(.+)$`)
 	matches := re.FindStringSubmatch(uri)
@@ -167,10 +169,10 @@ type ClusterProfile struct {
 }
 
 // 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.
+// 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.
 func NewClusterProfile(cfg *ClusterConfig) (*ClusterProfile, error) {
 	if err := cfg.Validate(); err != nil {
 		return nil, err
@@ -196,7 +198,9 @@ func NewClusterProfile(cfg *ClusterConfig) (*ClusterProfile, error) {
 	return cp, 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.
+// 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.
 func (m *ClusterProfile) buildAndPushImage() error {
 	registry, repo, tag, err := parseECRImageURI(m.cfg.HelmValues["image"])
 	if err != nil {
@@ -215,10 +219,10 @@ func (m *ClusterProfile) buildAndPushImage() error {
 	return ExecCmd(cmd)
 }
 
-// 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.
+// 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.
 func (m *ClusterProfile) deployHelm(testName string) error {
 	//nolint
 	defer os.Remove(m.cfg.tmpHelmFilePath)
@@ -233,10 +237,9 @@ func (m *ClusterProfile) deployHelm(testName string) error {
 	return ExecCmd(cmd.String())
 }
 
-// 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.
+// 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.
 func (m *ClusterProfile) Run() error {
 	testName := uuid.NewString()[0:8]
 	tn := []rune(testName)

wasp/cmd.go

@@ -9,18 +9,17 @@ import (
 	"github.com/rs/zerolog/log"
 )
 
-// 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.
+// 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.
 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 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.
+// 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.
 func readStdPipe(pipe io.ReadCloser, streamFunc func(string)) {
 	scanner := bufio.NewScanner(pipe)
 	scanner.Split(bufio.ScanLines)
@@ -32,9 +31,9 @@ func readStdPipe(pipe io.ReadCloser, streamFunc func(string)) {
 	}
 }
 
-// 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.
+// 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.
 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,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.
+// 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.
 func main() {
 	// just default dashboard, no NFRs, no dashboard extensions
 	// see examples/alerts.go for an example extension