[Bot] Add automatically generated go documentation

Author: Tofel

wasp/benchspy/basic.go

@@ -22,6 +22,8 @@ type BasicData struct {
 	GeneratorConfigs map[string]*wasp.Config `json:"generator_configs"`
 }
 
+// MustNewBasicData creates a new BasicData instance from a commit or tag.
+// It panics if the creation fails, ensuring that the caller receives a valid instance.
 func MustNewBasicData(commitOrTag string, generators ...*wasp.Generator) BasicData {
 	b, err := NewBasicData(commitOrTag, generators...)
 	if err != nil {
@@ -31,6 +33,9 @@ func MustNewBasicData(commitOrTag string, generators ...*wasp.Generator) BasicDa
 	return *b
 }
 
+// NewBasicData creates a new BasicData instance using the provided commit or tag and a list of generators.
+// It ensures that at least one generator is provided and that it is associated with a testing.T instance. 
+// This function is essential for initializing data required for testing and reporting.
 func NewBasicData(commitOrTag string, generators ...*wasp.Generator) (*BasicData, error) {
 	if len(generators) == 0 {
 		return nil, errors.New("at least one generator is required")
@@ -58,6 +63,8 @@ func NewBasicData(commitOrTag string, generators ...*wasp.Generator) (*BasicData
 	return b, nil
 }
 
+// FillStartEndTimes calculates the earliest start time and latest end time from generator schedules.
+// It validates that all segments have valid start and end times, returning an error if any are missing.
 func (b *BasicData) FillStartEndTimes() error {
 	earliestTime := time.Now()
 	var latestTime time.Time
@@ -89,6 +96,9 @@ func (b *BasicData) FillStartEndTimes() error {
 	return nil
 }
 
+// Validate checks the integrity of BasicData by ensuring that the test start and end times are set,
+// and that at least one generator configuration is provided. It returns an error if any of these
+// conditions are not met, guiding users to correct their input before proceeding.
 func (b *BasicData) Validate() error {
 	if b.TestStart.IsZero() {
 		return errors.New("test start time is missing. We cannot query Loki without a time range. Please set it and try again")
@@ -104,6 +114,8 @@ func (b *BasicData) Validate() error {
 	return nil
 }
 
+// IsComparable checks if two BasicData instances have the same configuration settings.
+// It validates the count, presence, and equivalence of generator configurations, returning an error if discrepancies are found.
 func (b *BasicData) IsComparable(otherData BasicData) error {
 	// are all configs present? do they have the same schedule type? do they have the same segments? is call timeout the same? is rate limit timeout the same?
 	if len(b.GeneratorConfigs) != len(otherData.GeneratorConfigs) {

wasp/benchspy/generator.go

@@ -20,6 +20,9 @@ type GeneratorQueryExecutor struct {
 	QueryResults map[string]interface{}      `json:"query_results"`
 }
 
+// NewStandardGeneratorQueryExecutor creates a new GeneratorQueryExecutor for standard queries.
+// It initializes the executor with generated standard queries based on the provided generator.
+// This function is useful for setting up query execution in a standardized manner.
 func NewStandardGeneratorQueryExecutor(generator *wasp.Generator) (*GeneratorQueryExecutor, error) {
 	g := &GeneratorQueryExecutor{
 		KindName: string(StandardQueryExecutor_Generator),
@@ -33,6 +36,9 @@ func NewStandardGeneratorQueryExecutor(generator *wasp.Generator) (*GeneratorQue
 	return NewGeneratorQueryExecutor(generator, queries)
 }
 
+// NewGeneratorQueryExecutor creates a new instance of GeneratorQueryExecutor.
+// It initializes the executor with a specified generator and a set of query functions,
+// enabling the execution of custom queries against the generator's data.
 func NewGeneratorQueryExecutor(generator *wasp.Generator, queries map[string]GeneratorQueryFn) (*GeneratorQueryExecutor, error) {
 	g := &GeneratorQueryExecutor{
 		KindName:     string(StandardQueryExecutor_Generator),
@@ -44,14 +50,20 @@ func NewGeneratorQueryExecutor(generator *wasp.Generator, queries map[string]Gen
 	return g, nil
 }
 
+// Results returns the query results as a map of string keys to interface{} values.
+// It allows users to access the outcomes of executed queries, facilitating data retrieval and manipulation.
 func (g *GeneratorQueryExecutor) Results() map[string]interface{} {
 	return g.QueryResults
 }
 
+// Kind returns the type of the query executor as a string.
+// It is used to identify the specific kind of query executor in various operations.
 func (l *GeneratorQueryExecutor) Kind() string {
 	return l.KindName
 }
 
+// IsComparable checks if the current GeneratorQueryExecutor is comparable to another QueryExecutor.
+// It validates the type and configuration of both executors, returning an error if they are not compatible.
 func (g *GeneratorQueryExecutor) IsComparable(otherQueryExecutor QueryExecutor) error {
 	otherType := reflect.TypeOf(otherQueryExecutor)
 
@@ -83,6 +95,8 @@ func (l *GeneratorQueryExecutor) compareQueries(other map[string]GeneratorQueryF
 	return nil
 }
 
+// Validate checks if the generator is set and if at least one query is provided.
+// It returns an error if either condition is not met, ensuring that the query executor is properly configured before execution.
 func (g *GeneratorQueryExecutor) Validate() error {
 	if g.Generator == nil {
 		return errors.New("generator is not set")
@@ -95,6 +109,8 @@ func (g *GeneratorQueryExecutor) Validate() error {
 	return nil
 }
 
+// Execute runs the defined queries using the generator's data, storing results for each query.
+// It validates the generator and its data, ensuring responses are available before execution.
 func (g *GeneratorQueryExecutor) Execute(_ context.Context) error {
 	if g.Generator == nil {
 		return errors.New("generator is not set")
@@ -130,6 +146,9 @@ func (g *GeneratorQueryExecutor) Execute(_ context.Context) error {
 	return nil
 }
 
+// TimeRange sets the time range for the query executor. 
+// It ensures that all responses are within the specified time range, 
+// although no action is needed if the generator already contains the correct data.
 func (g *GeneratorQueryExecutor) TimeRange(_, _ time.Time) {
 	// nothing to do here, since all responses stored in the generator are already in the right time range
 }
@@ -194,6 +213,9 @@ func (g *GeneratorQueryExecutor) standardQuery(standardMetric StandardLoadMetric
 	}
 }
 
+// MarshalJSON customizes the JSON encoding of the GeneratorQueryExecutor.
+// It serializes only the relevant fields, including query names and results,
+// making it suitable for efficient data transmission and storage in JSON format.
 func (g *GeneratorQueryExecutor) MarshalJSON() ([]byte, error) {
 	// we need custom marshalling to only include query names, since the functions are not serializable
 	type QueryExecutor struct {
@@ -222,6 +244,9 @@ func (g *GeneratorQueryExecutor) MarshalJSON() ([]byte, error) {
 	})
 }
 
+// UnmarshalJSON parses the JSON-encoded data and populates the GeneratorQueryExecutor fields.
+// It extracts generator configuration, queries, and query results, converting them to appropriate types.
+// This function is essential for initializing a GeneratorQueryExecutor from JSON data.
 func (g *GeneratorQueryExecutor) UnmarshalJSON(data []byte) error {
 	// helper struct with QueryExecutors as json.RawMessage and QueryResults as map[string]interface{}
 	// and as actual types

wasp/benchspy/loki.go

@@ -15,6 +15,8 @@ import (
 	"golang.org/x/sync/errgroup"
 )
 
+// NewLokiQueryExecutor initializes a LokiQueryExecutor with specified queries and configuration.
+// It returns a pointer to the newly created LokiQueryExecutor, enabling efficient querying of logs in a Loki instance.
 func NewLokiQueryExecutor(queries map[string]string, lokiConfig *wasp.LokiConfig) *LokiQueryExecutor {
 	return &LokiQueryExecutor{
 		KindName:     string(StandardQueryExecutor_Loki),
@@ -40,14 +42,20 @@ type LokiQueryExecutor struct {
 	Config *wasp.LokiConfig `json:"-"`
 }
 
+// Results returns the query results as a map of string keys to interface{} values.
+// It is useful for retrieving the output of executed queries in a structured format.
 func (l *LokiQueryExecutor) Results() map[string]interface{} {
 	return l.QueryResults
 }
 
+// Kind returns the type of the query executor as a string.
+// It is used to identify the specific kind of query executor in various operations.
 func (l *LokiQueryExecutor) Kind() string {
 	return l.KindName
 }
 
+// IsComparable checks if the current LokiQueryExecutor is of the same type as another QueryExecutor.
+// It ensures that the queries are structurally and semantically identical, returning an error if discrepancies are found.
 func (l *LokiQueryExecutor) IsComparable(otherQueryExecutor QueryExecutor) error {
 	otherType := reflect.TypeOf(otherQueryExecutor)
 
@@ -58,6 +66,9 @@ func (l *LokiQueryExecutor) IsComparable(otherQueryExecutor QueryExecutor) error
 	return l.compareQueries(otherQueryExecutor.(*LokiQueryExecutor).Queries)
 }
 
+// Validate checks if the LokiQueryExecutor has valid queries and configuration.
+// It returns an error if no queries are set or if the configuration is missing, 
+// ensuring that the executor is ready for execution.
 func (l *LokiQueryExecutor) Validate() error {
 	if len(l.Queries) == 0 {
 		return errors.New("there are no Loki queries, there's nothing to fetch. Please set them and try again")
@@ -69,6 +80,9 @@ func (l *LokiQueryExecutor) Validate() error {
 	return nil
 }
 
+// Execute runs the configured Loki queries concurrently and collects the results.
+// It validates the configuration, handles basic authentication, and manages errors during execution.
+// This function is essential for retrieving log data from Loki based on specified queries.
 func (l *LokiQueryExecutor) Execute(ctx context.Context) error {
 	var basicAuth client.LokiBasicAuth
 
@@ -159,11 +173,16 @@ func (l *LokiQueryExecutor) compareQueries(other map[string]string) error {
 	return nil
 }
 
+// TimeRange sets the start and end time for the Loki query execution.
+// This function is essential for defining the time window of the data to be queried.
 func (l *LokiQueryExecutor) TimeRange(start, end time.Time) {
 	l.StartTime = start
 	l.EndTime = end
 }
 
+// UnmarshalJSON parses the JSON-encoded data and populates the LokiQueryExecutor fields.
+// It converts the query results from a generic map to a specific type map, ensuring type safety.
+// This function is essential for handling JSON data in a structured manner.
 func (l *LokiQueryExecutor) UnmarshalJSON(data []byte) error {
 	// helper struct with QueryResults map[string]interface{}
 	type Alias LokiQueryExecutor
@@ -188,6 +207,9 @@ func (l *LokiQueryExecutor) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+// NewStandardMetricsLokiExecutor creates a LokiQueryExecutor configured with standard queries 
+// based on the provided test and generator details. It facilitates querying metrics from Loki 
+// for performance analysis within a specified time range.
 func NewStandardMetricsLokiExecutor(lokiConfig *wasp.LokiConfig, testName, generatorName, branch, commit string, startTime, endTime time.Time) (*LokiQueryExecutor, error) {
 	lq := &LokiQueryExecutor{
 		KindName:     string(StandardQueryExecutor_Loki),

wasp/benchspy/metrics.go

@@ -6,6 +6,8 @@ import (
 	"strconv"
 )
 
+// CalculatePercentile computes the specified percentile of a slice of numbers.
+// It is useful for statistical analysis, allowing users to determine the value below which a given percentage of observations fall.
 func CalculatePercentile(numbers []float64, percentile float64) float64 {
 	// Sort the slice
 	sort.Float64s(numbers)
@@ -31,6 +33,8 @@ func CalculatePercentile(numbers []float64, percentile float64) float64 {
 	return numbers[lowerIndex]*(1-weight) + numbers[upperIndex]*weight
 }
 
+// StringSliceToFloat64Slice converts a slice of strings to a slice of float64 values.
+// It returns an error if any string cannot be parsed as a float64.
 func StringSliceToFloat64Slice(s []string) ([]float64, error) {
 	numbers := make([]float64, len(s))
 	for i, str := range s {

wasp/benchspy/prometheus.go

@@ -22,6 +22,8 @@ type PrometheusConfig struct {
 
 const PrometheusUrlEnvVar = "PROMETHEUS_URL"
 
+// NewPrometheusConfig creates a new PrometheusConfig instance with the specified name regex patterns.
+// It retrieves the Prometheus URL from the environment and is useful for configuring Prometheus query execution.
 func NewPrometheusConfig(nameRegexPatterns ...string) *PrometheusConfig {
 	return &PrometheusConfig{
 		Url:               os.Getenv(PrometheusUrlEnvVar),
@@ -56,6 +58,8 @@ func NewPrometheusQueryExecutor(queries map[string]string, config PrometheusConf
 	}, nil
 }
 
+// NewStandardPrometheusQueryExecutor creates a PrometheusQueryExecutor with standard queries based on the provided time range and configuration.
+// It generates queries for each name regex pattern and returns the executor or an error if the generation fails.
 func NewStandardPrometheusQueryExecutor(startTime, endTime time.Time, config PrometheusConfig) (*PrometheusQueryExecutor, error) {
 	p := &PrometheusQueryExecutor{}
 
@@ -74,6 +78,8 @@ func NewStandardPrometheusQueryExecutor(startTime, endTime time.Time, config Pro
 	return NewPrometheusQueryExecutor(standardQueries, config)
 }
 
+// Execute runs a series of Prometheus queries concurrently, collecting results and warnings.
+// It returns an error if any query fails, allowing for efficient data retrieval in reporting tasks.
 func (r *PrometheusQueryExecutor) Execute(ctx context.Context) error {
 	for name, query := range r.Queries {
 		result, warnings, queryErr := r.client.Query(ctx, query, r.EndTime)
@@ -91,14 +97,22 @@ func (r *PrometheusQueryExecutor) Execute(ctx context.Context) error {
 	return nil
 }
 
+// Results returns the query results as a map of string to interface{}.
+// It allows users to access the results of executed queries, facilitating data retrieval and manipulation.
 func (r *PrometheusQueryExecutor) Results() map[string]interface{} {
 	return r.QueryResults
 }
 
+// Kind returns the type of the query executor as a string.
+// It is used to identify the specific implementation of a query executor, 
+// enabling filtering and processing of results based on their executor type.
 func (l *PrometheusQueryExecutor) Kind() string {
 	return l.KindName
 }
 
+// Validate checks the Prometheus query executor's configuration for correctness.
+// It ensures that the Prometheus client is initialized and that at least one query is provided.
+// It returns an error if any validation checks fail, helping to prevent execution issues.
 func (r *PrometheusQueryExecutor) Validate() error {
 	if r.client == nil {
 		return errors.New("prometheus client is nil")
@@ -111,6 +125,8 @@ func (r *PrometheusQueryExecutor) Validate() error {
 	return nil
 }
 
+// IsComparable checks if the provided QueryExecutor is of the same type as the receiver.
+// It returns an error if the types do not match, ensuring type safety for query comparisons.
 func (r *PrometheusQueryExecutor) IsComparable(other QueryExecutor) error {
 	otherType := reflect.TypeOf(other)
 	if otherType != reflect.TypeOf(r) {
@@ -141,10 +157,15 @@ func (r *PrometheusQueryExecutor) compareQueries(other map[string]string) error
 	return nil
 }
 
+// Warnings returns a map of warnings encountered during query execution.
+// This function is useful for retrieving any issues that may have arisen,
+// allowing users to handle or log them appropriately.
 func (r *PrometheusQueryExecutor) Warnings() map[string]v1.Warnings {
 	return r.warnings
 }
 
+// MustResultsAsValue retrieves the query results as a map of metric names to their corresponding values.
+// It ensures that the results are in a format compatible with further processing or serialization.
 func (r *PrometheusQueryExecutor) MustResultsAsValue() map[string]model.Value {
 	results := make(map[string]model.Value)
 	for name, result := range r.QueryResults {
@@ -180,6 +201,8 @@ func (r *PrometheusQueryExecutor) MustResultsAsValue() map[string]model.Value {
 	return results
 }
 
+// TimeRange sets the start and end time for the Prometheus query execution.
+// This function is essential for defining the time window for data retrieval in monitoring and analytics tasks.
 func (r *PrometheusQueryExecutor) TimeRange(startTime, endTime time.Time) {
 	r.StartTime = startTime
 	r.EndTime = endTime
@@ -222,6 +245,9 @@ type TypedMetric struct {
 	MetricType string      `json:"metric_type"`
 }
 
+// MarshalJSON customizes the JSON representation of the PrometheusQueryExecutor.
+// It includes only essential fields: Kind, Queries, and simplified QueryResults,
+// making it useful for efficient data transfer and storage in JSON format.
 func (g *PrometheusQueryExecutor) MarshalJSON() ([]byte, error) {
 	// we need custom marshalling to only include some parts of the metrics
 	type QueryExecutor struct {
@@ -248,6 +274,9 @@ func (g *PrometheusQueryExecutor) MarshalJSON() ([]byte, error) {
 	return json.Marshal(q)
 }
 
+// UnmarshalJSON decodes JSON data into a PrometheusQueryExecutor instance.
+// It populates the QueryResults field with the appropriate metric types,
+// enabling structured access to the results of Prometheus queries.
 func (r *PrometheusQueryExecutor) UnmarshalJSON(data []byte) error {
 	// helper struct with QueryResults map[string]interface{}
 	type Alias PrometheusQueryExecutor