Add some comments

Signed-off-by: Federico Torres <[email protected]>

Author: fedetorres93

prometheus-metrics-exposition-formats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetricsTextFormatWriter.java

@@ -272,6 +272,8 @@ private void writeNameAndLabels(OutputStreamWriter writer, String name, String s
     private void writeNameAndLabels(OutputStreamWriter writer, String name, String suffix, Labels labels,
                                     String additionalLabelName, double additionalLabelValue) throws IOException {
         boolean metricInsideBraces = false;
+        // If the name does not pass the legacy validity check, we must put the
+        // metric name inside the braces.
         if (PrometheusNaming.validateLegacyMetricName(name) != null) {
             metricInsideBraces = true;
             writer.write('{');

prometheus-metrics-exposition-formats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusTextFormatWriter.java

@@ -278,6 +278,8 @@ private void writeNameAndLabels(OutputStreamWriter writer, String name, String s
     private void writeNameAndLabels(OutputStreamWriter writer, String name, String suffix, Labels labels,
                                     String additionalLabelName, double additionalLabelValue) throws IOException {
         boolean metricInsideBraces = false;
+        // If the name does not pass the legacy validity check, we must put the
+        // metric name inside the braces.
         if (PrometheusNaming.validateLegacyMetricName(name) != null) {
             metricInsideBraces = true;
             writer.write('{');

prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/EscapingScheme.java

@@ -4,9 +4,19 @@
 import static io.prometheus.metrics.model.snapshots.PrometheusNaming.nameEscapingScheme;
 
 public enum EscapingScheme {
+    // NO_ESCAPING indicates that a name will not be escaped.
     NO_ESCAPING("allow-utf-8"),
+
+    // UNDERSCORE_ESCAPING replaces all legacy-invalid characters with underscores.
     UNDERSCORE_ESCAPING("underscores"),
+
+    // DOTS_ESCAPING is similar to UNDERSCORE_ESCAPING, except that dots are
+    // converted to `_dot_` and pre-existing underscores are converted to `__`.
     DOTS_ESCAPING("dots"),
+
+    // VALUE_ENCODING_ESCAPING prepends the name with `U__` and replaces all invalid
+    // characters with the Unicode value, surrounded by underscores. Single
+    // underscores are replaced with double underscores.
     VALUE_ENCODING_ESCAPING("values"),
     ;
 
@@ -20,6 +30,10 @@ public final String getValue() {
         this.value = value;
     }
 
+    // fromAcceptHeader returns an EscapingScheme depending on the Accept header. Iff the
+    // header contains an escaping=allow-utf-8 term, it will select NO_ESCAPING. If a valid
+    // "escaping" term exists, that will be used. Otherwise, the global default will
+    // be returned.
     public static EscapingScheme fromAcceptHeader(String acceptHeader) {
         for (String p : acceptHeader.split(";")) {
             String[] toks = p.split("=");
@@ -32,6 +46,7 @@ public static EscapingScheme fromAcceptHeader(String acceptHeader) {
                 try {
                     return EscapingScheme.forString(value);
                 } catch (IllegalArgumentException e) {
+                    // If the escaping parameter is unknown, ignore it.
                     return nameEscapingScheme;
                 }
             }

prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/PrometheusNaming.java

@@ -18,10 +18,23 @@
  * in Prometheus exposition formats. However, if metrics are exposed in OpenTelemetry format the dots are retained.
  */
 public class PrometheusNaming {
+    // nameValidationScheme determines the method of name validation to be used by
+    // all calls to validateMetricName() and isValidMetricName(). Setting UTF-8 mode
+    // in isolation from other components that don't support UTF-8 may result in
+    // bugs or other undefined behavior. This value is intended to be set by
+    // UTF-8-aware binaries as part of their startup via a properties file.
     public static ValidationScheme nameValidationScheme = initValidationScheme();
 
+    // nameEscapingScheme defines the default way that names will be
+    // escaped when presented to systems that do not support UTF-8 names. If the
+    // Accept "escaping" term is specified, that will override this value.
     public static EscapingScheme nameEscapingScheme = EscapingScheme.VALUE_ENCODING_ESCAPING;
 
+    // ESCAPING_KEY is the key in an Accept header that defines how
+    // metric and label names that do not conform to the legacy character
+    // requirements should be escaped when being scraped by a legacy Prometheus
+    // system. If a system does not explicitly pass an escaping parameter in the
+    // Accept header, the default nameEscapingScheme will be used.
     public static final String ESCAPING_KEY = "escaping";
 
     private static final String LOWERHEX = "0123456789abcdef";
@@ -258,6 +271,8 @@ private static String replaceIllegalCharsInLabelName(String name) {
         return new String(sanitized);
     }
 
+    // escapeMetricSnapshot escapes the given metric names and labels with the given
+    // escaping scheme.
     public static MetricSnapshot escapeMetricSnapshot(MetricSnapshot v, EscapingScheme scheme) {
         if (v == null) {
             return null;
@@ -269,6 +284,7 @@ public static MetricSnapshot escapeMetricSnapshot(MetricSnapshot v, EscapingSche
 
         String outName;
 
+        // If the name is null, copy as-is, don't try to escape.
         if (v.getMetadata().getPrometheusName() == null || isValidLegacyMetricName(v.getMetadata().getPrometheusName())) {
             outName = v.getMetadata().getPrometheusName();
         } else {
@@ -453,6 +469,10 @@ static boolean metricNeedsEscaping(DataPointSnapshot d) {
         return false;
     }
 
+    // escapeName escapes the incoming name according to the provided escaping
+    // scheme. Depending on the rules of escaping, this may cause no change in the
+    // string that is returned (especially NO_ESCAPING, which by definition is a
+    // noop). This method does not do any validation of the name.
     static String escapeName(String name, EscapingScheme scheme) {
         if (name.isEmpty()) {
             return name;
@@ -475,6 +495,7 @@ static String escapeName(String name, EscapingScheme scheme) {
                 }
                 return escaped.toString();
             case DOTS_ESCAPING:
+                // Do not early return for legacy valid names, we still escape underscores.
                 for (int i = 0; i < name.length(); i++) {
                     char c = name.charAt(i);
                     if (c == '_') {
@@ -519,6 +540,9 @@ static String escapeName(String name, EscapingScheme scheme) {
         }
     }
 
+    // unescapeName unescapes the incoming name according to the provided escaping
+    // scheme if possible. Some schemes are partially or totally non-roundtripable.
+    // If any error is encountered, returns the original input.
     static String unescapeName(String name, EscapingScheme scheme) {
         if (name.isEmpty()) {
             return name;

prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/ValidationScheme.java

@@ -1,6 +1,13 @@
 package io.prometheus.metrics.model.snapshots;
 
+// ValidationScheme is an enum for determining how metric and label names will
+// be validated by this library.
 public enum ValidationScheme {
+    // LEGACY_VALIDATION is a setting that requires that metric and label names
+    // conform to the original character requirements.
     LEGACY_VALIDATION,
+
+    // UTF_8_VALIDATION only requires that metric and label names be valid UTF-8
+    // strings.
     UTF_8_VALIDATION
 }