Add explanatory comments

Signed-off-by: Arianna Vespri <[email protected]>

Author: vesari

expfmt/openmetrics_create.go

@@ -52,8 +52,14 @@ import (
 //     its type will be set to `unknown` in that case to avoid invalid OpenMetrics
 //     output.
 //
-//   - The `# UNIT` line is optional, but if populated, the unit has to be present in the metric
-//     name as its suffix (see https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#unit)
+//   - According to the OM specs, the `# UNIT` line is optional, but if populated,
+//     the unit has to be present in the metric name as its suffix:
+//     (see https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#unit).
+//     However, in order to accomodate any potential scenario where such a change in the
+//     metric name is not desirable, the users are here given the choice of either explicitly
+//     opt in, in case they wish for the unit to be included in the output AND in the metric name
+//     as a suffix (see the description of the ToOpenMetricsWithUnit function below),
+//     or not to opt in, in case they don't want for any of that to happen.
 //
 //   - No support for the following (optional) features: `_created`
 //     line, info type, stateset type, gaugehistogram type.
@@ -66,11 +72,16 @@ import (
 
 type ToOpenMetrics struct {
 	withUnit bool
-	// withCreated bool can be added in the future
+	// withCreated bool can be added in the future.
 }
 
 type ToOpenMetricsOption = func(*ToOpenMetrics)
 
+// ToOpenMetricsWithUnit is meant to be called as an optional argument in the MetricFamilyToOpenMetrics
+// function. It enables a set unit to be written to the output and to be added to the metric name, (if
+// it's not there already), as a suffix. Without opting in this way, the unit will not be added to the
+// metric name and, on top of that, the unit will not be passed onto the output, even if it were declared
+// in the *dto.MetricFamily struct, i.e. even if in.Unit !=nil.
 func ToOpenMetricsWithUnit() ToOpenMetricsOption {
 	return func(om *ToOpenMetrics) {
 		om.withUnit = true

expfmt/openmetrics_create_test.go

@@ -545,6 +545,34 @@ func TestCreateOpenMatricsWithUnit(t *testing.T) {
 			out: `# HELP name_seconds doc string
 # TYPE name_seconds counter
 # UNIT name_seconds seconds
+`,
+		},
+		// 3: No metric plus unit wrong unit in name. // Can this happen at all?
+		{
+			in: &dto.MetricFamily{
+				Name:   proto.String("name_milliseconds_total"),
+				Help:   proto.String("doc string"),
+				Type:   dto.MetricType_COUNTER.Enum(),
+				Unit:   proto.String("seconds"),
+				Metric: []*dto.Metric{},
+			},
+			out: `# HELP name_milliseconds_seconds doc string
+# TYPE name_milliseconds_seconds counter
+# UNIT name_milliseconds_seconds seconds
+`,
+		},
+		// 3: No metric plus unit already in name.
+		{
+			in: &dto.MetricFamily{
+				Name:   proto.String("name_seconds_total"),
+				Help:   proto.String("doc string"),
+				Type:   dto.MetricType_COUNTER.Enum(),
+				Unit:   proto.String("seconds"),
+				Metric: []*dto.Metric{},
+			},
+			out: `# HELP name_seconds doc string
+# TYPE name_seconds counter
+# UNIT name_seconds seconds
 `,
 		},
 	}