Cleanup and add documentation for IndentedStringBuilder

src/EFCore.Cosmos/Query/Internal/SqlUnaryExpression.cs

@@ -92,7 +92,7 @@ public override void Print(ExpressionPrinter expressionPrinter)
         {
             Check.NotNull(expressionPrinter, nameof(expressionPrinter));
 
-            expressionPrinter.Append(OperatorType);
+            expressionPrinter.Append(OperatorType.ToString());
             expressionPrinter.Append("(");
             expressionPrinter.Visit(Operand);
             expressionPrinter.Append(")");

src/EFCore.Design/Design/Internal/CSharpHelper.cs

@@ -580,7 +580,7 @@ private string Array(Type type, IEnumerable values, bool vertical = false)
             if (valuesList.Count == 0)
             {
                 builder
-                    .Append(' ')
+                    .Append(" ")
                     .Append(Reference(type))
                     .Append("[0]");
             }

src/EFCore.Design/Scaffolding/Internal/CSharpEntityTypeGenerator.cs

@@ -142,7 +142,7 @@ private void GenerateKeylessAttribute(IEntityType entityType)
         {
             if (entityType.FindPrimaryKey() == null)
             {
-                _sb.AppendLine(new AttributeWriter(nameof(KeylessAttribute)));
+                _sb.AppendLine(new AttributeWriter(nameof(KeylessAttribute)).ToString());
             }
         }
 
@@ -166,7 +166,7 @@ private void GenerateTableAttribute(IEntityType entityType)
                     tableAttribute.AddParameter($"{nameof(TableAttribute.Schema)} = {_code.Literal(schema)}");
                 }
 
-                _sb.AppendLine(tableAttribute);
+                _sb.AppendLine(tableAttribute.ToString());
             }
         }
 
@@ -245,7 +245,7 @@ private void GenerateKeyAttribute(IProperty property)
             var key = property.FindContainingPrimaryKey();
             if (key != null)
             {
-                _sb.AppendLine(new AttributeWriter(nameof(KeyAttribute)));
+                _sb.AppendLine(new AttributeWriter(nameof(KeyAttribute)).ToString());
             }
         }
 
@@ -271,7 +271,7 @@ private void GenerateColumnAttribute(IProperty property)
                     columnAttribute.AddParameter($"{nameof(ColumnAttribute.TypeName)} = {delimitedColumnType}");
                 }
 
-                _sb.AppendLine(columnAttribute);
+                _sb.AppendLine(columnAttribute.ToString());
             }
         }
 
@@ -288,7 +288,7 @@ private void GenerateMaxLengthAttribute(IProperty property)
 
                 lengthAttribute.AddParameter(_code.Literal(maxLength.Value));
 
-                _sb.AppendLine(lengthAttribute);
+                _sb.AppendLine(lengthAttribute.ToString());
             }
         }
 
@@ -298,7 +298,7 @@ private void GenerateRequiredAttribute(IProperty property)
                 && property.ClrType.IsNullableType()
                 && !property.IsPrimaryKey())
             {
-                _sb.AppendLine(new AttributeWriter(nameof(RequiredAttribute)));
+                _sb.AppendLine(new AttributeWriter(nameof(RequiredAttribute)).ToString());
             }
         }
 
@@ -361,7 +361,7 @@ private void GenerateForeignKeyAttribute(INavigation navigation)
                         foreignKeyAttribute.AddParameter($"nameof({navigation.ForeignKey.Properties.First().Name})");
                     }
 
-                    _sb.AppendLine(foreignKeyAttribute);
+                    _sb.AppendLine(foreignKeyAttribute.ToString());
                 }
             }
         }
@@ -382,7 +382,7 @@ private void GenerateInversePropertyAttribute(INavigation navigation)
                             ? $"nameof({inverseNavigation.DeclaringEntityType.Name}.{inverseNavigation.Name})"
                             : _code.Literal(inverseNavigation.Name));
 
-                    _sb.AppendLine(inversePropertyAttribute);
+                    _sb.AppendLine(inversePropertyAttribute.ToString());
                 }
             }
         }

src/EFCore.Relational/Migrations/MigrationCommandListBuilder.cs

@@ -65,11 +65,11 @@ public virtual MigrationCommandListBuilder EndCommand(bool suppressTransaction =
         }
 
         /// <summary>
-        ///     Appends the given object (as a string) to the command being built.
+        ///     Appends the given string to the command being built.
         /// </summary>
-        /// <param name="o"> The object to append. </param>
+        /// <param name="o"> The string to append. </param>
         /// <returns> This builder so that additional calls can be chained. </returns>
-        public virtual MigrationCommandListBuilder Append([NotNull] object o)
+        public virtual MigrationCommandListBuilder Append([NotNull] string o)
         {
             Check.NotNull(o, nameof(o));
 
@@ -90,31 +90,31 @@ public virtual MigrationCommandListBuilder AppendLine()
         }
 
         /// <summary>
