Rename AppendEncoded() to AppendHtml() and SetContentEncoded() to SetHtmlContent()

- aspnet/Mvc#3225, 1 of 3

Also correct parameter names and doc comments
- add `xml-docs-test` to ensure this doc comments remain valid in the future

Author: dougbu

makefile.shade

@@ -5,3 +5,6 @@ var AUTHORS='Microsoft Open Technologies, Inc.'
 
 use-standard-lifecycle
 k-standard-goals
+
+#xml-docs-test .clean .build-compile description='Check generated XML documentation files for errors' target='package'
+  k-xml-docs-test

src/Microsoft.AspNet.Html.Abstractions/HtmlContentBuilderExtensions.cs

@@ -5,7 +5,6 @@
 using System.Diagnostics;
 using System.Globalization;
 using System.IO;
-using System.Text;
 using Microsoft.Extensions.WebEncoders;
 
 namespace Microsoft.AspNet.Html.Abstractions
@@ -20,6 +19,7 @@ public static class HtmlContentBuilderExtensions
         /// item with the HTML encoded <see cref="string"/> representation of the corresponding item in the
         /// <paramref name="args"/> array.
         /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
         /// <param name="format">
         /// The composite format <see cref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
         /// The format string is assumed to be HTML encoded as-provided, and no further encoding will be performed.
