Allow optional documentations for tag enumerations (#1021)

Allow optional documentations for tag enumerations

metric-schema-api/src/main/conjure/metric-schema-api.yml

@@ -44,3 +44,4 @@ types:
       TagValue:
         fields:
           value: string
+          docs: optional<Documentation>

metric-schema-java/src/main/java/com/palantir/metric/schema/UtilityGenerator.java

@@ -315,10 +315,11 @@ private static void generateConstants(
     private static void generateTagEnum(
             TypeSpec.Builder builder, String metricName, ImplementationVisibility visibility, TagDefinition tagDef) {
         TypeSpec.Builder enumBuilder = TypeSpec.enumBuilder(getTagClassName(metricName, tagDef));
-        tagDef.getValues()
-                .forEach(value -> enumBuilder.addEnumConstant(
-                        Custodian.anyToUpperUnderscore(value.getValue()),
-                        TypeSpec.anonymousClassBuilder("$S", value.getValue()).build()));
+        tagDef.getValues().forEach(value -> {
+            TypeSpec.Builder tagValueBuilder = TypeSpec.anonymousClassBuilder("$S", value.getValue());
+            value.getDocs().map(Javadoc::render).ifPresent(tagValueBuilder::addJavadoc);
+            enumBuilder.addEnumConstant(Custodian.anyToUpperUnderscore(value.getValue()), tagValueBuilder.build());
+        });
 
         builder.addType(enumBuilder
                 .addModifiers(visibility.apply())

metric-schema-java/src/test/resources/constant-tags.yml

@@ -8,7 +8,10 @@ namespaces:
         tags:
           - name: result
             docs: The result of processing
-            values: [success, failure]
+            values:
+              - value: success
+                docs: Successful installations processed
+              - failure
           - type
           - name: locator
             values: [ package:identifier ]

metric-schema-lang/src/main/java/com/palantir/metric/schema/lang/LangConverter.java

@@ -56,10 +56,19 @@ private static List<TagDefinition> convert(List<com.palantir.metric.schema.lang.
                 .map(tag -> TagDefinition.builder()
                         .name(tag.name())
                         .docs(tag.docs().map(Documentation::of))
-                        .values(tag.values().stream().map(TagValue::of).collect(ImmutableList.toImmutableList()))
+                        .values(tag.values().stream()
+                                .map(LangConverter::convert)
+                                .collect(ImmutableList.toImmutableList()))
                         .build())
                 .collect(ImmutableList.toImmutableList());
     }
 
+    private static TagValue convert(com.palantir.metric.schema.lang.TagValue tagValue) {
+        return TagValue.builder()
+                .value(tagValue.value())
+                .docs(tagValue.docs().map(Documentation::of))
+                .build();
+    }
+
     private LangConverter() {}
 }

metric-schema-lang/src/main/java/com/palantir/metric/schema/lang/TagDefinition.java

@@ -33,7 +33,7 @@ public interface TagDefinition {
 
     Optional<String> docs();
 
-    List<String> values();
+    List<TagValue> values();
 
     final class TagDefinitionDeserializer extends JsonDeserializer<TagDefinition> {
         @Override

metric-schema-lang/src/main/java/com/palantir/metric/schema/lang/TagValue.java

@@ -0,0 +1,45 @@
+/*
+ * (c) Copyright 2023 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.metric.schema.lang;
+
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.core.JsonToken;
+import com.fasterxml.jackson.databind.DeserializationContext;
+import com.fasterxml.jackson.databind.JsonDeserializer;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import java.io.IOException;
+import java.util.Optional;
+import org.immutables.value.Value.Immutable;
+
+@Immutable
+@JsonDeserialize(using = TagValue.TagValueDeserializer.class)
+public interface TagValue {
+    String value();
+
+    Optional<String> docs();
+
+    final class TagValueDeserializer extends JsonDeserializer<TagValue> {
+        @Override
+        public TagValue deserialize(JsonParser parser, DeserializationContext _ctxt) throws IOException {
+            if (parser.currentToken() == JsonToken.VALUE_STRING) {
+                String value = parser.getValueAsString();
+                return ImmutableTagValue.builder().value(value).build();
+            }
+            return ImmutableTagValue.fromJson(parser.readValueAs(ImmutableTagValue.Json.class));
+        }
+    }
+}

metric-schema-markdown/src/main/java/com/palantir/metric/schema/markdown/MarkdownRenderer.java

@@ -30,6 +30,7 @@
 import java.util.Locale;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Optional;
 import java.util.stream.Collectors;
 import org.apache.commons.lang3.StringUtils;
 
@@ -106,23 +107,38 @@ private static void renderLine(
                 .append(metric.getDocs().get())
                 .append('\n');
         if (hasComplexTags) {
-            allTags.forEach(tagDefinition -> {
-                output.append("  - `").append(tagDefinition.getName()).append("`");
-                if (!tagDefinition.getValues().isEmpty()) {
-                    output.append(" values ")
-                            .append(tagDefinition.getValues().stream()
-                                    .map(TagValue::getValue)
-                                    .sorted()
-                                    .collect(Collectors.joining("`,`", "(`", "`)")));
-                }
-                tagDefinition.getDocs().ifPresent(docs -> {
-                    output.append(": ").append(docs);
-                });
-                output.append("\n");
-            });
+            renderComplexTags(allTags, output);
         }
     }
 
+    private static void renderComplexTags(List<TagDefinition> tagDefinitions, StringBuilder output) {
+        tagDefinitions.forEach(tagDefinition -> {
+            boolean hasEnumValueDocs =
+                    tagDefinition.getValues().stream().map(TagValue::getDocs).anyMatch(Optional::isPresent);
+
+            output.append("  - `").append(tagDefinition.getName()).append("`");
+            if (!tagDefinition.getValues().isEmpty() && !hasEnumValueDocs) {
+                output.append(" values ")
+                        .append(tagDefinition.getValues().stream()
+                                .map(TagValue::getValue)
+                                .collect(Collectors.joining("`,`", "(`", "`)")));
+            }
+
+            tagDefinition.getDocs().ifPresent(docs -> {
+                output.append(": ").append(docs);
+            });
+            output.append("\n");
+
+            if (hasEnumValueDocs) {
+                tagDefinition.getValues().forEach(value -> {
+                    output.append(String.format("    - `%s`", value.getValue()));
+                    value.getDocs().ifPresent(docs -> output.append(String.format(": %s", docs)));
+                    output.append("\n");
+                });
+            }
+        });
+    }
+
     private static ImmutableList<Section> namespaces(String localCoordinate, Map<String, List<MetricSchema>> schemas) {
         return schemas.entrySet().stream()
                 .sorted(Map.Entry.comparingByKey(new CoordinateComparator(localCoordinate)))

metric-schema-markdown/src/test/java/com/palantir/metric/schema/markdown/MarkdownRendererTest.java

@@ -203,13 +203,25 @@ void testComplexTagged() {
                                                 .type(MetricType.METER)
                                                 .tagDefinitions(TagDefinition.builder()
                                                         .name("result")
-                                                        .values(TagValue.of("success"))
-                                                        .values(TagValue.of("failure"))
+                                                        .values(TagValue.of(
+                                                                "success", Documentation.of("This is a success enum")))
+                                                        .values(TagValue.builder()
+                                                                .value("failure")
+                                                                .build())
                                                         .build())
                                                 .tagDefinitions(TagDefinition.builder()
                                                         .name("endpoint")
                                                         .docs(Documentation.of("Some docs"))
                                                         .build())
+                                                .tagDefinitions(TagDefinition.builder()
+                                                        .name("processing")
+                                                        .values(TagValue.builder()
+                                                                .value("foo")
+                                                                .build())
+                                                        .values(TagValue.builder()
+                                                                .value("bar")
+                                                                .build())
+                                                        .build())
                                                 .docs(Documentation.of("metric docs"))
                                                 .build())
                                 .build())
@@ -227,8 +239,11 @@ void testComplexTagged() {
                         + "namespace docs\n"
                         + "- `namespace.metric` (meter): metric docs\n"
                         + "  - `namespaceTag`\n"
-                        + "  - `result` values (`failure`,`success`)\n"
-                        + "  - `endpoint`: Some docs");
+                        + "  - `result`\n"
+                        + "    - `success`: This is a success enum\n"
+                        + "    - `failure`\n"
+                        + "  - `endpoint`: Some docs\n"
+                        + "  - `processing` values (`foo`,`bar`)");
     }
 
     @Test