-        ///     Appends the given object (as a string) to the command being built, and then starts a new line.
+        ///     Appends the given string to the command being built, and then starts a new line.
         /// </summary>
-        /// <param name="o"> The object to append. </param>
+        /// <param name="value"> The string to append. </param>
         /// <returns> This builder so that additional calls can be chained. </returns>
-        public virtual MigrationCommandListBuilder AppendLine([NotNull] object o)
+        public virtual MigrationCommandListBuilder AppendLine([NotNull] string value)
         {
-            Check.NotNull(o, nameof(o));
+            Check.NotNull(value, nameof(value));
 
-            _commandBuilder.AppendLine(o);
+            _commandBuilder.AppendLine(value);
 
             return this;
         }
 
         /// <summary>
         ///     Appends the given object to the command being built as multiple lines of text. That is,
-        ///     each line in the passed object (as a string) is added as a line to the command being built.
+        ///     each line in the passed string is added as a line to the command being built.
         ///     This results in the lines having the correct indentation.
         /// </summary>
-        /// <param name="o"> The object to append. </param>
+        /// <param name="value"> The string to append. </param>
         /// <returns> This builder so that additional calls can be chained. </returns>
-        public virtual MigrationCommandListBuilder AppendLines([NotNull] object o)
+        public virtual MigrationCommandListBuilder AppendLines([NotNull] string value)
         {
-            Check.NotNull(o, nameof(o));
+            Check.NotNull(value, nameof(value));
 
-            _commandBuilder.AppendLines(o);
+            _commandBuilder.AppendLines(value);
 
             return this;
         }

src/EFCore.Relational/Query/SqlExpressions/SqlUnaryExpression.cs