@@ -54,9 +54,10 @@ public static IHtmlContentBuilder AppendFormat(
 
         /// <summary>
         /// Appends the specified <paramref name="format"/> to the existing content with information from the
-        /// <paramref name="provider"/> after replacing each format item with the HTML encoded <see cref="string"/>
-        /// representation of the corresponding item in the <paramref name="args"/> array.
+        /// <paramref name="formatProvider"/> after replacing each format item with the HTML encoded
+        /// <see cref="string"/> representation of the corresponding item in the <paramref name="args"/> array.
         /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
         /// <param name="formatProvider">An object that supplies culture-specific formatting information.</param>
         /// <param name="format">
         /// The composite format <see cref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
@@ -122,9 +123,9 @@ public static IHtmlContentBuilder AppendLine(this IHtmlContentBuilder builder, s
         /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
         /// <param name="content">The <see cref="IHtmlContent"/> to append.</param>
         /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
-        public static IHtmlContentBuilder AppendLine(this IHtmlContentBuilder builder, IHtmlContent htmlContent)
+        public static IHtmlContentBuilder AppendLine(this IHtmlContentBuilder builder, IHtmlContent content)
         {
-            builder.Append(htmlContent);
+            builder.Append(content);
             builder.Append(HtmlEncodedString.NewLine);
             return builder;
         }
@@ -134,11 +135,11 @@ public static IHtmlContentBuilder AppendLine(this IHtmlContentBuilder builder, I
         /// The value is treated as HTML encoded as-provided, and no further encoding will be performed.
         /// </summary>
         /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
-        /// <param name="content">The HTML encoded <see cref="string"/> to append.</param>
+        /// <param name="encoded">The HTML encoded <see cref="string"/> to append.</param>
         /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
-        public static IHtmlContentBuilder AppendLineEncoded(this IHtmlContentBuilder builder, string encoded)
+        public static IHtmlContentBuilder AppendHtmlLine(this IHtmlContentBuilder builder, string encoded)
         {
-            builder.AppendEncoded(encoded);
+            builder.AppendHtml(encoded);
             builder.Append(HtmlEncodedString.NewLine);
             return builder;
         }
@@ -148,7 +149,7 @@ public static IHtmlContentBuilder AppendLineEncoded(this IHtmlContentBuilder bui
         /// and will be HTML encoded before writing to output.
         /// </summary>
         /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
-        /// <param name="value">The <see cref="string"/> value that replaces the content.</param>
+        /// <param name="unencoded">The <see cref="string"/> value that replaces the content.</param>
         /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
         public static IHtmlContentBuilder SetContent(this IHtmlContentBuilder builder, string unencoded)
         {
@@ -161,7 +162,7 @@ public static IHtmlContentBuilder SetContent(this IHtmlContentBuilder builder, s
         /// Sets the content to the <see cref="IHtmlContent"/> value.
         /// </summary>
         /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
-        /// <param name="value">The <see cref="IHtmlContent"/> value that replaces the content.</param>
+        /// <param name="content">The <see cref="IHtmlContent"/> value that replaces the content.</param>
         /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
         public static IHtmlContentBuilder SetContent(this IHtmlContentBuilder builder, IHtmlContent content)
         {
@@ -175,12 +176,12 @@ public static IHtmlContentBuilder SetContent(this IHtmlContentBuilder builder, I
         /// no further encoding will be performed.
         /// </summary>
         /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
-        /// <param name="content">The HTML encoded <see cref="string"/> that replaces the content.</param>
+        /// <param name="encoded">The HTML encoded <see cref="string"/> that replaces the content.</param>
         /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
-        public static IHtmlContentBuilder SetContentEncoded(this IHtmlContentBuilder builder, string encoded)
+        public static IHtmlContentBuilder SetHtmlContent(this IHtmlContentBuilder builder, string encoded)
         {
             builder.Clear();
-            builder.AppendEncoded(encoded);
+            builder.AppendHtml(encoded);
             return builder;
         }
 

src/Microsoft.AspNet.Html.Abstractions/IHtmlContentBuilder.cs

@@ -29,7 +29,7 @@ public interface IHtmlContentBuilder : IHtmlContent
         /// </summary>
         /// <param name="encoded">The HTML encoded <see cref="string"/> to append.</param>
         /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
-        IHtmlContentBuilder AppendEncoded(string encoded);
+        IHtmlContentBuilder AppendHtml(string encoded);
 
         /// <summary>
         /// Clears the content.

src/Microsoft.Extensions.BufferedHtmlContent.Sources/BufferedHtmlContent.cs

@@ -24,11 +24,11 @@ internal class BufferedHtmlContent : IHtmlContentBuilder
         /// <summary>
         /// Appends the <see cref="string"/> to the collection.
         /// </summary>
-        /// <param name="value">The <c>string</c> to be appended.</param>
+        /// <param name="unencoded">The <c>string</c> to be appended.</param>
         /// <returns>A reference to this instance after the Append operation has completed.</returns>
-        public IHtmlContentBuilder Append(string value)
+        public IHtmlContentBuilder Append(string unencoded)
         {
-            Entries.Add(value);
+            Entries.Add(unencoded);
             return this;
         }
 
@@ -46,11 +46,11 @@ public IHtmlContentBuilder Append(IHtmlContent htmlContent)
         /// <summary>
         /// Appends the HTML encoded <see cref="string"/> to the collection.
         /// </summary>
-        /// <param name="value">The HTML encoded <c>string</c> to be appended.</param>
+        /// <param name="encoded">The HTML encoded <c>string</c> to be appended.</param>
         /// <returns>A reference to this instance after the Append operation has completed.</returns>
-        public IHtmlContentBuilder AppendEncoded(string value)
+        public IHtmlContentBuilder AppendHtml(string encoded)
         {
-            Entries.Add(new HtmlEncodedString(value));
+            Entries.Add(new HtmlEncodedString(encoded));
             return this;
         }
         /// <summary>
@@ -95,7 +95,7 @@ public void WriteTo(TextWriter writer, IHtmlEncoder encoder)
                 }
             }
         }
-        
+
         private string DebuggerToString()
         {
             using (var writer = new StringWriter())

test/Microsoft.AspNet.Html.Abstractions.Test/HtmlContentBuilderExtensionsTest.cs

@@ -62,13 +62,13 @@ public void Builder_AppendLine_IHtmlContent()
         }
 
         [Fact]
-        public void Builder_AppendLineEncoded_String()
+        public void Builder_AppendHtmlLine_String()
         {
             // Arrange
             var builder = new TestHtmlContentBuilder();
 
             // Act
-            builder.AppendLineEncoded("Hi");
+            builder.AppendHtmlLine("Hi");
 
             // Assert
             Assert.Collection(
@@ -112,14 +112,14 @@ public void Builder_SetContent_IHtmlContent()
         }
 
         [Fact]
-        public void Builder_SetContentEncoded_String()
+        public void Builder_SetHtmlContent_String()
         {
             // Arrange
             var builder = new TestHtmlContentBuilder();
             builder.Append("Existing Content. Will be Cleared.");
 
             // Act
-            builder.SetContentEncoded("Hi");
+            builder.SetHtmlContent("Hi");
 
             // Assert
             Assert.Collection(
@@ -366,7 +366,7 @@ public IHtmlContentBuilder Append(IHtmlContent content)
                 return this;
             }
 
-            public IHtmlContentBuilder AppendEncoded(string encoded)
+            public IHtmlContentBuilder AppendHtml(string encoded)
             {
                 Entries.Add(new EncodedString(encoded));
                 return this;

test/Microsoft.Extensions.BufferedHtmlContent.Test/BufferedHtmlContentTest.cs

@@ -41,11 +41,11 @@ public void AppendString_WrittenAsEncoded()
         }
 
         [Fact]
-        public void AppendEncoded_DoesNotGetWrittenAsEncoded()
+        public void AppendHtml_DoesNotGetWrittenAsEncoded()
         {
             // Arrange
             var content = new BufferedHtmlContent();
-            content.AppendEncoded("Hello");
+            content.AppendHtml("Hello");
 
             var writer = new StringWriter();