Add sparse trait information

Author: JordonPhillips

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/generators/MemberGenerator.java

@@ -14,6 +14,7 @@
 import software.amazon.smithy.docgen.core.DocGenerationContext;
 import software.amazon.smithy.docgen.core.DocSymbolProvider;
 import software.amazon.smithy.docgen.core.sections.MemberSection;
+import software.amazon.smithy.docgen.core.sections.ShapeDetailsSection;
 import software.amazon.smithy.docgen.core.sections.ShapeMembersSection;
 import software.amazon.smithy.docgen.core.sections.ShapeSubheadingSection;
 import software.amazon.smithy.docgen.core.writers.DocWriter;
@@ -112,6 +113,7 @@ public void run() {
 
                 writer.injectSection(new ShapeSubheadingSection(context, member));
                 writer.writeShapeDocs(member, context.model());
+                writer.injectSection(new ShapeDetailsSection(context, member));
                 writer.closeDefinitionListItem();
                 writer.popState();
             }

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/integrations/BuiltinsIntegration.java

@@ -24,6 +24,7 @@
 import software.amazon.smithy.docgen.core.interceptors.RecommendedInterceptor;
 import software.amazon.smithy.docgen.core.interceptors.SensitiveInterceptor;
 import software.amazon.smithy.docgen.core.interceptors.SinceInterceptor;
+import software.amazon.smithy.docgen.core.interceptors.SparseInterceptor;
 import software.amazon.smithy.docgen.core.interceptors.UniqueItemsInterceptor;
 import software.amazon.smithy.docgen.core.interceptors.UnstableInterceptor;
 import software.amazon.smithy.docgen.core.writers.DocWriter;
@@ -69,6 +70,7 @@ public List<? extends CodeInterceptor<? extends CodeSection, DocWriter>> interce
         return List.of(
                 new NoReplaceBindingInterceptor(),
                 new NoReplaceOperationInterceptor(),
+                new SparseInterceptor(),
                 new UniqueItemsInterceptor(),
                 new PatternInterceptor(),
                 new RangeInterceptor(),

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/interceptors/SparseInterceptor.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.docgen.core.interceptors;
+
+import java.util.Locale;
+import software.amazon.smithy.docgen.core.sections.ShapeDetailsSection;
+import software.amazon.smithy.docgen.core.writers.DocWriter;
+import software.amazon.smithy.docgen.core.writers.DocWriter.AdmonitionType;
+import software.amazon.smithy.model.traits.SparseTrait;
+import software.amazon.smithy.utils.CodeInterceptor;
+import software.amazon.smithy.utils.SmithyInternalApi;
+
+/**
+ * Adds an admonition to shapes that have the
+ * <a href="https://smithy.io/2.0/spec/type-refinement-traits.html#sparse-trait">
+ * sparse trait</a>.
+ */
+@SmithyInternalApi
+public final class SparseInterceptor implements CodeInterceptor<ShapeDetailsSection, DocWriter> {
+    @Override
+    public Class<ShapeDetailsSection> sectionType() {
+        return ShapeDetailsSection.class;
+    }
+
+    @Override
+    public boolean isIntercepted(ShapeDetailsSection section) {
+        return section.shape().getMemberTrait(section.context().model(), SparseTrait.class).isPresent();
+    }
+
+    @Override
+    public void write(DocWriter writer, String previousText, ShapeDetailsSection section) {
+        var target = section.shape().isMemberShape()
+                ? section.context().model().expectShape(section.shape().asMemberShape().get().getTarget())
+                : section.shape();
+        writer.writeWithNoFormatting(previousText);
+        writer.openAdmonition(AdmonitionType.NOTE);
+        writer.write("This $L may contain null values.", target.getType().toString().toLowerCase(Locale.ENGLISH));
+        writer.closeAdmonition();
+    }
+}

smithy-docgen-test/model/main.smithy

@@ -133,6 +133,8 @@ list StringSet {
     member: String
 }
 
+/// A string map that allows null values.
+@sparse
 @length(max: 16)
 map StringMap {
     key: String