@@ -75,7 +75,7 @@ public override void Print(ExpressionPrinter expressionPrinter)
             }
             else
             {
-                expressionPrinter.Append(OperatorType);
+                expressionPrinter.Append(OperatorType.ToString());
                 expressionPrinter.Append("(");
                 expressionPrinter.Visit(Operand);
                 expressionPrinter.Append(")");

src/EFCore.Relational/Storage/IRelationalCommandBuilder.cs

@@ -45,7 +45,7 @@ public interface IRelationalCommandBuilder
         /// </summary>
         /// <param name="value"> The object to be written. </param>
         /// <returns> The same builder instance so that multiple calls can be chained. </returns>
-        IRelationalCommandBuilder Append([NotNull] object value);
+        IRelationalCommandBuilder Append([NotNull] string value);
 
         /// <summary>
         ///     Appends a blank line to the command text.

src/EFCore.Relational/Storage/RelationalCommandBuilder.cs

@@ -87,7 +87,7 @@ public virtual IRelationalCommandBuilder AddParameter(IRelationalParameter param
         /// </summary>
         /// <param name="value"> The object to be written. </param>
         /// <returns> The same builder instance so that multiple calls can be chained. </returns>
-        public virtual IRelationalCommandBuilder Append(object value)
+        public virtual IRelationalCommandBuilder Append(string value)
         {
             Check.NotNull(value, nameof(value));
 

src/EFCore.Relational/Storage/RelationalCommandBuilderExtensions.cs

@@ -25,7 +25,7 @@ public static class RelationalCommandBuilderExtensions
         /// <returns> The same builder instance so that multiple calls can be chained. </returns>
         public static IRelationalCommandBuilder AppendLine(
             [NotNull] this IRelationalCommandBuilder commandBuilder,
-            [NotNull] object value)
+            [NotNull] string value)
         {
             Check.NotNull(commandBuilder, nameof(commandBuilder));
             Check.NotNull(value, nameof(value));
@@ -45,13 +45,13 @@ public static IRelationalCommandBuilder AppendLine(
         /// <returns> The same builder instance so that multiple calls can be chained. </returns>
         public static IRelationalCommandBuilder AppendLines(
             [NotNull] this IRelationalCommandBuilder commandBuilder,
-            [NotNull] object value,
+            [NotNull] string value,
             bool skipFinalNewline = false)
         {
             Check.NotNull(commandBuilder, nameof(commandBuilder));
             Check.NotNull(value, nameof(value));
 
-            using (var reader = new StringReader(value.ToString()))
+            using (var reader = new StringReader(value))
             {
                 var first = true;
                 string line;

src/EFCore/Infrastructure/IndentedStringBuilder.cs

@@ -8,6 +8,15 @@
 
 namespace Microsoft.EntityFrameworkCore.Infrastructure
 {
+    /// <summary>
+    ///     <para>
+    ///         A thin wrapper over <see cref="StringBuilder" /> that adds indentation to each line built.
+    ///     </para>
+    ///     <para>
+    ///         This type is typically used by database providers (and other extensions). It is generally
+    ///         not used in application code.
+    ///     </para>
+    /// </summary>
     public class IndentedStringBuilder
     {
         private const byte IndentSize = 4;
@@ -16,32 +25,43 @@ public class IndentedStringBuilder
 
         private readonly StringBuilder _stringBuilder = new StringBuilder();
 
-        public IndentedStringBuilder()
-        {
-        }
-
+        /// <summary>
+        ///     The current length of the built string.
+        /// </summary>
         public virtual int Length => _stringBuilder.Length;
 
-        public virtual IndentedStringBuilder Append([NotNull] object o)
+        /// <summary>
+        ///     Appends an indent and then the given string to the string being built.
+        /// </summary>
+        /// <param name="value"> The string to append. </param>
+        /// <returns> This builder so that additional calls can be chained. </returns>
+        public virtual IndentedStringBuilder Append([NotNull] string value)
         {
             DoIndent();
 
-            _stringBuilder.Append(o);
+            _stringBuilder.Append(value);
 
             return this;
         }
 
+        /// <summary>
+        ///     Appends a new line to the string being built.
+        /// </summary>
+        /// <returns> This builder so that additional calls can be chained. </returns>
         public virtual IndentedStringBuilder AppendLine()
         {
             AppendLine(string.Empty);
 
             return this;
         }
 
-        public virtual IndentedStringBuilder AppendLine([NotNull] object o)
+        /// <summary>
+        ///     Appends an indent, the given string, and a new line to the string being built.
+        /// </summary>
+        /// <param name="value"> The string to append. </param>
+        /// <returns> This builder so that additional calls can be chained. </returns>
+        public virtual IndentedStringBuilder AppendLine([NotNull] string value)
         {
-            var value = o.ToString();
-
             if (value.Length != 0)
             {
                 DoIndent();
@@ -54,9 +74,15 @@ public virtual IndentedStringBuilder AppendLine([NotNull] object o)
             return this;
         }
 
-        public virtual IndentedStringBuilder AppendLines([NotNull] object o, bool skipFinalNewline = false)
+        /// <summary>
+        ///     Appends all the lines in the given string, prefixed by the current indent.
+        /// </summary>
+        /// <param name="value"> The string to append. </param>
+        /// <param name="skipFinalNewline"> If true, then a terminating new line is not added. </param>
+        /// <returns> This builder so that additional calls can be chained. </returns>
+        public virtual IndentedStringBuilder AppendLines([NotNull] string value, bool skipFinalNewline = false)
         {
-            using (var reader = new StringReader(o.ToString()))
+            using (var reader = new StringReader(value))
             {
                 var first = true;
                 string line;
@@ -86,20 +112,33 @@ public virtual IndentedStringBuilder AppendLines([NotNull] object o, bool skipFi
             return this;
         }
 
+        /// <summary>
+        ///     Resets this builder ready to build a new string.
+        /// </summary>
+        /// <returns> This builder so that additional calls can be chained. </returns>
         public virtual IndentedStringBuilder Clear()
         {
             _stringBuilder.Clear();
+            _indent = 0;
 
             return this;
         }
 
+        /// <summary>
+        ///     Increments the indent.
+        /// </summary>
+        /// <returns> This builder so that additional calls can be chained. </returns>
         public virtual IndentedStringBuilder IncrementIndent()
         {
             _indent++;
 
             return this;
         }
 
+        /// <summary>
+        ///     Decrements the indent.
+        /// </summary>
+        /// <returns> This builder so that additional calls can be chained. </returns>
         public virtual IndentedStringBuilder DecrementIndent()
         {
             if (_indent > 0)
@@ -110,8 +149,16 @@ public virtual IndentedStringBuilder DecrementIndent()
             return this;
         }
 
+        /// <summary>
+        ///     Creates a scoped indenter that will increment the index, then decrement it when disposed.
+        /// </summary>
+        /// <returns> An indenter. </returns>
         public virtual IDisposable Indent() => new Indenter(this);
 
+        /// <summary>
+        ///     Returns the built string.
+        /// </summary>
+        /// <returns> The built string. </returns>
         public override string ToString() => _stringBuilder.ToString();
 
         private void DoIndent()

src/EFCore/Query/EntityShaperExpression.cs

@@ -163,7 +163,7 @@ public virtual void Print(ExpressionPrinter expressionPrinter)
             expressionPrinter.AppendLine(nameof(EntityShaperExpression) + ": ");
             using (expressionPrinter.Indent())
             {
-                expressionPrinter.AppendLine(EntityType);
+                expressionPrinter.AppendLine(EntityType.ToString());
                 expressionPrinter.AppendLine(nameof(ValueBufferExpression) + ": ");
                 using (expressionPrinter.Indent())
                 {
@@ -172,7 +172,7 @@ public virtual void Print(ExpressionPrinter expressionPrinter)
                 }
 
                 expressionPrinter.Append(nameof(IsNullable) + ": ");
-                expressionPrinter.AppendLine(IsNullable);
+                expressionPrinter.AppendLine(IsNullable.ToString());
             }
         }
     }