Move depth tracking to DocWriter

Author: JordonPhillips

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

@@ -5,6 +5,7 @@
 
 package software.amazon.smithy.docgen.core.writers;
 
+import software.amazon.smithy.codegen.core.CodegenException;
 import software.amazon.smithy.codegen.core.SymbolWriter;
 import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.utils.SmithyUnstableApi;
@@ -16,6 +17,10 @@
  */
 @SmithyUnstableApi
 public abstract class DocWriter extends SymbolWriter<DocWriter, DocImportContainer> {
+    private static final int MAX_HEADING_DEPTH = 6;
+
+    private int headingDepth = 0;
+
     public DocWriter(DocImportContainer importContainer) {
         super(importContainer);
     }
@@ -47,12 +52,44 @@ public DocWriter(DocImportContainer importContainer) {
      * @param content A string to use as the heading content.
      * @return returns the writer.
      */
-    public abstract DocWriter openHeading(String content);
+    public DocWriter openHeading(String content) {
+        headingDepth++;
+        if (headingDepth > MAX_HEADING_DEPTH) {
+            throw new CodegenException(String.format(
+                "Tried opening a heading nested more deeply than the max depth of %d.",
+                MAX_HEADING_DEPTH
+            ));
+        }
+        return openHeading(content, headingDepth);
+    }
 
     /**
-     * Closes the current heading, cleaning any context created for the current level.
+     * Writes a heading of a given level 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.
+     * @param level The level of the heading to open. This corresponds to HTML heading
+     *              levels, and will only have values between 1 and 6.
      * @return returns the writer.
      */
-    public abstract DocWriter closeHeading();
+    abstract DocWriter openHeading(String content, int level);
+
+    /**
+     * Closes the current heading, cleaning any context created for the current level,
+     * then writes a blank line.
+     *
+     * @return returns the writer.
+     */
+    public DocWriter closeHeading() {
+        headingDepth--;
+        if (headingDepth < 0) {
+            throw new CodegenException(
+                "Attempted to close a heading when at the base heading level."
+            );
+        }
+        write("");
+        return this;
+    }
 }

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

@@ -5,16 +5,12 @@
 
 package software.amazon.smithy.docgen.core.writers;
 
-import software.amazon.smithy.codegen.core.CodegenException;
 import software.amazon.smithy.codegen.core.SymbolWriter;
 import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.model.traits.DocumentationTrait;
 import software.amazon.smithy.utils.StringUtils;
 
 public final class MarkdownWriter extends DocWriter {
-    private static int MAX_HEADING_DEPTH = 5;
-
-    private int headerLevel = 0;
 
     public MarkdownWriter() {
         super(new DocImportContainer());
@@ -42,28 +38,8 @@ private DocWriter writeWithNewline(Object content, Object... args) {
     }
 
     @Override
-    public DocWriter openHeading(String content) {
-        headerLevel++;
-        if (headerLevel > MAX_HEADING_DEPTH) {
-            throw new CodegenException(String.format(
-                "Tried opening a heading nested more deeply than the max depth of %d.",
-                MAX_HEADING_DEPTH
-            ));
-        }
-
-        writeWithNewline(StringUtils.repeat("#", headerLevel) + " " + content);
-
-        return this;
-    }
-
-    @Override
-    public DocWriter closeHeading() {
-        if (headerLevel <= 0) {
-            throw new CodegenException("Closed a header that was never opened.");
-        }
-        write("");
-
-        headerLevel--;
+    public DocWriter openHeading(String content, int level) {
+        writeWithNewline(StringUtils.repeat("#", level) + " " + content);
         return this;
     }
 }