[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 supplied and that it is associated with a testing.T instance. 
+// This function is essential for initializing data required for generating reports or executing tests.
 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,10 @@ func NewBasicData(commitOrTag string, generators ...*wasp.Generator) (*BasicData
 	return b, nil
 }
 
+// FillStartEndTimes calculates and sets the earliest start time and latest end time 
+// from the generator configurations. It ensures that all segments have valid start and 
+// end times, returning an error if any are missing. This function is essential for 
+// establishing the time range for tests based on generator schedules.
 func (b *BasicData) FillStartEndTimes() error {
 	earliestTime := time.Now()
 	var latestTime time.Time
@@ -89,6 +98,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.
 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 +116,10 @@ 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 any discrepancies are found. This function is useful for ensuring
+// consistency between data reports before processing or comparison.
 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,8 @@ type GeneratorQueryExecutor struct {
 	QueryResults map[string]interface{}      `json:"query_results"`
 }
 
+// NewGeneratorQueryExecutor creates a new GeneratorQueryExecutor instance using the provided generator.
+// It initializes standard queries and prepares the executor for handling query results, returning any errors encountered.
 func NewGeneratorQueryExecutor(generator *wasp.Generator) (*GeneratorQueryExecutor, error) {
 	g := &GeneratorQueryExecutor{
 		KindName:  string(StandardQueryExecutor_Generator),
@@ -37,14 +39,20 @@ func NewGeneratorQueryExecutor(generator *wasp.Generator) (*GeneratorQueryExecut
 	return g, nil
 }
 
+// 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 (g *GeneratorQueryExecutor) Results() map[string]interface{} {
 	return g.QueryResults
 }
 
+// Kind returns the type of the query executor as a string.
+// It is useful for identifying the specific kind of executor being used 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)
 
@@ -76,6 +84,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")
@@ -88,6 +98,9 @@ func (g *GeneratorQueryExecutor) Validate() error {
 	return nil
 }
 
+// Execute runs the defined queries on the generator's data, aggregating results for each query. 
+// It returns an error if the generator is not set, lacks data, or if any query execution fails. 
+// This function is essential for processing and retrieving results from multiple queries concurrently.
 func (g *GeneratorQueryExecutor) Execute(_ context.Context) error {
 	if g.Generator == nil {
 		return errors.New("generator is not set")
@@ -123,6 +136,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
 }
@@ -183,6 +199,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 {
@@ -211,6 +230,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 the 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 prepares the executor to handle queries against a Loki instance, facilitating efficient log retrieval.
 func NewLokiQueryExecutor(queries map[string]string, lokiConfig *wasp.LokiConfig) *LokiQueryExecutor {
 	return &LokiQueryExecutor{
 		KindName:     string(StandardQueryExecutor_Loki),
@@ -40,14 +42,21 @@ type LokiQueryExecutor struct {
 	Config *wasp.LokiConfig `json:"-"`
 }
 
+// Results returns the query results as a map of string to interface{}.
+// It allows users to access the results of executed queries, facilitating further processing or type assertions.
 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 contexts.
 func (l *LokiQueryExecutor) Kind() string {
 	return l.KindName
 }
 
+// IsComparable checks if the current LokiQueryExecutor is of the same type as another QueryExecutor.
+// It validates the queries for equivalence, ensuring they match in count and content. 
+// This function is useful for comparing query executors in reporting scenarios.
 func (l *LokiQueryExecutor) IsComparable(otherQueryExecutor QueryExecutor) error {
 	otherType := reflect.TypeOf(otherQueryExecutor)
 
@@ -58,6 +67,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 +81,9 @@ func (l *LokiQueryExecutor) Validate() error {
 	return nil
 }
 
+// Execute runs multiple Loki queries concurrently and collects their results.
+// It validates the configuration, handles authentication, and manages errors.
+// This function is essential for retrieving logs from Loki based on specified queries and time ranges.
 func (l *LokiQueryExecutor) Execute(ctx context.Context) error {
 	var basicAuth client.LokiBasicAuth
 
@@ -159,11 +174,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 decodes JSON data into a LokiQueryExecutor instance.
+// It populates the QueryResults field with a typed map from the raw JSON input,
+// enabling structured access to query results for further processing.
 func (l *LokiQueryExecutor) UnmarshalJSON(data []byte) error {
 	// helper struct with QueryResults map[string]interface{}
 	type Alias LokiQueryExecutor
@@ -188,6 +208,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 and monitoring during tests.
 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 value at a specified percentile from a slice of numbers.
+// It is useful for statistical analysis, allowing users to determine thresholds or benchmarks in data sets.
 func CalculatePercentile(numbers []float64, percentile float64) float64 {
 	// Sort the slice
 	sort.Float64s(numbers)
@@ -31,6 +33,9 @@ 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. This function is useful
+// for data processing where numeric values are represented as strings.
 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 executors.
 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 simplifies the setup of query execution for Prometheus by generating queries that match specified name patterns.
 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 the defined Prometheus queries concurrently, collecting results and warnings.
+// It returns an error if any query fails, allowing for efficient data retrieval and error handling.
 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,20 @@ 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 outcomes of executed queries, facilitating further processing or analysis of the data.
 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 kind of query executor in a collection.
 func (l *PrometheusQueryExecutor) Kind() string {
 	return l.KindName
 }
 
+// Validate checks the Prometheus client and the provided queries for correctness.
+// It returns an error if the client is nil or if no queries are specified, ensuring that the executor is properly configured before execution.
 func (r *PrometheusQueryExecutor) Validate() error {
 	if r.client == nil {
 		return errors.New("prometheus client is nil")
@@ -111,6 +123,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 +155,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 address potential problems in their queries.
 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 all results are converted to a common value type, facilitating 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 +199,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, ensuring accurate and relevant results.
 func (r *PrometheusQueryExecutor) TimeRange(startTime, endTime time.Time) {
 	r.StartTime = startTime
 	r.EndTime = endTime
@@ -222,6 +243,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.
+// This function is useful for serializing the executor's state in a concise format.
 func (g *PrometheusQueryExecutor) MarshalJSON() ([]byte, error) {
 	// we need custom marshalling to only include some parts of the metrics
 	type QueryExecutor struct {
@@ -248,6 +272,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 query results for further processing.
 func (r *PrometheusQueryExecutor) UnmarshalJSON(data []byte) error {
 	// helper struct with QueryResults map[string]interface{}
 	type Alias PrometheusQueryExecutor