try docs generated by the new tool

Author: Tofel

wasp/alert.go

@@ -23,6 +23,10 @@ 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.
 func NewAlertChecker(t *testing.T) *AlertChecker {
 	url := os.Getenv("GRAFANA_URL")
 	if url == "" {
@@ -43,7 +47,12 @@ func NewAlertChecker(t *testing.T) *AlertChecker {
 	}
 }
 
-// AnyAlerts check if any alerts with dashboardUUID have been raised
+// 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.
 func (m *AlertChecker) AnyAlerts(dashboardUUID, requirementLabelValue string) ([]grafana.AlertGroupsResponse, error) {
 	raised := false
 	defer func() {
@@ -75,7 +84,11 @@ func (m *AlertChecker) AnyAlerts(dashboardUUID, requirementLabelValue string) ([
 	return alertGroups, nil
 }
 
-// CheckDashobardAlerts checks for alerts in the given dashboardUUIDs between from and to times
+// 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.
 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,17 @@ type SliceBuffer[T any] struct {
 	Data     []T
 }
 
-// NewSliceBuffer creates new limited capacity slice
+// 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.
 func NewSliceBuffer[T any](cap int) *SliceBuffer[T] {
 	return &SliceBuffer[T]{Capacity: cap, Data: make([]T, 0)}
 }
 
-// Append appends T if len <= cap, overrides old data otherwise
+// 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.
 func (m *SliceBuffer[T]) Append(s T) {
 	if m.Idx >= m.Capacity {
 		m.Idx = 0

wasp/cluster.go

@@ -68,6 +68,13 @@ 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.
 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?
@@ -132,6 +139,10 @@ 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.
 func (m *ClusterConfig) Validate() (err error) {
 	if m.Namespace == "" {
 		err = errors.Join(err, ErrNoNamespace)
@@ -142,7 +153,10 @@ func (m *ClusterConfig) Validate() (err error) {
 	return
 }
 
-// parseECRImageURI parses the ECR image URI and returns its components
+// 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.
 func parseECRImageURI(uri string) (registry, repo, tag string, err error) {
 	re := regexp.MustCompile(`^([^/]+)/([^:]+):(.+)$`)
 	matches := re.FindStringSubmatch(uri)
@@ -160,7 +174,11 @@ type ClusterProfile struct {
 	Cancel context.CancelFunc
 }
 
-// NewClusterProfile creates new cluster profile
+// 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.
 func NewClusterProfile(cfg *ClusterConfig) (*ClusterProfile, error) {
 	if err := cfg.Validate(); err != nil {
 		return nil, err
@@ -186,6 +204,12 @@ 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.
 func (m *ClusterProfile) buildAndPushImage() error {
 	registry, repo, tag, err := parseECRImageURI(m.cfg.HelmValues["image"])
 	if err != nil {
@@ -204,6 +228,11 @@ 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.
 func (m *ClusterProfile) deployHelm(testName string) error {
 	//nolint
 	defer os.Remove(m.cfg.tmpHelmFilePath)
@@ -218,7 +247,12 @@ func (m *ClusterProfile) deployHelm(testName string) error {
 	return ExecCmd(cmd.String())
 }
 
-// Run starts a new test
+// 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.
 func (m *ClusterProfile) Run() error {
 	testName := uuid.NewString()[0:8]
 	tn := []rune(testName)

wasp/cmd.go

@@ -9,14 +9,19 @@ import (
 	"github.com/rs/zerolog/log"
 )
 
-// ExecCmd executes os command, logging both streams
+// 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.
 func ExecCmd(command string) error {
 	return ExecCmdWithStreamFunc(command, func(m string) {
 		log.Info().Str("Text", m).Msg("Command output")
 	})
 }
 
-// readStdPipe continuously read a pipe from the command
+// 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.
 func readStdPipe(pipe io.ReadCloser, streamFunc func(string)) {
 	scanner := bufio.NewScanner(pipe)
 	scanner.Split(bufio.ScanLines)
@@ -28,7 +33,11 @@ func readStdPipe(pipe io.ReadCloser, streamFunc func(string)) {
 	}
 }
 
-// ExecCmdWithStreamFunc executes command with stream function
+// 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.
 func ExecCmdWithStreamFunc(command string, outputFunction func(string)) error {
 	c := strings.Split(command, " ")
 	cmd := exec.Command(c[0], c[1:]...)

wasp/gun_http_mock.go

@@ -14,7 +14,9 @@ type MockHTTPGun struct {
 	Data   []string
 }
 
-// NewHTTPMockGun create an HTTP mock gun
+// NewHTTPMockGun initializes a new instance of MockHTTPGun using the provided configuration.
+// It sets up an HTTP client and prepares an empty slice to store data. 
+// The returned MockHTTPGun can be used for testing purposes, simulating HTTP interactions without making real network calls.
 func NewHTTPMockGun(cfg *MockHTTPGunConfig) *MockHTTPGun {
 	return &MockHTTPGun{
 		client: resty.New(),
@@ -23,7 +25,11 @@ func NewHTTPMockGun(cfg *MockHTTPGunConfig) *MockHTTPGun {
 	}
 }
 
-// Call implements example gun call, assertions on response bodies should be done here
+// Call executes an HTTP GET request to the target URL configured in the MockHTTPGun. 
+// It returns a Response containing the result of the request. If the request encounters 
+// an error or does not return a status of "200 OK", the Response will include the error 
+// message. If the request is successful, the Response will contain the data retrieved 
+// from the target URL.
 func (m *MockHTTPGun) Call(l *Generator) *Response {
 	var result map[string]interface{}
 	r, err := m.client.R().

wasp/gun_sleep_mock.go

@@ -23,15 +23,22 @@ type MockGun struct {
 	Data []string
 }
 
-// NewMockGun create a mock gun
+// NewMockGun creates and returns a new instance of MockGun initialized with the provided configuration. 
+// It sets up the internal data structure to hold string data, starting with an empty slice. 
+// The returned MockGun can be used to simulate gun-related operations in a testing environment.
 func NewMockGun(cfg *MockGunConfig) *MockGun {
 	return &MockGun{
 		cfg:  cfg,
 		Data: make([]string, 0),
 	}
 }
 
-// Call implements example gun call, assertions on response bodies should be done here
+// Call executes a request using the provided Generator and returns a Response. 
+// It may simulate a failure or a timeout based on the configuration settings of the MockGun. 
+// If the InternalStop configuration is enabled, it will stop the Generator before proceeding. 
+// The function will also respect the CallSleep duration specified in the configuration. 
+// The returned Response contains data indicating success or failure, along with an error message if applicable. 
+// If a timeout occurs, the Response will reflect that with a Timeout flag set to true.
 func (m *MockGun) Call(l *Generator) *Response {
 	if m.cfg.InternalStop {
 		l.Stop()
@@ -54,6 +61,11 @@ func (m *MockGun) Call(l *Generator) *Response {
 	return &Response{Data: "successCallData"}
 }
 
+// convertResponsesData processes the generator's response data and returns three values: 
+// a slice of strings containing the successfully processed data, 
+// a slice of pointers to Response objects representing successful responses, 
+// and a slice of pointers to Response objects representing failed responses. 
+// The function ensures thread safety by locking the necessary mutexes during data access.
 func convertResponsesData(g *Generator) ([]string, []*Response, []*Response) {
 	g.responsesData.okDataMu.Lock()
 	defer g.responsesData.okDataMu.Unlock()

wasp/http_server_mock.go

@@ -18,17 +18,28 @@ type HTTPMockServer struct {
 	Sleep time.Duration
 }
 
+// Run starts the HTTP mock server in a separate goroutine. 
+// It invokes the server's Run method, allowing it to handle incoming requests 
+// asynchronously. This function does not return any value and is intended 
+// to be called to initiate the server's operation.
 func (s *HTTPMockServer) Run() {
 	go func() {
 		//nolint
 		_ = s.srv.Run()
 	}()
 }
 
+// URL returns the base URL of the HTTP mock server as a string. 
+// This URL can be used to send requests to the mock server for testing purposes. 
+// The returned URL is fixed and points to "http://localhost:8080/1".
 func (s *HTTPMockServer) URL() string {
 	return "http://localhost:8080/1"
 }
 
+// NewHTTPMockServer creates a new instance of HTTPMockServer with the provided configuration. 
+// If the configuration is nil, it initializes the server with default settings, including 
+// predefined latencies and HTTP response codes for two mock API endpoints. 
+// The returned HTTPMockServer can be used to simulate API responses for testing purposes.
 func NewHTTPMockServer(cfg *HTTPMockServerConfig) *HTTPMockServer {
 	if cfg == nil {
 		cfg = &HTTPMockServerConfig{

wasp/k8s.go

@@ -23,7 +23,11 @@ type K8sClient struct {
 	RESTConfig *rest.Config
 }
 
-// GetLocalK8sDeps get local k8s context config
+// GetLocalK8sDeps retrieves a Kubernetes client set and its associated REST configuration 
+// for interacting with a local Kubernetes cluster. 
+// It returns a pointer to the kubernetes.Clientset, a pointer to the rest.Config, 
+// and an error if any issues occur during the retrieval process. 
+// If successful, the client set can be used to perform operations on the Kubernetes API.
 func GetLocalK8sDeps() (*kubernetes.Clientset, *rest.Config, error) {
 	loadingRules := clientcmd.NewDefaultClientConfigLoadingRules()
 	kubeConfig := clientcmd.NewNonInteractiveDeferredLoadingClientConfig(loadingRules, &clientcmd.ConfigOverrides{})
@@ -38,7 +42,10 @@ func GetLocalK8sDeps() (*kubernetes.Clientset, *rest.Config, error) {
 	return k8sClient, k8sConfig, nil
 }
 
-// NewK8sClient creates a new k8s client with a REST config
+// NewK8sClient initializes a new K8sClient instance by retrieving the necessary Kubernetes dependencies 
+// from the local environment. It returns a pointer to the K8sClient, which contains the ClientSet and 
+// RESTConfig required for interacting with the Kubernetes API. If there is an error while fetching 
+// the dependencies, the function logs the error and terminates the program.
 func NewK8sClient() *K8sClient {
 	cs, cfg, err := GetLocalK8sDeps()
 	if err != nil {
@@ -50,18 +57,33 @@ func NewK8sClient() *K8sClient {
 	}
 }
 
+// jobPods retrieves a list of pods in the specified namespace that match the given synchronization label. 
+// It returns a pointer to a v1.PodList containing the matching pods and an error if the operation fails. 
+// If no pods are found, the returned PodList will be empty, and the error will be nil.
 func (m *K8sClient) jobPods(ctx context.Context, nsName, syncLabel string) (*v1.PodList, error) {
 	return m.ClientSet.CoreV1().Pods(nsName).List(ctx, metaV1.ListOptions{LabelSelector: syncSelector(syncLabel)})
 }
 
+// jobs retrieves a list of Kubernetes jobs in the specified namespace that match the given label selector. 
+// It takes a context for cancellation and a namespace name along with a synchronization label as parameters. 
+// The function returns a pointer to a batchV1.JobList containing the jobs that match the criteria, 
+// or an error if the retrieval fails.
 func (m *K8sClient) jobs(ctx context.Context, nsName, syncLabel string) (*batchV1.JobList, error) {
 	return m.ClientSet.BatchV1().Jobs(nsName).List(ctx, metaV1.ListOptions{LabelSelector: syncSelector(syncLabel)})
 }
 
+// syncSelector formats a string to create a label selector for synchronization purposes. 
+// It returns a string in the format "sync=<input>", where <input> is the provided string argument. 
+// This formatted string can be used in Kubernetes API calls to filter resources based on the specified synchronization label.
 func syncSelector(s string) string {
 	return fmt.Sprintf("sync=%s", s)
 }
 
+// removeJobs deletes the specified jobs in the given namespace. 
+// It takes a context for cancellation and a namespace name along with a list of jobs to be removed. 
+// The function logs the removal process and ensures that each job is deleted with a foreground deletion policy. 
+// If any error occurs during the deletion of a job, it returns the error. 
+// If all jobs are successfully deleted, it returns nil.
 func (m *K8sClient) removeJobs(ctx context.Context, nsName string, jobs *batchV1.JobList) error {
 	log.Info().Msg("Removing jobs")
 	for _, j := range jobs.Items {
@@ -75,6 +97,10 @@ func (m *K8sClient) removeJobs(ctx context.Context, nsName string, jobs *batchV1
 	return nil
 }
 
+// waitSyncGroup blocks until the specified number of pods with the given sync label are in the Running state. 
+// It periodically checks the status of the pods in the specified namespace and logs the progress. 
+// If an error occurs while retrieving the pods, it returns the error. 
+// The function will return nil once all pods are confirmed to be running, or it will continue to wait if the conditions are not met.
 func (m *K8sClient) waitSyncGroup(ctx context.Context, nsName string, syncLabel string, jobNum int) error {
 outer:
 	for {
@@ -97,7 +123,11 @@ outer:
 	}
 }
 
-// TrackJobs tracks both jobs and their pods until they succeed or fail
+// TrackJobs monitors the status of Kubernetes jobs and their associated pods in a specified namespace. 
+// It continuously checks for the specified number of job pods and logs their statuses. 
+// If any job fails, it returns an error and can optionally remove the jobs based on the keepJobs parameter. 
+// The function will exit gracefully if the provided context is done, returning nil. 
+// If all jobs succeed, it will either remove the jobs or return nil based on the keepJobs flag.
 func (m *K8sClient) TrackJobs(ctx context.Context, nsName, syncLabel string, jobNum int, keepJobs bool) error {
 	log.Debug().Str("LabelSelector", syncSelector(syncLabel)).Msg("Searching for jobs/pods")
 	for {