Update javadoc integration to support non-shape sections (#563)

codegen/core/src/main/java/software/amazon/smithy/java/codegen/integrations/javadoc/BuilderSetterDocumentationInterceptor.java

@@ -19,10 +19,10 @@ final class BuilderSetterDocumentationInterceptor implements CodeInterceptor.App
 
     @Override
     public void append(JavaWriter writer, JavadocSection section) {
-        if (section.shape().hasTrait(RequiredTrait.class)) {
+        if (section.targetedShape().hasTrait(RequiredTrait.class)) {
             writer.writeWithNoFormatting("<p><strong>Required</strong>");
         }
-        if (section.shape().hasTrait(RecommendedTrait.class)) {
+        if (section.targetedShape().hasTrait(RecommendedTrait.class)) {
             writer.writeWithNoFormatting("<p><strong>Recommended</strong>");
         }
         writer.writeWithNoFormatting("@return this builder.");

codegen/core/src/main/java/software/amazon/smithy/java/codegen/integrations/javadoc/DeprecatedTraitInterceptor.java

@@ -17,7 +17,7 @@ final class DeprecatedTraitInterceptor implements CodeInterceptor.Appender<Javad
 
     @Override
     public void append(JavaWriter writer, JavadocSection section) {
-        var trait = section.shape().expectTrait(DeprecatedTrait.class);
+        var trait = section.targetedShape().expectTrait(DeprecatedTrait.class);
         writer.putContext("since", trait.getSince());
         writer.write("@deprecated ${?since}As of ${since:L}. ${/since}$L", trait.getMessage());
     }
@@ -29,6 +29,6 @@ public Class<JavadocSection> sectionType() {
 
     @Override
     public boolean isIntercepted(JavadocSection section) {
-        return section.shape().hasTrait(DeprecatedTrait.class);
+        return section.targetedShape() != null && section.targetedShape().hasTrait(DeprecatedTrait.class);
     }
 }

codegen/core/src/main/java/software/amazon/smithy/java/codegen/integrations/javadoc/DocumentationTraitInterceptor.java

@@ -19,7 +19,7 @@ final class DocumentationTraitInterceptor implements CodeInterceptor<JavadocSect
 
     @Override
     public void write(JavaWriter writer, String previousText, JavadocSection section) {
-        writer.writeWithNoFormatting(section.shape().expectTrait(DocumentationTrait.class).getValue());
+        writer.writeWithNoFormatting(section.targetedShape().expectTrait(DocumentationTrait.class).getValue());
 
         if (!previousText.isEmpty()) {
             // Add spacing if tags have been added to the javadoc
@@ -35,6 +35,6 @@ public Class<JavadocSection> sectionType() {
 
     @Override
     public boolean isIntercepted(JavadocSection section) {
-        return section.shape().hasTrait(DocumentationTrait.class);
+        return section.targetedShape() != null && section.targetedShape().hasTrait(DocumentationTrait.class);
     }
 }

codegen/core/src/main/java/software/amazon/smithy/java/codegen/integrations/javadoc/ExternalDocumentationTraitInterceptor.java

@@ -16,7 +16,7 @@
 final class ExternalDocumentationTraitInterceptor implements CodeInterceptor.Appender<JavadocSection, JavaWriter> {
     @Override
     public void append(JavaWriter writer, JavadocSection section) {
-        var trait = section.shape().expectTrait(ExternalDocumentationTrait.class);
+        var trait = section.targetedShape().expectTrait(ExternalDocumentationTrait.class);
         writer.pushState();
         writer.putContext("links", trait.getUrls());
         writer.write("${#links}@see <a href=${value:S}>${key:L}</a>${^key.last}\n${/key.last}${/links}");
@@ -30,6 +30,6 @@ public Class<JavadocSection> sectionType() {
 
     @Override
     public boolean isIntercepted(JavadocSection section) {
-        return section.shape().hasTrait(ExternalDocumentationTrait.class);
+        return section.targetedShape() != null && section.targetedShape().hasTrait(ExternalDocumentationTrait.class);
     }
 }

codegen/core/src/main/java/software/amazon/smithy/java/codegen/integrations/javadoc/JavadocInjectorInterceptor.java

@@ -6,15 +6,9 @@
 package software.amazon.smithy.java.codegen.integrations.javadoc;
 
 import software.amazon.smithy.java.codegen.sections.ApplyDocumentation;
-import software.amazon.smithy.java.codegen.sections.BuilderSetterSection;
-import software.amazon.smithy.java.codegen.sections.ClassSection;
 import software.amazon.smithy.java.codegen.sections.DocumentedSection;
-import software.amazon.smithy.java.codegen.sections.EnumVariantSection;
-import software.amazon.smithy.java.codegen.sections.GetterSection;
 import software.amazon.smithy.java.codegen.sections.JavadocSection;
-import software.amazon.smithy.java.codegen.sections.OperationSection;
 import software.amazon.smithy.java.codegen.writer.JavaWriter;
-import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.model.traits.DeprecatedTrait;
 import software.amazon.smithy.model.traits.UnstableTrait;
 import software.amazon.smithy.utils.CodeInterceptor;
@@ -45,34 +39,24 @@ public boolean isIntercepted(CodeSection section) {
 
     @Override
     public void prepend(JavaWriter writer, CodeSection section) {
-        var shape = getShape(section);
-        writer.injectSection(new JavadocSection(shape, section));
-        if (shape.hasTrait(UnstableTrait.class)) {
-            writer.write("@$T", SmithyUnstableApi.class);
-        }
-
-        if (shape.hasTrait(DeprecatedTrait.class)) {
-            var deprecated = shape.expectTrait(DeprecatedTrait.class);
-            writer.pushState();
-            writer.putContext("since", deprecated.getSince().orElse(""));
-            writer.write("@$T${?since}(since = ${since:S})${/since}", Deprecated.class);
-            writer.popState();
-        }
-    }
-
-    private static Shape getShape(CodeSection section) {
-        if (section instanceof ClassSection cs) {
-            return cs.shape();
-        } else if (section instanceof GetterSection gs) {
-            return gs.memberShape();
-        } else if (section instanceof EnumVariantSection es) {
-            return es.memberShape();
-        } else if (section instanceof BuilderSetterSection bs) {
-            return bs.memberShape();
-        } else if (section instanceof OperationSection os) {
-            return os.operation();
-        } else {
-            throw new IllegalArgumentException("Javadocs cannot be injected for section: " + section);
+        if (section instanceof DocumentedSection ds) {
+            var shape = ds.targetedShape();
+            writer.injectSection(new JavadocSection(shape, section));
+            if (shape == null) {
+                return;
+            }
+
+            if (shape.hasTrait(UnstableTrait.class)) {
+                writer.write("@$T", SmithyUnstableApi.class);
+            }
+
+            if (shape.hasTrait(DeprecatedTrait.class)) {
+                var deprecated = shape.expectTrait(DeprecatedTrait.class);
+                writer.pushState();
+                writer.putContext("since", deprecated.getSince().orElse(""));
+                writer.write("@$T${?since}(since = ${since:S})${/since}", Deprecated.class);
+                writer.popState();
+            }
         }
     }
 }

codegen/core/src/main/java/software/amazon/smithy/java/codegen/integrations/javadoc/OperationErrorInterceptor.java

@@ -18,9 +18,8 @@ final class OperationErrorInterceptor implements CodeInterceptor.Appender<Javado
 
     @Override
     public void append(JavaWriter writer, JavadocSection section) {
-        var operation = section.shape().asOperationShape().orElseThrow();
         if (section.parent() instanceof OperationSection os) {
-            for (var error : operation.getErrors()) {
+            for (var error : os.targetedShape().getErrors()) {
                 writer.pushState();
                 var errorShape = os.model().expectShape(error);
                 var errorSymbol = os.symbolProvider().toSymbol(errorShape);
@@ -44,9 +43,6 @@ public Class<JavadocSection> sectionType() {
 
     @Override
     public boolean isIntercepted(JavadocSection section) {
-        if (section.parent() instanceof OperationSection) {
-            return section.shape().isOperationShape();
-        }
-        return false;
+        return section.parent() instanceof OperationSection;
     }
 }

codegen/core/src/main/java/software/amazon/smithy/java/codegen/integrations/javadoc/SinceTraitInterceptor.java

@@ -16,7 +16,7 @@
 final class SinceTraitInterceptor implements CodeInterceptor.Appender<JavadocSection, JavaWriter> {
     @Override
     public void append(JavaWriter writer, JavadocSection section) {
-        var trait = section.shape().expectTrait(SinceTrait.class);
+        var trait = section.targetedShape().expectTrait(SinceTrait.class);
         writer.write("@since $L", trait.getValue());
     }
 
@@ -27,6 +27,6 @@ public Class<JavadocSection> sectionType() {
 
     @Override
     public boolean isIntercepted(JavadocSection section) {
-        return section.shape().hasTrait(SinceTrait.class);
+        return section.targetedShape() != null && section.targetedShape().hasTrait(SinceTrait.class);
     }
 }

codegen/core/src/main/java/software/amazon/smithy/java/codegen/sections/BuilderSetterSection.java

@@ -11,6 +11,6 @@
 /**
  * Contains a setter method on a builder.
  *
- * @param memberShape Smithy member that the Builder setter sets
+ * @param targetedShape Smithy member that the Builder setter sets
  */
-public record BuilderSetterSection(MemberShape memberShape) implements CodeSection, DocumentedSection {}
+public record BuilderSetterSection(MemberShape targetedShape) implements CodeSection, DocumentedSection {}

codegen/core/src/main/java/software/amazon/smithy/java/codegen/sections/ClassSection.java

@@ -11,12 +11,12 @@
 /**
  * Contains a Java class definition.
  *
- * @param shape Smithy shape that the Java class defines
+ * @param targetedShape Smithy shape that the Java class defines
  * @param applyDocumentation Whether and how documentation is applied.
  */
-public record ClassSection(Shape shape, ApplyDocumentation applyDocumentation) implements CodeSection,
+public record ClassSection(Shape targetedShape, ApplyDocumentation applyDocumentation) implements CodeSection,
         DocumentedSection {
-    public ClassSection(Shape shape) {
-        this(shape, ApplyDocumentation.DOCUMENT);
+    public ClassSection(Shape targetShape) {
+        this(targetShape, ApplyDocumentation.DOCUMENT);
     }
 }

codegen/core/src/main/java/software/amazon/smithy/java/codegen/sections/DocumentedSection.java

@@ -5,11 +5,18 @@
 
 package software.amazon.smithy.java.codegen.sections;
 
+import software.amazon.smithy.model.shapes.Shape;
+
 /**
  * Applied to sections that can have documentation.
  */
 public interface DocumentedSection {
     default ApplyDocumentation applyDocumentation() {
         return ApplyDocumentation.DOCUMENT;
     }
+
+    /**
+     * @return Shape targeted by this section, or null if target is not a shape
+     */
+    Shape targetedShape();
 }

codegen/core/src/main/java/software/amazon/smithy/java/codegen/sections/EnumVariantSection.java

@@ -11,6 +11,6 @@
 /**
  * Used to add documentation to an Enum Variant member shape.
  *
- * @param memberShape Member shape for enum variant
+ * @param targetedShape Member shape for enum variant
  */
-public record EnumVariantSection(MemberShape memberShape) implements CodeSection, DocumentedSection {}
+public record EnumVariantSection(MemberShape targetedShape) implements CodeSection, DocumentedSection {}

codegen/core/src/main/java/software/amazon/smithy/java/codegen/sections/GetterSection.java

@@ -11,6 +11,6 @@
 /**
  * Contains a getter method.
  *
- * @param memberShape Member shape that getter provides
+ * @param targetedShape Member shape that getter provides
  */
-public record GetterSection(MemberShape memberShape) implements CodeSection, DocumentedSection {}
+public record GetterSection(MemberShape targetedShape) implements CodeSection, DocumentedSection {}

codegen/core/src/main/java/software/amazon/smithy/java/codegen/sections/JavadocSection.java

@@ -15,7 +15,7 @@
  * are used to populate this section with content and to format it as a doc
  * comment.
  *
- * @param shape Shape that java docs are being added to.
+ * @param targetedShape Shape that java docs are being added to.
  * @param parent Code section that this javadoc section is attached to
  */
-public record JavadocSection(Shape shape, CodeSection parent) implements CodeSection {}
+public record JavadocSection(Shape targetedShape, CodeSection parent) implements CodeSection {}

codegen/core/src/main/java/software/amazon/smithy/java/codegen/sections/OperationSection.java

@@ -16,9 +16,9 @@
  * <p>This section is used operations both as stand-alone models
  * and for operation methods on clients.
  *
- * @param operation Operation that java docs are being added to.
+ * @param targetedShape Operation that java docs are being added to.
  */
 public record OperationSection(
-        OperationShape operation,
+        OperationShape targetedShape,
         SymbolProvider symbolProvider,
         Model model) implements CodeSection, DocumentedSection {}