Add documentation and cleanup visiblity

Author: JordonPhillips

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DirectedDocGen.java

@@ -17,8 +17,13 @@
 import software.amazon.smithy.codegen.core.directed.GenerateStructureDirective;
 import software.amazon.smithy.codegen.core.directed.GenerateUnionDirective;
 import software.amazon.smithy.docgen.core.generators.ServiceGenerator;
+import software.amazon.smithy.utils.SmithyUnstableApi;
 
-public class DirectedDocGen implements DirectedCodegen<DocGenerationContext, DocSettings, DocIntegration> {
+/**
+ * The main entry points for documentation generation.
+ */
+@SmithyUnstableApi
+final class DirectedDocGen implements DirectedCodegen<DocGenerationContext, DocSettings, DocIntegration> {
 
     @Override
     public SymbolProvider createSymbolProvider(CreateSymbolProviderDirective<DocSettings> directive) {

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocGenerationContext.java

@@ -13,7 +13,13 @@
 import software.amazon.smithy.docgen.core.writers.DocWriter;
 import software.amazon.smithy.docgen.core.writers.MarkdownWriter;
 import software.amazon.smithy.model.Model;
+import software.amazon.smithy.utils.SmithyUnstableApi;
 
+/**
+ * Contextual information that is made available during most parts of documentation
+ * generation.
+ */
+@SmithyUnstableApi
 public final class DocGenerationContext implements CodegenContext<DocSettings, DocWriter, DocIntegration> {
     private final Model model;
     private final DocSettings docSettings;

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocIntegration.java

@@ -7,6 +7,17 @@
 
 import software.amazon.smithy.codegen.core.SmithyIntegration;
 import software.amazon.smithy.docgen.core.writers.DocWriter;
+import software.amazon.smithy.utils.SmithyUnstableApi;
 
+/**
+ * Allows integrating additional functionality into the documentation generator.
+ *
+ * <p>{@code DocIntegration}s are loaded as a Java SPI. To make your integration
+ * discoverable, add a file to {@code META-INF/services} named
+ * {@code software.amazon.smithy.docgen.core.DocIntegration} where each line is
+ * the fully-qualified class name of your integrations. Several tools, such as
+ * {@code AutoService}, can do this for you.
+ */
+@SmithyUnstableApi
 public interface DocIntegration extends SmithyIntegration<DocSettings, DocWriter, DocGenerationContext> {
 }

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocSettings.java

@@ -8,13 +8,27 @@
 import java.util.Objects;
 import software.amazon.smithy.model.node.ObjectNode;
 import software.amazon.smithy.model.shapes.ShapeId;
+import software.amazon.smithy.utils.SmithyUnstableApi;
 
+/**
+ * Settings for documentation generation. These can be set in the
+ * {@code smithy-build.json} configuration for this plugin.
+ *
+ * @param service The shape id of the service to generate documentation for.
+ */
+@SmithyUnstableApi
 public record DocSettings(ShapeId service) {
 
     public DocSettings {
         Objects.requireNonNull(service);
     }
 
+    /**
+     * Load the settings from an {@code ObjectNode}.
+     *
+     * @param pluginSettings the {@code ObjectNode} to load settings from.
+     * @return loaded settings based on the given node.
+     */
     public static DocSettings from(ObjectNode pluginSettings) {
         return new DocSettings(pluginSettings.expectStringMember("service").expectShapeId());
     }

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocSymbolProvider.java

@@ -51,7 +51,7 @@
  *
  */
 @SmithyUnstableApi
-public class DocSymbolProvider extends ShapeVisitor.Default<Symbol> implements SymbolProvider {
+public final class DocSymbolProvider extends ShapeVisitor.Default<Symbol> implements SymbolProvider {
 
     /**
      * The name for a shape symbol's named property containing the shape the symbol

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/SmithyDocPlugin.java

@@ -11,10 +11,12 @@
 import software.amazon.smithy.build.SmithyBuildPlugin;
 import software.amazon.smithy.codegen.core.directed.CodegenDirector;
 import software.amazon.smithy.docgen.core.writers.DocWriter;
+import software.amazon.smithy.utils.SmithyInternalApi;
 
 /**
  * Generates API documentation from a Smithy model.
  */
+@SmithyInternalApi
 public final class SmithyDocPlugin implements SmithyBuildPlugin {
 
     private static final Logger LOGGER = Logger.getLogger(SmithyDocPlugin.class.getName());

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

@@ -10,10 +10,13 @@
 import software.amazon.smithy.docgen.core.DocGenerationContext;
 import software.amazon.smithy.docgen.core.DocSettings;
 import software.amazon.smithy.model.shapes.ServiceShape;
-import software.amazon.smithy.model.traits.TitleTrait;
+import software.amazon.smithy.utils.SmithyInternalApi;
 
-public final class ServiceGenerator
-        implements Consumer<GenerateServiceDirective<DocGenerationContext, DocSettings>> {
+/**
+ * Generates the top-level documentation for a service.
+ */
+@SmithyInternalApi
+public final class ServiceGenerator implements Consumer<GenerateServiceDirective<DocGenerationContext, DocSettings>> {
 
     @Override
     public void accept(GenerateServiceDirective<DocGenerationContext, DocSettings> directive) {

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/DocImportContainer.java

@@ -7,7 +7,12 @@
 
 import software.amazon.smithy.codegen.core.ImportContainer;
 import software.amazon.smithy.codegen.core.Symbol;
+import software.amazon.smithy.utils.SmithyUnstableApi;
 
+/**
+ * A No-Op import container.
+ */
+@SmithyUnstableApi
 public class DocImportContainer implements ImportContainer {
     @Override
     public void importSymbol(Symbol symbol, String s) {

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/DocWriter.java

@@ -7,15 +7,52 @@
 
 import software.amazon.smithy.codegen.core.SymbolWriter;
 import software.amazon.smithy.model.shapes.Shape;
+import software.amazon.smithy.utils.SmithyUnstableApi;
 
+/**
+ * A {@code SymbolWriter} provides abstract methods that will be used during
+ * documentation generation. This allows for other formats to be swapped out
+ * without much difficulty.
+ */
+@SmithyUnstableApi
 public abstract class DocWriter extends SymbolWriter<DocWriter, DocImportContainer> {
     public DocWriter(DocImportContainer importContainer) {
         super(importContainer);
     }
 
+    /**
+     * Writes out the content of the shape's
+     * <a href="https://smithy.io/2.0/spec/documentation-traits.html#smithy-api-documentation-trait">
+     * documentation trait</a>, if present.
+     *
+     * <p>Smithy's documentation trait is in the
+     * <a href="https://spec.commonmark.org">CommonMark</a> format, so writers
+     * for formats that aren't based on CommonMark will need to convert the value to
+     * their format. This includes raw HTML, which CommonMark allows.
+     *
+     * <p>If the shape doesn't have a documentation trait, the writer MAY write out
+     * default documentation.
+     *
+     * @param shape The shape whose documentation should be written.
+     * @return returns the writer.
+     */
     public abstract DocWriter writeShapeDocs(Shape shape);
 
+    /**
+     * Writes a heading with the given content.
+     *
+     * <p>{@link #closeHeading} will be called to enable cleaning up any resources or
+     * context this method creates.
+     *
+     * @param content A string to use as the heading content.
+     * @return returns the writer.
+     */
     public abstract DocWriter openHeading(String content);
 
+    /**
+     * Closes the current heading, cleaning any context created for the current level.
+     *
+     * @return returns the writer.
+     */
     public abstract DocWriter closeHeading();
 }

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/MarkdownWriter.java

@@ -12,7 +12,7 @@
 import software.amazon.smithy.utils.StringUtils;
 
 public final class MarkdownWriter extends DocWriter {
-    private static int MAX_HEADING_DEPTH = 6;
+    private static int MAX_HEADING_DEPTH = 5;
 
     private int headerLevel = 0;