Preserve CodeWriter backwards compatibility

Adding a parent of CodeWriter that changed the return type of its methods, even
though those returned objects were always in practice the same type as they had
been before, broke binary backwards compatibility for consumers of CodeWriter.

This returns CodeWriter back to its previous state, mostly, and adds a new
default extension of AbstractCodeWriter called SimpleCodeWriter. Current
consumers of CodeWriter will continue to work, and have access to some new
features.

smithy-codegen-core/src/main/java/software/amazon/smithy/codegen/core/writer/CodegenWriter.java

@@ -80,10 +80,12 @@
  *
  * @param <T> The concrete type, used to provide a fluent interface.
  * @param <U> The import container used by the writer to manage imports.
+ * @deprecated prefer {@link SymbolWriter}. This will be removed in a future release.
  */
 @SmithyUnstableApi
+@Deprecated
 public class CodegenWriter<T extends CodegenWriter<T, U>, U extends ImportContainer>
-        extends AbstractCodeWriter<T> implements SymbolDependencyContainer {
+        extends CodeWriter implements SymbolDependencyContainer {
 
     private static final Logger LOGGER = Logger.getLogger(CodegenWriter.class.getName());
     private static final String RELATIVIZE_SYMBOLS = "__CodegenWriterRelativizeSymbols";

smithy-codegen-core/src/main/java/software/amazon/smithy/codegen/core/writer/DocWriter.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2020 Amazon.com, Inc. or its affiliates. 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.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.smithy.codegen.core.writer;
+
+import software.amazon.smithy.utils.AbstractCodeWriter;
+import software.amazon.smithy.utils.SmithyUnstableApi;
+
+/**
+ * Responsible for properly writing documentation emitted when a
+ * {@code Runnable} in invoked.
+ *
+ * <p>The following example shows how to implement a basic
+ * {@code DocumentationWriter} that encloses documentation in
+ * successive lines that start with "///".
+ *
+ * <pre>{@code
+ * public final class MyDocWriter implements DocumentationWriter<MyWriter> {
+ *     \@Override
+ *     public void writeDocs(T writer, Runnable runnable) {
+ *         setNewlinePrefix("/// ")
+ *         runnable.run();
+ *     }
+ * }
+ * }</pre>
+ *
+ * @param <T> The type of {@code AbstractCodeWriter} being written to.
+ */
+@FunctionalInterface
+@SmithyUnstableApi
+public interface DocWriter<T extends AbstractCodeWriter<T>> {
+
+    /**
+     * Writes documentation comments.
+     *
+     * <p>Implementations are expected to write out the beginning of a documentation
+     * comment, set any necessary prefix for each line written while writing docs,
+     * then invoke the given {@code runnable}, then finally write the closing
+     * characters for documentation.
+     *
+     * @param writer   Writer to configure for writing documentation.
+     * @param runnable Runnable that handles actually writing docs with the writer.
+     */
+    void writeDocs(T writer, Runnable runnable);
+}

smithy-codegen-core/src/main/java/software/amazon/smithy/codegen/core/writer/DocumentationWriter.java

@@ -15,7 +15,7 @@
 
 package software.amazon.smithy.codegen.core.writer;
 
-import software.amazon.smithy.utils.AbstractCodeWriter;
+import software.amazon.smithy.utils.CodeWriter;
 import software.amazon.smithy.utils.SmithyUnstableApi;
 
 /**
@@ -37,10 +37,12 @@
  * }</pre>
  *
  * @param <T> The type of {@code CodegenWriter} being written to.
+ * @deprecated prefer {@link DocWriter}. This will be removed in a future release.
  */
+@Deprecated
 @FunctionalInterface
 @SmithyUnstableApi
-public interface DocumentationWriter<T extends AbstractCodeWriter<T>> {
+public interface DocumentationWriter<T extends CodeWriter> {
     // Implementer's note: this class is not tied to CodegenWriter; it can be
     // used with any kind of CodeWriter, allowing any kind of CodegenWriters to
     // be used but also making this type more general-purpose.

smithy-codegen-core/src/main/java/software/amazon/smithy/codegen/core/writer/JavaStyleDocumentationWriterBuilder.java

@@ -16,7 +16,7 @@
 package software.amazon.smithy.codegen.core.writer;
 
 import java.util.function.Function;
-import software.amazon.smithy.utils.AbstractCodeWriter;
+import software.amazon.smithy.utils.CodeWriter;
 import software.amazon.smithy.utils.SmithyUnstableApi;
 
 /**
@@ -27,7 +27,10 @@
  * closing documentation comment (i.e., star (*) followed by a forward slash
  * (/)). This should also work for JavaScript, PHP, and other languages that
  * use Java-style comments.
+ *
+ * @deprecated this class uses CodeWriter, which is deprecated.
  */
+@Deprecated
 @SmithyUnstableApi
 public final class JavaStyleDocumentationWriterBuilder {
 
@@ -62,7 +65,7 @@ public static String escapeAtSignWithEntity(String contents) {
      * @param <T> The type of writer to create.
      * @return Returns the created documentation writer.
      */
-    public <T extends AbstractCodeWriter<T>> DocumentationWriter<T> build() {
+    public <T extends CodeWriter> DocumentationWriter<T> build() {
         Function<String, String> function = resolveMappingFunction();
         String sectionName = namedDocumentationSection;