Improve XML comments in `HtmlHelper` and related classes and interfaces

- #847 line 1: copy XML comments from interfaces to extension methods
- lots of wording changes to be more consistent
 - core text split from PR #866, where @rynowak and I hashed out the words
 - to extent possible, reuse words between method descriptions

- add a few missing `<param/>` and `<typeparam/>` elements and fill in empty ones
- display more HTML elements as tags
- use `<c>true|false|null</c>` more often
- add `<remarks/>` describing behaviour of input helpers e.g. `CheckBox()`
- add `<remarks/>` explaining "renders"
- add `<remarks/>` containing example expression names

nits:
- "The expression" -> "An expression"
- make examples for `ObjectToDictionary()` and `AnonymousObjectToHtmlAttributes()` more consistent
- move `<typeparam/>` elements (that existed) after all `<param/>` elements
- explain "checked" attributes better, removing some duplicated words from the `RadioButton[For]()` descriptions
- correct `routeValues` description in `GenerateForm()` comments

src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelper.cs

@@ -126,7 +126,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// If the object is already an <see cref="IDictionary{string, object}"/> instance, then it is
         /// returned as-is.
         /// <example>
-        /// <c>new { property_name = "value" }</c> will translate to the entry <c>{ "property_name" , "value" }</c>
+        /// <c>new { data_name="value" }</c> will translate to the entry <c>{ "data_name", "value" }</c>
         /// in the resulting dictionary.
         /// </example>
         /// </summary>
@@ -144,7 +144,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// If the object is already an <see cref="IDictionary{string, object}"/> instance, then it is
         /// returned as-is.
         /// <example>
-        /// new { data_name="value" } will translate to the entry { "data-name" , "value" }
+        /// <c>new { data_name="value" }</c> will translate to the entry <c>{ "data-name", "value" }</c>
         /// in the resulting dictionary.
         /// </example>
         /// </summary>
@@ -633,16 +633,21 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// </summary>
         /// <param name="actionName">The name of the action method.</param>
         /// <param name="controllerName">The name of the controller.</param>
-        /// <param name="routeValues">An object that contains the parameters for a route. The parameters are retrieved
+        /// <param name="routeValues">
-        /// through reflection by examining the properties of the object. This object is typically created using object
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
-        /// initializer syntax. Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
-        /// route parameters.</param>
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the route parameters.
+        /// </param>
         /// <param name="method">The HTTP method for processing the form, either GET or POST.</param>
         /// <param name="htmlAttributes">An <see cref="IDictionary{string, object}"/> instance containing HTML
         /// attributes to set for the element.</param>
         /// <returns>
         /// An <see cref="MvcForm"/> instance which emits the &lt;/form&gt; end tag when disposed.
         /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         protected virtual MvcForm GenerateForm(string actionName, string controllerName, object routeValues,
                                                FormMethod method, IDictionary<string, object> htmlAttributes)
         {

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayExtensions.cs

@@ -6,13 +6,62 @@ using System.Linq.Expressions;
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Display-related extensions for <see cref="IHtmlHelper"/> and <see cref="IHtmlHelper{TModel}"/>.
+    /// </summary>
     public static class HtmlHelperDisplayExtensions
     {
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template. The template is found
+        /// using the <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to display.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         public static HtmlString Display([NotNull] this IHtmlHelper html, string expression)
         {
             return html.Display(expression, templateName: null, htmlFieldName: null, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template and specified
+        /// additional view data. The template is found using the <paramref name="expression"/>'s
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to display.
+        /// </param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         public static HtmlString Display(
             [NotNull] this IHtmlHelper html,
             string expression,
@@ -22,6 +71,28 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template. The template is found
+        /// using the <paramref name="templateName"/> or the <paramref name="expression"/>'s
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to display.
+        /// </param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         public static HtmlString Display(
             [NotNull] this IHtmlHelper html,
             string expression,
@@ -30,6 +101,33 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return html.Display(expression, templateName, htmlFieldName: null, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template and specified
+        /// additional view data. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to display.
+        /// </param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         public static HtmlString Display(
             [NotNull] this IHtmlHelper html,
             string expression,
@@ -39,6 +137,32 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return html.Display(expression, templateName, htmlFieldName: null, additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template and specified HTML
+        /// field name. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s<see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to display.
+        /// </param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="htmlFieldName">
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for
+        /// properties that have the same name.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         public static HtmlString Display(
             [NotNull] this IHtmlHelper html,
             string expression,
@@ -48,6 +172,19 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return html.Display(expression, templateName, htmlFieldName, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template. The template is found
+        /// using the <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString DisplayFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
                                                             [NotNull] Expression<Func<TModel, TValue>> expression)
         {
@@ -55,6 +192,25 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template and specified
+        /// additional view data. The template is found using the <paramref name="expression"/>'s
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString DisplayFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
                                                             [NotNull] Expression<Func<TModel, TValue>> expression,
                                                             object additionalViewData)
@@ -63,6 +219,21 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template. The template is found
+        /// using the <paramref name="templateName"/> or the <paramref name="expression"/>'s
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString DisplayFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
                                                             [NotNull] Expression<Func<TModel, TValue>> expression,
                                                             string templateName)
@@ -70,6 +241,26 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return html.DisplayFor<TValue>(expression, templateName, htmlFieldName: null, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template and specified
+        /// additional view data. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString DisplayFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
                                                             [NotNull] Expression<Func<TModel, TValue>> expression,
                                                             string templateName,
@@ -79,6 +270,25 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template and specified HTML
+        /// field name. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="htmlFieldName">
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for properties
+        /// that have the same name.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString DisplayFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
                                                             [NotNull] Expression<Func<TModel, TValue>> expression,
                                                             string templateName,
@@ -88,23 +298,76 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using a display template. The template is found using the
+        /// model's <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// current model.
+        /// </remarks>
         public static HtmlString DisplayForModel([NotNull] this IHtmlHelper html)
         {
             return html.Display(expression: null, templateName: null, htmlFieldName: null, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using a display template and specified additional view data. The
+        /// template is found using the model's <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// current model.
+        /// </remarks>
         public static HtmlString DisplayForModel([NotNull] this IHtmlHelper html, object additionalViewData)
         {
             return html.Display(expression: null, templateName: null, htmlFieldName: null,
                 additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using a display template. The template is found using the
+        /// <paramref name="templateName"/> or the model's <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// current model.
+        /// </remarks>
         public static HtmlString DisplayForModel([NotNull] this IHtmlHelper html, string templateName)
         {
             return html.Display(expression: null, templateName: templateName, htmlFieldName: null,
                 additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using a display template and specified additional view data. The
+        /// template is found using the <paramref name="templateName"/> or the model's
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// current model.
+        /// </remarks>
         public static HtmlString DisplayForModel(
             [NotNull] this IHtmlHelper html,
             string templateName,
@@ -114,6 +377,22 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using a display template and specified HTML field name. The
+        /// template is found using the <paramref name="templateName"/> or the model's
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="htmlFieldName">
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for
+        /// properties that have the same name.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// current model.
+        /// </remarks>
         public static HtmlString DisplayForModel(
             [NotNull] this IHtmlHelper html,
             string templateName,
@@ -123,6 +402,27 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using a display template, specified HTML field name, and
+        /// additional view data. The template is found using the <paramref name="templateName"/> or the model's
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="htmlFieldName">
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for
+        /// properties that have the same name.
+        /// </param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// current model.
+        /// </remarks>
         public static HtmlString DisplayForModel(
             [NotNull] this IHtmlHelper html,
             string templateName,

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayNameExtensions.cs

@@ -29,7 +29,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// <param name="htmlHelper">
         /// The <see cref="IHtmlHelper{IEnumerable{TModelItem}}"/> instance this method extends.
         /// </param>
-        /// <param name="expression">The expression to be evaluated against an item in the current model.</param>
+        /// <param name="expression">An expression to be evaluated against an item in the current model.</param>
         /// <typeparam name="TModelItem">The type of items in the model collection.</typeparam>
         /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
         /// <returns>A <see cref="string"/> containing the display name.</returns>

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperEditorExtensions.cs

@@ -6,42 +6,198 @@ using System.Linq.Expressions;
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Editor-related extensions for <see cref="IHtmlHelper"/> and <see cref="IHtmlHelper{TModel}"/>.
+    /// </summary>
     public static class HtmlHelperEditorExtensions
     {
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template. The template is found
+        /// using the <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to edit.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         public static HtmlString Editor([NotNull] this IHtmlHelper html, string expression)
         {
             return html.Editor(expression, templateName: null, htmlFieldName: null, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template and specified
+        /// additional view data. The template is found using the <paramref name="expression"/>'s
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to edit.
+        /// </param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         public static HtmlString Editor([NotNull] this IHtmlHelper html, string expression, object additionalViewData)
         {
             return html.Editor(expression, templateName: null, htmlFieldName: null,
                 additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template. The template is found
+        /// using the <paramref name="templateName"/> or the <paramref name="expression"/>'s
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to edit.
+        /// </param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         public static HtmlString Editor([NotNull] this IHtmlHelper html, string expression, string templateName)
         {
             return html.Editor(expression, templateName, htmlFieldName: null, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template and specified
+        /// additional view data. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to edit.
+        /// </param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         public static HtmlString Editor([NotNull] this IHtmlHelper html, string expression, string templateName,
             object additionalViewData)
         {
             return html.Editor(expression, templateName, htmlFieldName: null, additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template and specified HTML
+        /// field name. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to edit.
+        /// </param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="htmlFieldName">
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for
+        /// properties that have the same name.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         public static HtmlString Editor([NotNull] this IHtmlHelper html, string expression, string templateName,
             string htmlFieldName)
         {
             return html.Editor(expression, templateName, htmlFieldName, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template. The template is found
+        /// using the <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString EditorFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
             [NotNull] Expression<Func<TModel, TValue>> expression)
         {
             return html.EditorFor(expression, templateName: null, htmlFieldName: null, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template and specified
+        /// additional view data. The template is found using the <paramref name="expression"/>'s
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString EditorFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
             [NotNull] Expression<Func<TModel, TValue>> expression, object additionalViewData)
         {
@@ -49,12 +205,47 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template. The template is found
+        /// using the <paramref name="templateName"/> or the <paramref name="expression"/>'s
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="templateName">The name of the template that is used to create the HTML markup.</param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString EditorFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
             [NotNull] Expression<Func<TModel, TValue>> expression, string templateName)
         {
             return html.EditorFor(expression, templateName, htmlFieldName: null, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template and specified
+        /// additional view data. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="templateName">The name of the template that is used to create the HTML markup.</param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString EditorFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
             [NotNull] Expression<Func<TModel, TValue>> expression, string templateName, object additionalViewData)
         {
@@ -62,29 +253,101 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template and specified HTML
+        /// field name. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="templateName">The name of the template that is used to create the HTML markup.</param>
+        /// <param name="htmlFieldName">
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for properties
+        /// that have the same name.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString EditorFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
             [NotNull] Expression<Func<TModel, TValue>> expression, string templateName, string htmlFieldName)
         {
             return html.EditorFor(expression, templateName, htmlFieldName, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using an editor template. The template is found using the
+        /// model's <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/> result.
+        /// </remarks>
         public static HtmlString EditorForModel([NotNull] this IHtmlHelper html)
         {
             return html.Editor(expression: null, templateName: null, htmlFieldName: null, additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using an editor template and specified additional view data. The
+        /// template is found using the model's <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the current model.
+        /// </remarks>
         public static HtmlString EditorForModel([NotNull] this IHtmlHelper html, object additionalViewData)
         {
             return html.Editor(expression: null, templateName: null, htmlFieldName: null,
                 additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using an editor template. The template is found using the
+        /// <paramref name="templateName"/> or the model's <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the current model.
+        /// </remarks>
         public static HtmlString EditorForModel([NotNull] this IHtmlHelper html, string templateName)
         {
             return html.Editor(expression: null, templateName: templateName, htmlFieldName: null,
                 additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using an editor template and specified additional view data. The
+        /// template is found using the <paramref name="templateName"/> or the model's
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the current model.
+        /// </remarks>
         public static HtmlString EditorForModel([NotNull] this IHtmlHelper html, string templateName,
             object additionalViewData)
         {
@@ -92,6 +355,22 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: additionalViewData);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using an editor template and specified HTML field name. The
+        /// template is found using the <paramref name="templateName"/> or the model's
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="htmlFieldName">
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for
+        /// properties that have the same name.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the current model.
+        /// </remarks>
         public static HtmlString EditorForModel([NotNull] this IHtmlHelper html, string templateName,
             string htmlFieldName)
         {
@@ -99,6 +378,27 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 additionalViewData: null);
         }
 
+        /// <summary>
+        /// Returns HTML markup for the current model, using an editor template, specified HTML field name, and
+        /// additional view data. The template is found using the <paramref name="templateName"/> or the model's
+        /// <see cref="ModelBinding.ModelMetadata"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
+        /// <param name="htmlFieldName">
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for
+        /// properties that have the same name.
+        /// </param>
+        /// <param name="additionalViewData">
+        /// An anonymous <see cref="object"/> or <see cref="System.Collections.Generic.IDictionary{string, object}"/>
+        /// that can contain additional view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/>
+        /// instance created for the template.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the current model.
+        /// </remarks>
         public static HtmlString EditorForModel([NotNull] this IHtmlHelper html, string templateName,
             string htmlFieldName, object additionalViewData)
         {

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperFormExtensions.cs

@@ -3,8 +3,23 @@
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// DisplayName-related extensions for <see cref="IHtmlHelper"/>.
+    /// </summary>
     public static class HtmlHelperFormExtensions
     {
+        /// <summary>
+        /// Renders a &lt;form&gt; start tag to the response. When the user submits the form,
+        /// the request will be processed by same action. That is the rendered URL will match the current
+        /// request.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <returns>
+        /// An <see cref="MvcForm"/> instance which renders the &lt;/form&gt; end tag when disposed.
+        /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static MvcForm BeginForm([NotNull] this IHtmlHelper htmlHelper)
         {
             // Generates <form action="{current url}" method="post">.
@@ -12,12 +27,41 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                         method: FormMethod.Post, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Renders a &lt;form&gt; start tag to the response. When the user submits the form,
+        /// the request will be processed by an action method.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="method">The HTTP method for processing the form, either GET or POST.</param>
+        /// <returns>
+        /// An <see cref="MvcForm"/> instance which renders the &lt;/form&gt; end tag when disposed.
+        /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static MvcForm BeginForm([NotNull] this IHtmlHelper htmlHelper, FormMethod method)
         {
             return htmlHelper.BeginForm(actionName: null, controllerName: null, routeValues: null,
                                         method: method, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Renders a &lt;form&gt; start tag to the response. When the user submits the form,
+        /// the request will be processed by an action method.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="method">The HTTP method for processing the form, either GET or POST.</param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <returns>
+        /// An <see cref="MvcForm"/> instance which renders the &lt;/form&gt; end tag when disposed.
+        /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             FormMethod method,
@@ -27,12 +71,43 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                         method: method, htmlAttributes: htmlAttributes);
         }
 
+        /// <summary>
+        /// Renders a &lt;form&gt; start tag to the response. When the user submits the form,
+        /// the request will be processed by an action method.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <returns>
+        /// An <see cref="MvcForm"/> instance which renders the &lt;/form&gt; end tag when disposed.
+        /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static MvcForm BeginForm([NotNull] this IHtmlHelper htmlHelper, object routeValues)
         {
             return htmlHelper.BeginForm(actionName: null, controllerName: null, routeValues: routeValues,
                                         method: FormMethod.Post, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Renders a &lt;form&gt; start tag to the response. When the user submits the form,
+        /// the request will be processed by an action method.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="actionName">The name of the action method.</param>
+        /// <param name="controllerName">The name of the controller.</param>
+        /// <returns>
+        /// An <see cref="MvcForm"/> instance which renders the &lt;/form&gt; end tag when disposed.
+        /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             string actionName,
@@ -42,6 +117,26 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                         method: FormMethod.Post, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Renders a &lt;form&gt; start tag to the response. When the user submits the form,
+        /// the request will be processed by an action method.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="actionName">The name of the action method.</param>
+        /// <param name="controllerName">The name of the controller.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <returns>
+        /// An <see cref="MvcForm"/> instance which renders the &lt;/form&gt; end tag when disposed.
+        /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             string actionName,
@@ -52,6 +147,20 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                         FormMethod.Post, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Renders a &lt;form&gt; start tag to the response. When the user submits the form,
+        /// the request will be processed by an action method.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="actionName">The name of the action method.</param>
+        /// <param name="controllerName">The name of the controller.</param>
+        /// <param name="method">The HTTP method for processing the form, either GET or POST.</param>
+        /// <returns>
+        /// An <see cref="MvcForm"/> instance which renders the &lt;/form&gt; end tag when disposed.
+        /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             string actionName,
@@ -62,6 +171,27 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                         method: method, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Renders a &lt;form&gt; start tag to the response. When the user submits the form,
+        /// the request will be processed by an action method.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="actionName">The name of the action method.</param>
+        /// <param name="controllerName">The name of the controller.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <param name="method">The HTTP method for processing the form, either GET or POST.</param>
+        /// <returns>
+        /// An <see cref="MvcForm"/> instance which renders the &lt;/form&gt; end tag when disposed.
+        /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             string actionName,
@@ -73,6 +203,25 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                         method, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Renders a &lt;form&gt; start tag to the response. When the user submits the form,
+        /// the request will be processed by an action method.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="actionName">The name of the action method.</param>
+        /// <param name="controllerName">The name of the controller.</param>
+        /// <param name="method">The HTTP method for processing the form, either GET or POST.</param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <returns>
+        /// An <see cref="MvcForm"/> instance which renders the &lt;/form&gt; end tag when disposed.
+        /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             string actionName,

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperLabelExtensions.cs

@@ -6,8 +6,17 @@ using System.Linq.Expressions;
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Label-related extensions for <see cref="IHtmlHelper"/> and <see cref="IHtmlHelper{TModel}"/>.
+    /// </summary>
     public static class HtmlHelperLabelExtensions
     {
+        /// <summary>
+        /// Returns a &lt;label&gt; element for the specified expression <paramref name="name"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">Expression name, relative to the current model.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         public static HtmlString Label([NotNull] this IHtmlHelper html, string expression)
         {
             return html.Label(expression,
@@ -15,17 +24,41 @@ namespace Microsoft.AspNet.Mvc.Rendering
                              htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a &lt;label&gt; element for the specified expression <paramref name="name"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">Expression name, relative to the current model.</param>
+        /// <param name="labelText">The inner text of the element.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         public static HtmlString Label([NotNull] this IHtmlHelper html, string expression, string labelText)
         {
             return html.Label(expression, labelText, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a &lt;label&gt; element for the specified <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         public static HtmlString LabelFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
                                                           [NotNull] Expression<Func<TModel, TValue>> expression)
         {
             return html.LabelFor<TValue>(expression, labelText: null, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a &lt;label&gt; element for the specified <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="labelText">The inner text of the element.</param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         public static HtmlString LabelFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
                                                           [NotNull] Expression<Func<TModel, TValue>> expression,
                                                           string labelText)
@@ -33,6 +66,19 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return html.LabelFor<TValue>(expression, labelText, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a &lt;label&gt; element for the specified <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         public static HtmlString LabelFor<TModel, TValue>([NotNull] this IHtmlHelper<TModel> html,
                                                           [NotNull] Expression<Func<TModel, TValue>> expression,
                                                           object htmlAttributes)
@@ -40,21 +86,53 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return html.LabelFor<TValue>(expression, labelText: null, htmlAttributes: htmlAttributes);
         }
 
+        /// <summary>
+        /// Returns a &lt;label&gt; element for the current model.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         public static HtmlString LabelForModel([NotNull] this IHtmlHelper html)
         {
             return html.Label(expression: null, labelText: null, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a &lt;label&gt; element for the current model.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="labelText">The inner text of the element.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         public static HtmlString LabelForModel([NotNull] this IHtmlHelper html, string labelText)
         {
             return html.Label(expression: null, labelText: labelText, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a &lt;label&gt; element for the current model.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         public static HtmlString LabelForModel([NotNull] this IHtmlHelper html, object htmlAttributes)
         {
             return html.Label(expression: null, labelText: null, htmlAttributes: htmlAttributes);
         }
 
+        /// <summary>
+        /// Returns a &lt;label&gt; element for the current model.
+        /// </summary>
+        /// <param name="html">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="labelText">The inner text of the element.</param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         public static HtmlString LabelForModel(
             [NotNull] this IHtmlHelper html,
             string labelText,

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperLinkExtensions.cs

@@ -3,8 +3,18 @@
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Link-related extensions for <see cref="IHtmlHelper"/>.
+    /// </summary>
     public static class HtmlHelperLinkExtensions
     {
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified action.
+        /// </summary>
+        /// <param name="helper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="actionName">The name of the action.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString ActionLink(
             [NotNull] this IHtmlHelper helper,
             [NotNull] string linkText,
@@ -21,6 +31,20 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified action.
+        /// </summary>
+        /// <param name="helper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="actionName">The name of the action.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString ActionLink(
             [NotNull] this IHtmlHelper helper,
             [NotNull] string linkText,
@@ -38,6 +62,25 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified action.
+        /// </summary>
+        /// <param name="helper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="actionName">The name of the action.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString ActionLink(
             [NotNull] this IHtmlHelper helper,
             [NotNull] string linkText,
@@ -56,6 +99,14 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 htmlAttributes: htmlAttributes);
         }
 
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified action.
+        /// </summary>
+        /// <param name="helper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="actionName">The name of the action.</param>
+        /// <param name="controllerName">The name of the controller.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString ActionLink(
             [NotNull] this IHtmlHelper helper,
             [NotNull] string linkText,
@@ -73,6 +124,21 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified action.
+        /// </summary>
+        /// <param name="helper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="actionName">The name of the action.</param>
+        /// <param name="controllerName">The name of the controller.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString ActionLink(
             [NotNull] this IHtmlHelper helper,
             [NotNull] string linkText,
@@ -91,6 +157,26 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified action.
+        /// </summary>
+        /// <param name="helper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="actionName">The name of the action.</param>
+        /// <param name="controllerName">The name of the controller.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString ActionLink(
             [NotNull] this IHtmlHelper helper,
             [NotNull] string linkText,
@@ -110,6 +196,19 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 htmlAttributes: htmlAttributes);
         }
 
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified route.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString RouteLink(
             [NotNull] this IHtmlHelper htmlHelper,
             [NotNull] string linkText,
@@ -125,6 +224,13 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                 htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified route.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="routeName">The name of the route.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString RouteLink(
             [NotNull] this IHtmlHelper htmlHelper,
             [NotNull] string linkText,
@@ -140,6 +246,20 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                 htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified route.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="routeName">The name of the route.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString RouteLink(
             [NotNull] this IHtmlHelper htmlHelper,
             [NotNull] string linkText,
@@ -156,6 +276,24 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                 htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified route.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString RouteLink(
             [NotNull] this IHtmlHelper htmlHelper,
             [NotNull] string linkText,
@@ -172,6 +310,25 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                 htmlAttributes: htmlAttributes);
         }
 
+        /// <summary>
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified route.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
+        /// <param name="routeName">The name of the route.</param>
+        /// <param name="routeValues">
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the route
+        /// parameters.
+        /// </param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
         public static HtmlString RouteLink(
             [NotNull] this IHtmlHelper htmlHelper,
             [NotNull] string linkText,

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperPartialExtensions.cs

@@ -5,15 +5,21 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// PartialView-related extensions for <see cref="IHtmlHelper"/>.
+    /// </summary>
     public static class HtmlHelperPartialExtensions
     {
         /// <summary>
-        /// Renders the partial view with the parent's view data and model to a string.
+        /// Returns HTML markup for the specified partial view.
         /// </summary>
-        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance that this method extends.</param>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
-        /// <param name="partialViewName">The name of the partial view to render.</param>
+        /// <param name="partialViewName">
+        /// The name of the partial view used to create the HTML markup. Must not be <c>null</c>.
+        /// </param>
         /// <returns>
-        /// A <see cref="Task{T}"/> that represents when rendering to the <see cref="HtmlString"/> has completed.
+        /// A <see cref="Task"/> that on completion returns a new <see cref="HtmlString"/> containing
+        /// the created HTML.
         /// </returns>
         public static Task<HtmlString> PartialAsync(
             [NotNull] this IHtmlHelper htmlHelper,
@@ -23,15 +29,16 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <summary>
-        /// Renders the partial view with the given view data and, implicitly, the given view data's model to a string.
+        /// Returns HTML markup for the specified partial view.
         /// </summary>
-        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance that this method extends.</param>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
-        /// <param name="partialViewName">The name of the partial view to render.</param>
+        /// <param name="partialViewName">
-        /// <param name="viewData">
+        /// The name of the partial view used to create the HTML markup. Must not be <c>null</c>.
-        /// The <see cref="ViewDataDictionary"/> that is provided to the partial view that will be rendered.
         /// </param>
+        /// <param name="viewData">A <see cref="ViewDataDictionary"/> to pass into the partial view.</param>
         /// <returns>
-        /// A <see cref="Task{T}"/> that represents when rendering to the <see cref="HtmlString"/> has completed.
+        /// A <see cref="Task"/> that on completion returns a new <see cref="HtmlString"/> containing
+        /// the created HTML.
         /// </returns>
         public static Task<HtmlString> PartialAsync(
             [NotNull] this IHtmlHelper htmlHelper,
@@ -42,13 +49,16 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <summary>
-        /// Renders the partial view with an empty view data and the given model to a string.
+        /// Returns HTML markup for the specified partial view.
         /// </summary>
-        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance that this method extends.</param>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
-        /// <param name="partialViewName">The name of the partial view to render.</param>
+        /// <param name="partialViewName">
-        /// <param name="model">The model to provide to the partial view that will be rendered.</param>
+        /// The name of the partial view used to create the HTML markup. Must not be <c>null</c>.
+        /// </param>
+        /// <param name="model">A model to pass into the partial view.</param>
         /// <returns>
-        /// A <see cref="Task{T}"/> that represents when rendering to the <see cref="HtmlString"/> has completed.
+        /// A <see cref="Task"/> that on completion returns a new <see cref="HtmlString"/> containing
+        /// the created HTML.
         /// </returns>
         public static Task<HtmlString> PartialAsync(
             [NotNull] this IHtmlHelper htmlHelper,
@@ -59,11 +69,16 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <summary>
-        /// Renders the partial view with the parent's view data and model.
+        /// Renders HTML markup for the specified partial view.
         /// </summary>
-        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance that this method extends.</param>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
-        /// <param name="partialViewName">The name of the partial view to render.</param>
+        /// <param name="partialViewName">
-        /// <returns>A <see cref="Task"/> that represents when rendering has completed.</returns>
+        /// The name of the partial view used to create the HTML markup. Must not be <c>null</c>.
+        /// </param>
+        /// <returns>A <see cref="Task"/> that renders the created HTML when it executes.</returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static Task RenderPartialAsync(
             [NotNull] this IHtmlHelper htmlHelper,
             [NotNull] string partialViewName)
@@ -73,14 +88,17 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <summary>
-        /// Renders the partial view with the given view data and, implicitly, the given view data's model.
+        /// Renders HTML markup for the specified partial view.
         /// </summary>
-        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance that this method extends.</param>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
-        /// <param name="partialViewName">The name of the partial view to render.</param>
+        /// <param name="partialViewName">
-        /// <param name="viewData">
+        /// The name of the partial view used to create the HTML markup. Must not be <c>null</c>.
-        /// The <see cref="ViewDataDictionary"/> that is provided to the partial view that will be rendered.
         /// </param>
-        /// <returns>A <see cref="Task"/> that represents when rendering has completed.</returns>
+        /// <param name="viewData">A <see cref="ViewDataDictionary"/> to pass into the partial view.</param>
+        /// <returns>A <see cref="Task"/> that renders the created HTML when it executes.</returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static Task RenderPartialAsync(
             [NotNull] this IHtmlHelper htmlHelper,
             [NotNull] string partialViewName,
@@ -90,12 +108,17 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <summary>
-        /// Renders the partial view with an empty view data and the given model.
+        /// Renders HTML markup for the specified partial view.
         /// </summary>
-        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance that this method extends.</param>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
-        /// <param name="partialViewName">The name of the partial view to render.</param>
+        /// <param name="partialViewName">
-        /// <param name="model">The model to provide to the partial view that will be rendered.</param>
+        /// The name of the partial view used to create the HTML markup. Must not be <c>null</c>.
-        /// <returns>A <see cref="Task"/> that represents when rendering has completed.</returns>
+        /// </param>
+        /// <param name="model">A model to pass into the partial view.</param>
+        /// <returns>A <see cref="Task"/> that renders the created HTML when it executes.</returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         public static Task RenderPartialAsync(
             [NotNull] this IHtmlHelper htmlHelper,
             [NotNull] string partialViewName,

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperSelectExtensions.cs

@@ -7,18 +7,63 @@ using System.Linq.Expressions;
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Select-related extensions for <see cref="IHtmlHelper"/> and <see cref="IHtmlHelper{TModel}"/>.
+    /// </summary>
     public static class HtmlHelperSelectExtensions
     {
+        /// <summary>
+        /// Returns a single-selection HTML &lt;select&gt; element for the expression <paramref name="name"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;select&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </remarks>
         public static HtmlString DropDownList([NotNull] this IHtmlHelper htmlHelper, string name)
         {
             return htmlHelper.DropDownList(name, selectList: null, optionLabel: null, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a single-selection HTML &lt;select&gt; element for the expression <paramref name="name"/>,
+        /// using the option label.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
+        /// <param name="optionLabel">
+        /// The text for a default empty item. Does not include such an item if argument is <c>null</c>.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;select&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </remarks>
         public static HtmlString DropDownList([NotNull] this IHtmlHelper htmlHelper, string name, string optionLabel)
         {
             return htmlHelper.DropDownList(name, selectList: null, optionLabel: optionLabel, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a single-selection HTML &lt;select&gt; element for the expression <paramref name="name"/>,
+        /// using the specified list items.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
+        /// <param name="selectList">
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;select&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </remarks>
         public static HtmlString DropDownList(
             [NotNull] this IHtmlHelper htmlHelper,
             string name,
@@ -27,6 +72,26 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.DropDownList(name, selectList, optionLabel: null, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a single-selection HTML &lt;select&gt; element for the expression <paramref name="name"/>,
+        /// using the specified list items and HTML attributes.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
+        /// <param name="selectList">
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
+        /// </param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the &lt;select&gt; element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;select&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </remarks>
         public static HtmlString DropDownList(
             [NotNull] this IHtmlHelper htmlHelper,
             string name,
@@ -36,6 +101,25 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.DropDownList(name, selectList, optionLabel: null, htmlAttributes: htmlAttributes);
         }
 
+        /// <summary>
+        /// Returns a single-selection HTML &lt;select&gt; element for the expression <paramref name="name"/>,
+        /// using the specified list items and option label.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
+        /// <param name="selectList">
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
+        /// </param>
+        /// <param name="optionLabel">
+        /// The text for a default empty item. Does not include such an item if argument is <c>null</c>.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;select&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </remarks>
         public static HtmlString DropDownList(
             [NotNull] this IHtmlHelper htmlHelper,
             string name,
@@ -45,12 +129,52 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.DropDownList(name, selectList, optionLabel, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a single-selection HTML &lt;select&gt; element for the <paramref name="expression"/>, using the
+        /// specified list items.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="selectList">
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set &lt;select&gt; element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute.
+        /// </remarks>
         public static HtmlString DropDownListFor<TModel, TProperty>([NotNull] this IHtmlHelper<TModel> htmlHelper,
             [NotNull] Expression<Func<TModel, TProperty>> expression, IEnumerable<SelectListItem> selectList)
         {
             return htmlHelper.DropDownListFor(expression, selectList, optionLabel: null, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a single-selection HTML &lt;select&gt; element for the <paramref name="expression"/>, using the
+        /// specified list items and HTML attributes.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="selectList">
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
+        /// </param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the &lt;select&gt; element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set &lt;select&gt; element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute.
+        /// </remarks>
         public static HtmlString DropDownListFor<TModel, TProperty>([NotNull] this IHtmlHelper<TModel> htmlHelper,
             [NotNull] Expression<Func<TModel, TProperty>> expression, IEnumerable<SelectListItem> selectList,
             object htmlAttributes)
@@ -59,6 +183,27 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 htmlAttributes: htmlAttributes);
         }
 
+        /// <summary>
+        /// Returns a single-selection HTML &lt;select&gt; element for the <paramref name="expression"/>, using the
+        /// specified list items and option label.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="selectList">
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
+        /// </param>
+        /// <param name="optionLabel">
+        /// The text for a default empty item. Does not include such an item if argument is <c>null</c>.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set &lt;select&gt; element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute.
+        /// </remarks>
         public static HtmlString DropDownListFor<TModel, TProperty>([NotNull] this IHtmlHelper<TModel> htmlHelper,
             [NotNull] Expression<Func<TModel, TProperty>> expression, IEnumerable<SelectListItem> selectList,
             string optionLabel)
@@ -66,11 +211,38 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.DropDownListFor(expression, selectList, optionLabel, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a multi-selection &lt;select&gt; element for the expression <paramref name="name"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;select&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </remarks>
         public static HtmlString ListBox([NotNull] this IHtmlHelper htmlHelper, string name)
         {
             return htmlHelper.ListBox(name, selectList: null, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a multi-selection &lt;select&gt; element for the expression <paramref name="name"/>, using the
+        /// specified list items.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
+        /// <param name="selectList">
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;select&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </remarks>
         public static HtmlString ListBox(
             [NotNull] this IHtmlHelper htmlHelper,
             string name,
@@ -79,6 +251,24 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.ListBox(name, selectList, htmlAttributes: null);
         }
 
+        /// <summary>
+        /// Returns a multi-selection &lt;select&gt; element for the  <paramref name="expression"/>, using the
+        /// specified list items.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="selectList">
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set &lt;select&gt; element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute.
+        /// </remarks>
         public static HtmlString ListBoxFor<TModel, TProperty>(
             [NotNull] this IHtmlHelper<TModel> htmlHelper,
             [NotNull] Expression<Func<TModel, TProperty>> expression,

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValidationExtensions.cs

@@ -6,14 +6,48 @@ using System.Linq.Expressions;
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Validation-related extensions for <see cref="IHtmlHelper"/> and <see cref="IHtmlHelper{TModel}"/>.
+    /// </summary>
     public static class HtmlHelperValidationExtensions
     {
+        /// <summary>
+        /// Returns the validation message if an error exists in the <see cref="ModelBinding.ModelStateDictionary"/>
+        /// object for the specified expression <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">Expression name, relative to the current model.</param>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing a <see cref="ViewContext.ValidationMessageElement"/> element.
+        /// <c>null</c> if the expression <paramref name="expression"/> is valid and client-side validation is
+        /// disabled.
+        /// </returns>
+        /// <remarks>
+        /// Method extracts an error string from the <see cref="ModelBinding.ModelStateDictionary"/> object. Message
+        /// will always be visible but client-side validation may update the associated CSS class.
+        /// </remarks>
         public static HtmlString ValidationMessage([NotNull] this IHtmlHelper htmlHelper,
             string expression)
         {
             return htmlHelper.ValidationMessage(expression, message: null, htmlAttributes: null, tag: null);
         }
 
+        /// <summary>
+        /// Returns the validation message if an error exists in the <see cref="ModelBinding.ModelStateDictionary"/>
+        /// object for the specified expression <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">Expression name, relative to the current model.</param>
+        /// <param name="message">
+        /// The message to be displayed. If <c>null</c> or empty, method extracts an error string from the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object. Message will always be visible but client-side
+        /// validation may update the associated CSS class.
+        /// </param>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing a <see cref="ViewContext.ValidationMessageElement"/> element.
+        /// <c>null</c> if the expression <paramref name="expression"/> is valid and client-side validation is
+        /// disabled.
+        /// </returns>
         public static HtmlString ValidationMessage([NotNull] this IHtmlHelper htmlHelper,
             string expression,
             string message)
@@ -21,6 +55,27 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.ValidationMessage(expression, message, htmlAttributes: null, tag: null);
         }
 
+        /// <summary>
+        /// Returns the validation message if an error exists in the <see cref="ModelBinding.ModelStateDictionary"/>
+        /// object for the specified expression <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">Expression name, relative to the current model.</param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the
+        /// (<see cref="ViewContext.ValidationMessageElement"/>) element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing a <see cref="ViewContext.ValidationMessageElement"/> element.
+        /// <c>null</c> if the expression <paramref name="expression"/> is valid and client-side validation is
+        /// disabled.
+        /// </returns>
+        /// <remarks>
+        /// Method extracts an error string from the <see cref="ModelBinding.ModelStateDictionary"/> object. Message
+        /// will always be visible but client-side validation may update the associated CSS class.
+        /// </remarks>
         public static HtmlString ValidationMessage([NotNull] this IHtmlHelper htmlHelper,
             string expression,
             object htmlAttributes)
@@ -28,6 +83,25 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.ValidationMessage(expression, message: null, htmlAttributes: htmlAttributes, tag: null);
         }
 
+        /// <summary>
+        /// Returns the validation message if an error exists in the <see cref="ModelBinding.ModelStateDictionary"/>
+        /// object for the specified expression <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">Expression name, relative to the current model.</param>
+        /// <param name="message">
+        /// The message to be displayed. If <c>null</c> or empty, method extracts an error string from the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object. Message will always be visible but client-side
+        /// validation may update the associated CSS class.
+        /// </param>
+        /// <param name="tag">
+        /// The tag to wrap the <paramref name="message"/> in the generated HTML. Its default value is
+        /// <see cref="ViewContext.ValidationMessageElement"/>.
+        /// </param>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing a <paramref name="tag"/> element. <c>null</c> if the
+        /// expression <paramref name="expression"/> is valid and client-side validation is disabled.
+        /// </returns>
         public static HtmlString ValidationMessage([NotNull] this IHtmlHelper htmlHelper,
             string expression,
             string message,
@@ -36,6 +110,28 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.ValidationMessage(expression, message, htmlAttributes: null, tag: tag);
         }
 
+        /// <summary>
+        /// Returns the validation message if an error exists in the <see cref="ModelBinding.ModelStateDictionary"/>
+        /// object for the specified expression <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">Expression name, relative to the current model.</param>
+        /// <param name="message">
+        /// The message to be displayed. If <c>null</c> or empty, method extracts an error string from the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object. Message will always be visible but client-side
+        /// validation may update the associated CSS class.
+        /// </param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the
+        /// (<see cref="ViewContext.ValidationMessageElement"/>) element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing a <see cref="ViewContext.ValidationMessageElement"/> element.
+        /// <c>null</c> if the expression <paramref name="expression"/> is valid and client-side validation is
+        /// disabled.
+        /// </returns>
         public static HtmlString ValidationMessage([NotNull] this IHtmlHelper htmlHelper,
             string expression,
             string message,
@@ -44,12 +140,47 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.ValidationMessage(expression, message, htmlAttributes, tag: null);
         }
 
+        /// <summary>
+        /// Returns the validation message if an error exists in the <see cref="ModelBinding.ModelStateDictionary"/>
+        /// object for the specified <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing a <see cref="ViewContext.ValidationMessageElement"/> element.
+        /// <c>null</c> if the expression <paramref name="expression"/> is valid and client-side validation is
+        /// disabled.
+        /// </returns>
+        /// <remarks>
+        /// Method extracts an error string from the <see cref="ModelBinding.ModelStateDictionary"/> object. Message
+        /// will always be visible but client-side validation may update the associated CSS class.
+        /// </remarks>
         public static HtmlString ValidationMessageFor<TModel, TProperty>([NotNull] this IHtmlHelper<TModel> htmlHelper,
             [NotNull] Expression<Func<TModel, TProperty>> expression)
         {
             return htmlHelper.ValidationMessageFor(expression, message: null, htmlAttributes: null, tag: null);
         }
 
+        /// <summary>
+        /// Returns the validation message if an error exists in the <see cref="ModelBinding.ModelStateDictionary"/>
+        /// object for the specified <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="message">
+        /// The message to be displayed. If <c>null</c> or empty, method extracts an error string from the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object. Message will always be visible but client-side
+        /// validation may update the associated CSS class.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing a <see cref="ViewContext.ValidationMessageElement"/> element.
+        /// <c>null</c> if the expression <paramref name="expression"/> is valid and client-side validation is
+        /// disabled.
+        /// </returns>
         public static HtmlString ValidationMessageFor<TModel, TProperty>([NotNull] this IHtmlHelper<TModel> htmlHelper,
             [NotNull] Expression<Func<TModel, TProperty>> expression,
             string message)
@@ -57,6 +188,30 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.ValidationMessageFor(expression, message, htmlAttributes: null, tag: null);
         }
 
+        /// <summary>
+        /// Returns the validation message if an error exists in the <see cref="ModelBinding.ModelStateDictionary"/>
+        /// object for the specified <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="message">
+        /// The message to be displayed. If <c>null</c> or empty, method extracts an error string from the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object. Message will always be visible but client-side
+        /// validation may update the associated CSS class.
+        /// </param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the
+        /// (<see cref="ViewContext.ValidationMessageElement"/>) element. Alternatively, an
+        /// <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing the HTML
+        /// attributes.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing a <see cref="ViewContext.ValidationMessageElement"/> element.
+        /// <c>null</c> if the expression <paramref name="expression"/> is valid and client-side validation is
+        /// disabled.
+        /// </returns>
         public static HtmlString ValidationMessageFor<TModel, TProperty>([NotNull] this IHtmlHelper<TModel> htmlHelper,
             [NotNull] Expression<Func<TModel, TProperty>> expression,
             string message,
@@ -65,6 +220,27 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.ValidationMessageFor(expression, message, htmlAttributes, tag: null);
         }
 
+        /// <summary>
+        /// Returns the validation message if an error exists in the <see cref="ModelBinding.ModelStateDictionary"/>
+        /// object for the specified <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
+        /// <param name="message">
+        /// The message to be displayed. If <c>null</c> or empty, method extracts an error string from the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object. Message will always be visible but client-side
+        /// validation may update the associated CSS class.
+        /// </param>
+        /// <param name="tag">
+        /// The tag to wrap the <paramref name="message"/> in the generated HTML. Its default value is
+        /// <see cref="ViewContext.ValidationMessageElement"/>.
+        /// </param>
+        /// <typeparam name="TModel">The type of the model.</typeparam>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing the <paramref name="tag"/> element. <c>null</c> if the
+        /// <paramref name="expression"/> is valid and client-side validation is disabled.
+        /// </returns>
         public static HtmlString ValidationMessageFor<TModel, TProperty>([NotNull] this IHtmlHelper<TModel> htmlHelper,
             [NotNull] Expression<Func<TModel, TProperty>> expression,
             string message,
@@ -73,6 +249,15 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return htmlHelper.ValidationMessageFor(expression, message, htmlAttributes: null, tag: tag);
         }
 
+        /// <summary>
+        /// Returns an unordered list (&lt;ul&gt; element) of validation messages that are in the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <returns>
+        /// New <see cref="HtmlString"/> containing a &lt;div&gt; element wrapping the &lt;ul&gt; element.
+        /// <see cref="HtmlString.Empty"/> if the current model is valid and client-side validation is disabled).
+        /// </returns>
         public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper)
         {
             return htmlHelper.ValidationSummary(excludePropertyErrors: false,
@@ -81,6 +266,18 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 tag: null);
         }
 
+        /// <summary>
+        /// Returns an unordered list (&lt;ul&gt; element) of validation messages that are in the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="excludePropertyErrors">
+        /// If <c>true</c>, display model-level errors only; otherwise display all errors.
+        /// </param>
+        /// <returns>
+        /// New <see cref="HtmlString"/> containing a &lt;div&gt; element wrapping the &lt;ul&gt; element.
+        /// <see cref="HtmlString.Empty"/> if the current model is valid and client-side validation is disabled).
+        /// </returns>
         public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, bool excludePropertyErrors)
         {
             return htmlHelper.ValidationSummary(excludePropertyErrors,
@@ -89,6 +286,18 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 tag: null);
         }
 
+        /// <summary>
+        /// Returns an unordered list (&lt;ul&gt; element) of validation messages that are in the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="message">The message to display with the validation summary.</param>
+        /// <returns>
+        /// New <see cref="HtmlString"/> containing a &lt;div&gt; element wrapping the
+        /// <see cref="ViewContext.ValidationSummaryMessageElement" /> element (which wraps the
+        /// <paramref name="message"/>) and the &lt;ul&gt; element. <see cref="HtmlString.Empty"/> if the current model
+        /// is valid and client-side validation is disabled).
+        /// </returns>
         public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, string message)
         {
             return htmlHelper.ValidationSummary(excludePropertyErrors: false,
@@ -97,6 +306,21 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 tag: null);
         }
 
+        /// <summary>
+        /// Returns an unordered list (&lt;ul&gt; element) of validation messages that are in the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="message">The message to display with the validation summary.</param>
+        /// <param name="tag">
+        /// The tag to wrap the <paramref name="message"/> in the generated HTML. Its default value is
+        /// <see cref="ViewContext.ValidationSummaryMessageElement" />.
+        /// </param>
+        /// <returns>
+        /// New <see cref="HtmlString"/> containing a &lt;div&gt; element wrapping the <paramref name="tag"/> element
+        /// and the &lt;ul&gt; element. <see cref="HtmlString.Empty"/> if the current model is valid and client-side
+        /// validation is disabled).
+        /// </returns>
         public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, string message, string tag)
         {
             return htmlHelper.ValidationSummary(excludePropertyErrors: false,
@@ -105,6 +329,21 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 tag: tag);
         }
 
+        /// <summary>
+        /// Returns an unordered list (&lt;ul&gt; element) of validation messages that are in the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="excludePropertyErrors">
+        /// If <c>true</c>, display model-level errors only; otherwise display all errors.
+        /// </param>
+        /// <param name="message">The message to display with the validation summary.</param>
+        /// <returns>
+        /// New <see cref="HtmlString"/> containing a &lt;div&gt; element wrapping the
+        /// <see cref="ViewContext.ValidationSummaryMessageElement" /> element (which, in turn, wraps the
+        /// <paramref name="message"/>) and the &lt;ul&gt; element. <see cref="HtmlString.Empty"/> if the current model
+        /// is valid and client-side validation is disabled).
+        /// </returns>
         public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper,
             bool excludePropertyErrors,
             string message)
@@ -115,6 +354,23 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 tag: null);
         }
 
+        /// <summary>
+        /// Returns an unordered list (&lt;ul&gt; element) of validation messages that are in the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="message">The message to display with the validation summary.</param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the topmost (&lt;div&gt;) element.
+        /// Alternatively, an <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing
+        /// the HTML attributes.
+        /// </param>
+        /// <returns>
+        /// New <see cref="HtmlString"/> containing a &lt;div&gt; element wrapping the
+        /// <see cref="ViewContext.ValidationSummaryMessageElement" /> element (which wraps the
+        /// <paramref name="message"/>) and the &lt;ul&gt; element. <see cref="HtmlString.Empty"/> if the current model
+        /// is valid and client-side validation is disabled).
+        /// </returns>
         public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper,
             string message,
             object htmlAttributes)
@@ -123,6 +379,26 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 excludePropertyErrors: false, message: message, htmlAttributes: htmlAttributes, tag: null);
         }
 
+        /// <summary>
+        /// Returns an unordered list (&lt;ul&gt; element) of validation messages that are in the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="message">The message to display with the validation summary.</param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the topmost (&lt;div&gt;) element.
+        /// Alternatively, an <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing
+        /// the HTML attributes.
+        /// </param>
+        /// <param name="tag">
+        /// The tag to wrap the <paramref name="message"/> in the generated HTML. Its default value is
+        /// <see cref="ViewContext.ValidationSummaryMessageElement" />.
+        /// </param>
+        /// <returns>
+        /// New <see cref="HtmlString"/> containing a &lt;div&gt; element wrapping the <paramref name="tag"/> element
+        /// and the &lt;ul&gt; element. <see cref="HtmlString.Empty"/> if the current model is valid and client-side
+        /// validation is disabled).
+        /// </returns>
         public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper,
             string message,
             object htmlAttributes,
@@ -132,6 +408,24 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 excludePropertyErrors: false, message: message, htmlAttributes: htmlAttributes, tag: tag);
         }
 
+        /// <summary>
+        /// Returns an unordered list (&lt;ul&gt; element) of validation messages that are in the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="excludePropertyErrors">
+        /// If <c>true</c>, display model-level errors only; otherwise display all errors.
+        /// </param>
+        /// <param name="message">The message to display with the validation summary.</param>
+        /// <param name="tag">
+        /// The tag to wrap the <paramref name="message"/> in the generated HTML. Its default value is
+        /// <see cref="ViewContext.ValidationSummaryMessageElement" />.
+        /// </param>
+        /// <returns>
+        /// New <see cref="HtmlString"/> containing a &lt;div&gt; element wrapping the <paramref name="tag"/> element
+        /// and the &lt;ul&gt; element. <see cref="HtmlString.Empty"/> if the current model is valid and client-side
+        /// validation is disabled).
+        /// </returns>
         public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper,
             bool excludePropertyErrors,
             string message,
@@ -143,6 +437,26 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 tag: tag);
         }
 
+        /// <summary>
+        /// Returns an unordered list (&lt;ul&gt; element) of validation messages that are in the
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="excludePropertyErrors">
+        /// If <c>true</c>, display model-level errors only; otherwise display all errors.
+        /// </param>
+        /// <param name="message">The message to display with the validation summary.</param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the topmost (&lt;div&gt;) element.
+        /// Alternatively, an <see cref="System.Collections.Generic.IDictionary{string, object}"/> instance containing
+        /// the HTML attributes.
+        /// </param>
+        /// <returns>
+        /// New <see cref="HtmlString"/> containing a &lt;div&gt; element wrapping the
+        /// <see cref="ViewContext.ValidationSummaryMessageElement" /> element (which wraps the
+        /// <paramref name="message"/>) and the &lt;ul&gt; element. <see cref="HtmlString.Empty"/> if the current model
+        /// is valid and client-side validation is disabled).
+        /// </returns>
         public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper,
             bool excludePropertyErrors,
             string message,

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValueExtensions.cs

@@ -18,7 +18,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// <param name="name">Expression name, relative to the current model.</param>
         /// <returns>A <see cref="string"/> containing the formatted value.</returns>
         /// <remarks>
-        /// Converts the expression <paramref name="name"/> result to a <see cref="string"/> directly.
+        /// Converts the expression result to a <see cref="string"/> directly.
         /// </remarks>
         public static string Value([NotNull] this IHtmlHelper htmlHelper, string name)
         {
@@ -29,7 +29,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// Returns the formatted value for the specified <paramref name="expression"/>.
         /// </summary>
         /// <param name="htmlHelper">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
-        /// <param name="expression">The expression to be evaluated against the current model.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
         /// <typeparam name="TModel">The type of the model.</typeparam>
         /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
         /// <returns>A <see cref="string"/> containing the formatted value.</returns>

src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelper.cs

@@ -45,26 +45,25 @@ namespace Microsoft.AspNet.Mvc.Rendering
         ViewDataDictionary ViewData { get; }
 
         /// <summary>
-        /// Returns an anchor element (a element) that contains a URL path to the specified action.
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified action.
         /// </summary>
-        /// <param name="linkText">The inner text of the anchor element.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
         /// <param name="actionName">The name of the action.</param>
         /// <param name="controllerName">The name of the controller.</param>
         /// <param name="protocol">The protocol for the URL, such as &quot;http&quot; or &quot;https&quot;.</param>
         /// <param name="hostname">The host name for the URL.</param>
         /// <param name="fragment">The URL fragment name (the anchor name).</param>
         /// <param name="routeValues">
-        /// An object that contains the parameters for a route. The parameters are retrieved through reflection by
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
-        /// examining the properties of the object. This object is typically created using object initializer syntax.
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the route parameters.
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the route parameters.
         /// </param>
         /// <param name="htmlAttributes">
-        /// An object that contains the HTML attributes to set for the element. Alternatively, an
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
         /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <returns>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
-        /// An anchor element (a element).
-        /// </returns>
         HtmlString ActionLink(
             [NotNull] string linkText,
             string actionName,
@@ -76,11 +75,10 @@ namespace Microsoft.AspNet.Mvc.Rendering
             object htmlAttributes);
 
         /// <summary>
-        /// Generates a hidden form field (anti-forgery token) that is validated when the form is submitted.
+        /// Returns a &lt;hidden&gt; element (anti-forgery token) that will be validated when the containing
+        /// &lt;form&gt; is submitted.
         /// </summary>
-        /// <returns>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;hidden&gt; element.</returns>
-        /// The generated form field (anti-forgery token).
-        /// </returns>
         HtmlString AntiForgeryToken();
 
         /// <summary>
@@ -89,17 +87,23 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// </summary>
         /// <param name="actionName">The name of the action method.</param>
         /// <param name="controllerName">The name of the controller.</param>
-        /// <param name="routeValues">An object that contains the parameters for a route. The parameters are retrieved
+        /// <param name="routeValues">
-        /// through reflection by examining the properties of the object. This object is typically created using object
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
-        /// initializer syntax. Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
-        /// route parameters.</param>
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the route parameters.
+        /// </param>
         /// <param name="method">The HTTP method for processing the form, either GET or POST.</param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// <param name="htmlAttributes">
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
         /// <returns>
         /// An <see cref="MvcForm"/> instance which renders the &lt;/form&gt; end tag when disposed.
         /// </returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         MvcForm BeginForm(
             string actionName,
             string controllerName,
@@ -108,39 +112,78 @@ namespace Microsoft.AspNet.Mvc.Rendering
             object htmlAttributes);
 
         /// <summary>
-        /// Render an input element of type "checkbox" with value "true" and an input element of type "hidden" with
+        /// Returns an &lt;input&gt; element of type "checkbox" with value "true" and an &lt;input&gt; element of type
-        /// value "false".
+        /// "hidden" with value "false".
         /// </summary>
-        /// <param name="name">
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// Rendered element's name. Also use this name to find value in submitted data or view data. Use view data
+        /// <param name="isChecked">If <c>true</c>, checkbox is initially checked.</param>
-        /// only if value is not in submitted data and <paramref name="value"/> is <c>null</c>.
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the checkbox element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="isChecked">
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; elements.</returns>
-        /// If <c>true</c>, checkbox is initially checked. Ignore if named value is found in submitted data. Finally
+        /// <remarks>
-        /// fall back to an existing "checked" value in <paramref name="htmlAttributes"/>.
+        /// <para>
-        /// </param>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set checkbox
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// element's "name" attribute. Sanitizes <paramref name="name"/> to set checkbox element's "id" attribute.
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// </para>
-        /// </param>
+        /// <para>Determines checkbox element's "checked" attribute based on the following precedence:</para>
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// <list type="number">
+        /// <item>
+        /// <see cref="ModelStateDictionary"/> entry for <paramref name="name"/> (converted to a fully-qualified name)
+        /// if entry exists and can be converted to a <see cref="bool"/>.
+        /// </item>
+        /// <item><paramref name="isChecked"/> if non-<c>null</c>.</item>
+        /// <item>
+        /// <see cref="ViewData"/> entry for <paramref name="name"/> (converted to a fully-qualified name)
+        /// if entry exists and can be converted to a <see cref="bool"/>.
+        /// </item>
+        /// <item>
+        /// Linq expression based on <paramref name="name"/> (converted to a fully-qualified name) run against current
+        /// model if result is non-<c>null</c> and can be converted to a <see cref="bool"/>. For example
+        /// <c>string.Empty</c> identifies the current model and <c>"prop"</c> identifies the current model's "prop"
+        /// property.
+        /// </item>
+        /// <item>Existing "checked" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>Otherwise, does not include a "checked" attribute.</item>
+        /// </list>
+        /// <para>
+        /// In all but the <paramref name="htmlAttributes"/> and default cases, includes a "checked" attribute with
+        /// value "checked" if the <see cref="bool"/> values is <c>true</c>; does not include the attribute otherwise.
+        /// </para>
+        /// </remarks>
         HtmlString CheckBox(string name, bool? isChecked, object htmlAttributes);
 
         /// <summary>
-        /// Returns HTML markup for each property in the object that is represented by the expression, using the
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template, specified HTML field
-        /// specified template, HTML field ID, and additional view data.
+        /// name, and additional view data. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelMetadata"/>.
         /// </summary>
-        /// <param name="expression">An expression that identifies the object that contains the properties to display.
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to display.
         /// </param>
-        /// <param name="templateName">The name of the template that is used to render the object.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
         /// <param name="htmlFieldName">
-        /// A string that is used to disambiguate the names of HTML input elements that are rendered for properties
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for
-        /// that have the same name.
+        /// properties that have the same name.
         /// </param>
         /// <param name="additionalViewData">
-        /// An anonymous object or dictionary that can contain additional view data that will be merged into the
+        /// An anonymous <see cref="object"/> or <see cref="IDictionary{string, object}"/> that can contain additional
-        /// <see cref="ViewDataDictionary{TModel}"/> instance that is created for the template.
+        /// view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/> instance created for the
+        /// template.
         /// </param>
-        /// <returns>The HTML markup for each property in the object that is represented by the expression.</returns>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         HtmlString Display(
             string expression,
             string templateName,
@@ -165,20 +208,27 @@ namespace Microsoft.AspNet.Mvc.Rendering
         string DisplayText(string name);
 
         /// <summary>
-        /// Returns a single-selection HTML &lt;select&gt; element using the specified name of the form field,
+        /// Returns a single-selection HTML &lt;select&gt; element for the expression <paramref name="name"/>,
-        /// list items, option label, and HTML attributes.
+        /// using the specified list items, option label, and HTML attributes.
         /// </summary>
-        /// <param name="name">The name of the form field to return.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// <param name="selectList">A collection of <see cref="SelectListItem"/> objects that are used to populate the
+        /// <param name="selectList">
-        /// drop-down list.</param>
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
-        /// <param name="optionLabel">The text for a default empty item. This parameter can be null.</param>
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
+        /// </param>
+        /// <param name="optionLabel">
+        /// The text for a default empty item. Does not include such an item if argument is <c>null</c>.
+        /// </param>
         /// <param name="htmlAttributes">
-        /// An object that contains the HTML attributes to set for the &lt;select&gt; element. Alternatively, an
+        /// An <see cref="object"/> that contains the HTML attributes for the &lt;select&gt; element. Alternatively, an
         /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <returns>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
-        /// An HTML &lt;select&gt; element with an &lt;option&gt; subelement for each item in the list.
+        /// <remarks>
-        /// </returns>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;select&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </remarks>
         HtmlString DropDownList(
             string name,
             IEnumerable<SelectListItem> selectList,
@@ -186,83 +236,131 @@ namespace Microsoft.AspNet.Mvc.Rendering
             object htmlAttributes);
 
         /// <summary>
-        /// Returns an HTML input element for each property in the object that is represented by the expression, using
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template, specified HTML field
-        /// the specified template, HTML field ID, and additional view data.
+        /// name, and additional view data. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelMetadata"/>.
         /// </summary>
-        /// <param name="expression">An expression that identifies the object that contains the properties to edit.
+        /// <param name="expression">
+        /// Expression name, relative to the current model. May identify a single property or an
+        /// <see cref="object"/> that contains the properties to edit.
         /// </param>
-        /// <param name="templateName">The name of the template that is used to render the object.</param>
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
         /// <param name="htmlFieldName">
-        /// A string that is used to disambiguate the names of HTML input elements that are rendered for properties
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for
-        /// that have the same name.
+        /// properties that have the same name.
         /// </param>
         /// <param name="additionalViewData">
-        /// An anonymous object or dictionary that can contain additional view data that will be merged into the
+        /// An anonymous <see cref="object"/> or <see cref="IDictionary{string, object}"/> that can contain additional
-        /// <see cref="ViewDataDictionary{TModel}"/> instance that is created for the template.
+        /// view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/> instance created for the
+        /// template.
         /// </param>
-        /// <returns>The HTML markup for the input elements for each property in the object that is represented by the
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
-        /// expression.</returns>
+        /// <remarks>
+        /// <para>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/>'s value.
+        /// </para>
+        /// <para>
+        /// Example <paramref name="expression"/>s include <c>string.Empty</c> which identifies the current model and
+        /// <c>"prop"</c> which identifies the current model's "prop" property.
+        /// </para>
+        /// </remarks>
         HtmlString Editor(string expression, string templateName, string htmlFieldName, object additionalViewData);
 
         /// <summary>
-        /// Converts the value of the specified object to an HTML-encoded string.
+        /// Converts the <paramref name="value"/> to an HTML-encoded <see cref="string"/>.
         /// </summary>
-        /// <param name="value">The object to encode.</param>
+        /// <param name="value">The <see cref="object"/> to encode.</param>
-        /// <returns>The HTML-encoded string.</returns>
+        /// <returns>The HTML-encoded <see cref="string"/>.</returns>
         string Encode(object value);
 
         /// <summary>
-        /// Converts the specified string to an HTML-encoded string.
+        /// Converts the specified <see cref="string"/> to an HTML-encoded <see cref="string"/>.
         /// </summary>
-        /// <param name="value">The string to encode.</param>
+        /// <param name="value">The <see cref="string"/> to encode.</param>
-        /// <returns>The HTML-encoded string.</returns>
+        /// <returns>The HTML-encoded <see cref="string"/>.</returns>
         string Encode(string value);
 
         /// <summary>
         /// Renders the &lt;/form&gt; end tag to the response.
         /// </summary>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         void EndForm();
 
         /// <summary>
         /// Formats the value.
         /// </summary>
         /// <param name="value">The value.</param>
-        /// <param name="format">The format string.</param>
+        /// <param name="format">
-        /// <returns>The formatted value.</returns>
+        /// The composite format <see cref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
+        /// </param>
+        /// <returns>A <see cref="string"/> containing the formatted value.</returns>
+        /// <remarks>
+        /// Converts <paramref name="value"/> to a <see cref="string"/> directly if
+        /// <paramref name="format"/> is <c>null</c> or empty.
+        /// </remarks>
         string FormatValue(object value, string format);
 
         /// <summary>
-        /// Creates an HTML element ID using the specified element name.
+        /// Returns an HTML element Id for the specified expression <paramref name="name"/>.
         /// </summary>
-        /// <param name="name">The name of the HTML element.</param>
+        /// <param name="name">
-        /// <returns>The ID of the HTML element.</returns>
+        /// Fully-qualified expression name, ignoring the current model. Must not be <c>null</c>.
+        /// </param>
+        /// <returns>A <see cref="string"/> containing the element Id.</returns>
         string GenerateIdFromName([NotNull] string name);
 
         /// <summary>
-        /// Returns information about about client validation rules for the given <paramref name="metadata"/> or
+        /// Returns information about about client validation rules for the specified <paramref name="metadata"/> or
         /// <paramref name="name"/>. Intended for use in <see cref="IHtmlHelper"/> extension methods.
         /// </summary>
         /// <param name="metadata">Metadata about the <see cref="object"/> of interest.</param>
-        /// <param name="name">Expression name, relative to the current model. Used to determine
+        /// <param name="name">
-        /// <see cref="ModelMetadata"/> when <paramref name="metadata"/> is <c>null</c>; ignored
+        /// Expression name, relative to the current model. Used to determine <see cref="ModelMetadata"/> when
-        /// otherwise.</param>
+        /// <paramref name="metadata"/> is <c>null</c>; ignored otherwise.
+        /// </param>
         /// <returns>An <see cref="IEnumerable{ModelClientValidationRule}"/> containing the relevant rules.</returns>
         IEnumerable<ModelClientValidationRule> GetClientValidationRules(ModelMetadata metadata, string name);
 
         /// <summary>
-        /// Render an input element of type "hidden".
+        /// Returns an &lt;input&gt; element of type "hidden" for the specified expression <paramref name="name"/>.
         /// </summary>
-        /// <param name="name">
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// Rendered element's name. Also use this name to find value in submitted data or view data. Use view data
+        /// <param name="value">If non-<c>null</c>, value to include in the element.</param>
-        /// only if value is not in submitted data and <paramref name="value"/> is <c>null</c>.
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="value">
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element.</returns>
-        /// If non-<c>null</c>, value to include in the element. Ignore if named value is found in submitted data.
+        /// <remarks>
-        /// </param>
+        /// <para>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// &lt;input&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
-        /// </param>
+        /// attribute.
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// </para>
+        /// <para>Determines &lt;input&gt; element's "value" attribute based on the following precedence:</para>
+        /// <list type="number">
+        /// <item>
+        /// <see cref="ModelStateDictionary"/> entry for <paramref name="name"/> (converted to a fully-qualified name)
+        /// if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item><paramref name="value"/> if non-<c>null</c>.</item>
+        /// <item>
+        /// <see cref="ViewData"/> entry for <paramref name="name"/> (converted to a fully-qualified name)
+        /// if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item>
+        /// Linq expression based on <paramref name="name"/> (converted to a fully-qualified name) run against current
+        /// model if result is non-<c>null</c> and can be converted to a <see cref="string"/>. For example
+        /// <c>string.Empty</c> identifies the current model and <c>"prop"</c> identifies the current model's "prop"
+        /// property.
+        /// </item>
+        /// <item>Existing "value" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>Otherwise, <c>string.Empty</c>.</item>
+        /// </list>
+        /// </remarks>
         HtmlString Hidden(string name, object value, object htmlAttributes);
 
         /// <summary>
@@ -273,30 +371,36 @@ namespace Microsoft.AspNet.Mvc.Rendering
         string Id(string name);
 
         /// <summary>
-        /// Returns an HTML label element and the property name of the property that is represented by the specified
+        /// Returns a &lt;label&gt; element for the specified expression <paramref name="name"/>.
-        /// expression.
         /// </summary>
-        /// <param name="expression">An expression that identifies the property to display.</param>
+        /// <param name="expression">Expression name, relative to the current model.</param>
-        /// <param name="labelText">The label text.</param>
+        /// <param name="labelText">The inner text of the element.</param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.</param>
+        /// <param name="htmlAttributes">
-        /// <returns>
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
-        /// An HTML label element and the property name of the property that is represented by the expression.
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
-        /// </returns>
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         HtmlString Label(string expression, string labelText, object htmlAttributes);
 
         /// <summary>
-        /// Returns a multi-selection HTML &lt;select&gt; element using the specified name of the form field,
+        /// Returns a multi-selection &lt;select&gt; element for the expression <paramref name="name"/>, using the
-        /// list items, and HTML attributes.
+        /// specified list items and HTML attributes.
         /// </summary>
-        /// <param name="name">The name of the form field to return.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// <param name="selectList">A collection of <see cref="SelectListItem"/> objects that are used to populate the
+        /// <param name="selectList">
-        /// drop-down list.</param>
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <returns>
+        /// <param name="htmlAttributes">
-        /// An HTML &lt;select&gt; element with an &lt;option&gt; subelement for each item in the list.
+        /// An <see cref="object"/> that contains the HTML attributes for the &lt;select&gt; element. Alternatively, an
-        /// </returns>
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// </param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;select&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </remarks>
         HtmlString ListBox(string name, IEnumerable<SelectListItem> selectList, object htmlAttributes);
 
         /// <summary>
@@ -307,99 +411,153 @@ namespace Microsoft.AspNet.Mvc.Rendering
         string Name(string name);
 
         /// <summary>
-        /// Returns a partial view in string format.
+        /// Returns HTML markup for the specified partial view.
         /// </summary>
-        /// <param name="partialViewName">The name of the partial view to render and return.</param>
+        /// <param name="partialViewName">
+        /// The name of the partial view used to create the HTML markup. Must not be <c>null</c>.
+        /// </param>
         /// <param name="model">A model to pass into the partial view.</param>
         /// <param name="viewData">A <see cref="ViewDataDictionary"/> to pass into the partial view.</param>
-        /// <returns>A task that represents when rendering of the partial view into a string has completed.</returns>
+        /// <returns>
+        /// A <see cref="Task"/> that on completion returns a new <see cref="HtmlString"/> containing
+        /// the created HTML.
+        /// </returns>
         Task<HtmlString> PartialAsync([NotNull] string partialViewName, object model, ViewDataDictionary viewData);
 
         /// <summary>
-        /// Render an input element of type "password".
+        /// Returns an &lt;input&gt; element of type "password" for the specified expression <paramref name="name"/>.
         /// </summary>
-        /// <param name="name">
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// Rendered element's name. Also use this name to find value in view data. Use view data
+        /// <param name="value">If non-<c>null</c>, value to include in the element.</param>
-        /// only if value is not in submitted data and <paramref name="value"/> is <c>null</c>.
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="value">
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element.</returns>
-        /// If non-<c>null</c>, value to include in the element.
+        /// <remarks>
-        /// </param>
+        /// <para>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// &lt;input&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
-        /// </param>
+        /// attribute.
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// </para>
+        /// <para>Determines &lt;input&gt; element's "value" attribute based on the following precedence:</para>
+        /// <list type="number">
+        /// <item><paramref name="value"/> if non-<c>null</c>.</item>
+        /// <item>Existing "value" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>Otherwise, <c>string.Empty</c>.</item>
+        /// </list>
+        /// </remarks>
         HtmlString Password(string name, object value, object htmlAttributes);
 
         /// <summary>
-        /// Render an input element of type "radio".
+        /// Returns an &lt;input&gt; element of type "radio" for the specified expression <paramref name="name"/>.
         /// </summary>
-        /// <param name="name">
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// Rendered element's name. Also use this name to find value in submitted data or view data. Use view data
-        /// only if value is not in submitted data and <paramref name="value"/> is <c>null</c>.
-        /// </param>
         /// <param name="value">
-        /// If non-<c>null</c>, value to include in the element. May be <c>null</c> only if
+        /// If non-<c>null</c>, value to include in the element. Must not be <c>null</c> if
-        /// <paramref name="isChecked"/> is also <c>null</c>. Also compared to value in submitted data or view data to
+        /// <paramref name="isChecked"/> is also <c>null</c> and no "checked" entry exists in
-        /// determine <paramref name="isChecked"/> if that parameter is <c>null</c>. Ignore if named value is found in
+        /// <paramref name="htmlAttributes"/>.
-        /// submitted data.
         /// </param>
         /// <param name="isChecked">
-        /// If <c>true</c>, radio button is initially selected. Ignore if named value is found in submitted data. Fall
+        /// If <c>true</c>, radio button is initially selected. Must not be <c>null</c> if
-        /// back to comparing <paramref name="value"/> with view data if this parameter is <c>null</c>. Finally
+        /// <paramref name="value"/> is also <c>null</c> and no "checked" entry exists in
-        /// fall back to an existing "checked" value in <paramref name="htmlAttributes"/>.
+        /// <paramref name="htmlAttributes"/>.
         /// </param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// <param name="htmlAttributes">
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element.</returns>
+        /// <remarks>
+        /// <para>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;input&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </para>
+        /// <para>Determines element's "value" attribute based on the following precedence:</para>
+        /// <list type="number">
+        /// <item><paramref name="value"/> if non-<c>null</c>.</item>
+        /// <item>Existing "value" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>Otherwise, <c>string.Empty</c>.</item>
+        /// </list>
+        /// <para>Determines &lt;input&gt; element's "checked" attribute based on the following precedence:</para>
+        /// <list type="number">
+        /// <item>
+        /// <see cref="ModelStateDictionary"/> entry for <paramref name="name"/> (converted to a fully-qualified name)
+        /// if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item><paramref name="isChecked"/> if non-<c>null</c>.</item>
+        /// <item>Existing "checked" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>
+        /// <see cref="ViewData"/> entry for <paramref name="name"/> (converted to a fully-qualified name)
+        /// if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item>
+        /// Linq expression based on <paramref name="name"/> (converted to a fully-qualified name) run against current
+        /// model if result is non-<c>null</c> and can be converted to a <see cref="string"/>. For example
+        /// <c>string.Empty</c> identifies the current model and <c>"prop"</c> identifies the current model's "prop"
+        /// property.
+        /// </item>
+        /// <item>Otherwise, does not include a "checked" attribute.</item>
+        /// </list>
+        /// <para>
+        /// In all but the <paramref name="htmlAttributes"/> and default cases, includes a "checked" attribute with
+        /// value "checked" if the <see cref="string"/> values is equal to a converted <see cref="string"/> for
+        /// <paramref name="value"/> or <paramref name="isChecked"/> is <c>true</c> (for that case); does not include
+        /// the attribute otherwise.
+        /// </para>
+        /// </remarks>
         HtmlString RadioButton(string name, object value, bool? isChecked, object htmlAttributes);
 
         /// <summary>
-        /// Wraps HTML markup in an <see cref="HtmlString"/>, which will enable HTML markup to be
+        /// Wraps HTML markup in an <see cref="HtmlString"/>, without HTML-encoding the specified
-        /// rendered to the output without getting HTML encoded.
+        /// <paramref name="value"/>.
         /// </summary>
-        /// <param name="value">HTML markup string.</param>
+        /// <param name="value">HTML markup <see cref="string"/>.</param>
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
+        /// <returns>A new <see cref="HtmlString"/> containing the wrapped <see cref="string"/>.</returns>
         HtmlString Raw(string value);
 
         /// <summary>
-        /// Wraps HTML markup from the string representation of an object in an <see cref="HtmlString"/>,
+        /// Wraps HTML markup from the string representation of an <see cref="object"/> in an
-        /// which will enable HTML markup to be rendered to the output without getting HTML encoded.
+        /// <see cref="HtmlString"/>, without HTML-encoding the string representation.
         /// </summary>
-        /// <param name="value">object with string representation as HTML markup.</param>
+        /// <param name="value">The <see cref="object"/> to wrap.</param>
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
+        /// <returns>A new <see cref="HtmlString"/> containing the wrapped string representation.</returns>
         HtmlString Raw(object value);
 
         /// <summary>
-        /// Renders a partial view.
+        /// Renders HTML markup for the specified partial view.
         /// </summary>
-        /// <param name="partialViewName">The name of the partial view to render.</param>
+        /// <param name="partialViewName">
+        /// The name of the partial view used to create the HTML markup. Must not be <c>null</c>.
+        /// </param>
         /// <param name="model">A model to pass into the partial view.</param>
         /// <param name="viewData">A <see cref="ViewDataDictionary"/> to pass into the partial view.</param>
-        /// <returns>A task that represents when rendering has completed.</returns>
+        /// <returns>A <see cref="Task"/> that renders the created HTML when it executes.</returns>
+        /// <remarks>
+        /// In this context, "renders" means the method writes its output using <see cref="ViewContext.Writer"/>.
+        /// </remarks>
         Task RenderPartialAsync([NotNull] string partialViewName, object model, ViewDataDictionary viewData);
 
         /// <summary>
-        /// Returns an anchor element (a element) that contains a URL path to the specified route.
+        /// Returns an anchor (&lt;a&gt;) element that contains a URL path to the specified route.
         /// </summary>
-        /// <param name="linkText">The inner text of the anchor element.</param>
+        /// <param name="linkText">The inner text of the anchor element. Must not be <c>null</c>.</param>
         /// <param name="routeName">The name of the route.</param>
         /// <param name="protocol">The protocol for the URL, such as &quot;http&quot; or &quot;https&quot;.</param>
         /// <param name="hostName">The host name for the URL.</param>
         /// <param name="fragment">The URL fragment name (the anchor name).</param>
         /// <param name="routeValues">
-        /// An object that contains the parameters for a route. The parameters are retrieved through reflection by
+        /// An <see cref="object"/> that contains the parameters for a route. The parameters are retrieved through
-        /// examining the properties of the object. This object is typically created using object initializer syntax.
+        /// reflection by examining the properties of the <see cref="object"/>. This <see cref="object"/> is typically
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the route parameters.
+        /// created using <see cref="object"/> initializer syntax. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the route parameters.
         /// </param>
         /// <param name="htmlAttributes">
-        /// An object that contains the HTML attributes to set for the element. Alternatively, an
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
         /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <returns>
+        /// <returns>A new <see cref="HtmlString"/> containing the anchor element.</returns>
-        /// An anchor element (a element).
-        /// </returns>
         HtmlString RouteLink(
             [NotNull] string linkText,
             string routeName,
@@ -410,67 +568,137 @@ namespace Microsoft.AspNet.Mvc.Rendering
             object htmlAttributes);
 
         /// <summary>
-        /// Render a textarea.
+        /// Returns a &lt;textarea&gt; element for the specified expression <paramref name="name"/>.
         /// </summary>
-        /// <param name="name">
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// Rendered element's name. Also use this name to find value in submitted data or view data. Use view data
+        /// <param name="value">If non-<c>null</c>, value to include in the element.</param>
-        /// only if value is not in submitted data and <paramref name="value"/> is <c>null</c>.
-        /// </param>
-        /// <param name="value">
-        /// If non-<c>null</c>, value to include in the element. Ignore if named value is found in submitted data.
-        /// </param>
         /// <param name="rows">Number of rows in the textarea.</param>
         /// <param name="columns">Number of columns in the textarea.</param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// <param name="htmlAttributes">
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;textarea&gt; element.</returns>
+        /// <remarks>
+        /// <para>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
+        /// &lt;textarea&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </para>
+        /// <para>Determines &lt;textarea&gt; element's content based on the following precedence:</para>
+        /// <list type="number">
+        /// <item>
+        /// <see cref="ModelStateDictionary"/> entry for <paramref name="name"/> (converted to a fully-qualified name)
+        /// if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item><paramref name="value"/> if non-<c>null</c>.</item>
+        /// <item>
+        /// <see cref="ViewData"/> entry for <paramref name="name"/> (converted to a fully-qualified name)
+        /// if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item>
+        /// Linq expression based on <paramref name="name"/> (converted to a fully-qualified name) run against current
+        /// model if result is non-<c>null</c> and can be converted to a <see cref="string"/>. For example
+        /// <c>string.Empty</c> identifies the current model and <c>"prop"</c> identifies the current model's "prop"
+        /// property.
+        /// </item>
+        /// <item>Otherwise, <c>string.Empty</c>.</item>
+        /// </list>
+        /// </remarks>
         HtmlString TextArea(string name, string value, int rows, int columns, object htmlAttributes);
 
         /// <summary>
-        /// Render an input element of type "text".
+        /// Returns an &lt;input&gt; element of type "text" for the specified expression <paramref name="name"/>.
         /// </summary>
-        /// <param name="name">
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// Rendered element's name. Also use this name to find value in submitted data or view data. Use view data
+        /// <param name="value">If non-<c>null</c>, value to include in the element.</param>
-        /// only if value is not in submitted data and <paramref name="value"/> is <c>null</c>.
+        /// <param name="format">
+        /// The composite format <see cref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
         /// </param>
-        /// <param name="value">
+        /// <param name="htmlAttributes">
-        /// If non-<c>null</c>, value to include in the element. Ignore if named value is found in submitted data.
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="format"></param>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element.</returns>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// <remarks>
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// <para>
-        /// </param>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and <paramref name="name"/> to set
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// &lt;input&gt; element's "name" attribute. Sanitizes <paramref name="name"/> to set element's "id"
+        /// attribute.
+        /// </para>
+        /// <para>Determines &lt;input&gt; element's "value" attribute based on the following precedence:</para>
+        /// <list type="number">
+        /// <item>
+        /// <see cref="ModelStateDictionary"/> entry for <paramref name="name"/> (converted to a fully-qualified name)
+        /// if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item>
+        /// <paramref name="value"/> if non-<c>null</c>. Formats <paramref name="value"/> using
+        /// <paramref name="format"/> or converts <paramref name="value"/> to a <see cref="string"/> directly if
+        /// <paramref name="format"/> is <c>null</c> or empty.
+        /// </item>
+        /// <item>
+        /// <see cref="ViewData"/> entry for <paramref name="name"/> (converted to a fully-qualified name) if entry
+        /// exists and can be converted to a <see cref="string"/>. Formats entry using <paramref name="format"/> or
+        /// converts entry to a <see cref="string"/> directly if <paramref name="format"/> is <c>null</c> or empty.
+        /// </item>
+        /// <item>
+        /// Linq expression based on <paramref name="name"/> (converted to a fully-qualified name) run against current
+        /// model if result is non-<c>null</c> and can be converted to a <see cref="string"/>. For example
+        /// <c>string.Empty</c> identifies the current model and <c>"prop"</c> identifies the current model's "prop"
+        /// property. Formats result using <paramref name="format"/> or converts result to a <see cref="string"/>
+        /// directly if <paramref name="format"/> is <c>null</c> or empty.
+        /// </item>
+        /// <item>Existing "value" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>Otherwise, <c>string.Empty</c>.</item>
+        /// </list>
+        /// </remarks>
         HtmlString TextBox(string name, object value, string format, object htmlAttributes);
 
         /// <summary>
-        /// Returns the validation message if an error exists in the <see cref="ModelStateDictionary"/> object.
+        /// Returns the validation message if an error exists in the <see cref="ModelStateDictionary"/> object
+        /// for the specified expression <paramref name="modelName"/>.
         /// </summary>
-        /// <param name="modelName">The name of the property that is being validated.</param>
+        /// <param name="modelName">Expression name, relative to the current model.</param>
-        /// <param name="message">The message to be displayed. This will always be visible but client-side
+        /// <param name="message">
-        /// validation may update the associated CSS class.</param>
+        /// The message to be displayed. If <c>null</c> or empty, method extracts an error string from the
-        /// <param name="htmlAttributes"> An object that contains the HTML attributes to set for the element.
+        /// <see cref="ModelStateDictionary"/> object. Message will always be visible but client-side validation may
+        /// update the associated CSS class.
+        /// </param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the <paramref name="tag"/> element.
         /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="tag">The tag to wrap the <paramref name="message"/> in the generated HTML.
+        /// <param name="tag">
-        /// Its default value is <see cref="ViewContext.ValidationMessageElement" />.</param>
+        /// The tag to wrap the <paramref name="message"/> in the generated HTML. Its default value is
-        /// <returns>An <see cref="HtmlString"/> that contains the validation message</returns>
+        /// <see cref="ViewContext.ValidationMessageElement"/>.
+        /// </param>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing a <paramref name="tag"/> element. <c>null</c> if the
+        /// expression <paramref name="modelName"/> is valid and client-side validation is disabled.
+        /// </returns>
         HtmlString ValidationMessage(string modelName, string message, object htmlAttributes, string tag);
 
         /// <summary>
-        /// Returns an unordered list (ul element) of validation messages that are in the
+        /// Returns an unordered list (&lt;ul&gt; element) of validation messages that are in the
         /// <see cref="ModelStateDictionary"/> object.
         /// </summary>
-        /// <param name="excludePropertyErrors">true to have the summary display model-level errors only, or false to
+        /// <param name="excludePropertyErrors">
-        /// have the summary display all errors.</param>
+        /// If <c>true</c>, display model-level errors only; otherwise display all errors.
+        /// </param>
         /// <param name="message">The message to display with the validation summary.</param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the topmost (&lt;div&gt;) element.
         /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="tag">The tag to wrap the <paramref name="message"/> in the generated HTML.
+        /// <param name="tag">
-        /// Its default value is <see cref="ViewContext.ValidationMessageElement" />.</param>
+        /// The tag to wrap the <paramref name="message"/> in the generated HTML. Its default value is
-        /// <returns>An <see cref="HtmlString"/> that contains an unordered list (ul element) of validation messages.
+        /// <see cref="ViewContext.ValidationSummaryMessageElement" />.
+        /// </param>
+        /// <returns>
+        /// New <see cref="HtmlString"/> containing a &lt;div&gt; element wrapping the <paramref name="tag"/> element
+        /// and the &lt;ul&gt; element. <see cref="HtmlString.Empty"/> if the current model is valid and client-side
+        /// validation is disabled).
         /// </returns>
         HtmlString ValidationSummary(
             bool excludePropertyErrors,

src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelperOfT.cs

@@ -19,35 +19,63 @@ namespace Microsoft.AspNet.Mvc.Rendering
         new ViewDataDictionary<TModel> ViewData { get; }
 
         /// <summary>
-        /// Render an input element of type "checkbox" with value "true" and an input element of type "hidden" with
+        /// Returns an &lt;input&gt; element of type "checkbox" with value "true" and an &lt;input&gt; element of type
-        /// value "false".
+        /// "hidden" with value "false".
         /// </summary>
-        /// <param name="expression">
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// An expression that identifies the object that contains the properties to render.
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the checkbox element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; elements.</returns>
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// <remarks>
-        /// </param>
+        /// <para>
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set checkbox element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set checkbox element's "id" attribute.
+        /// </para>
+        /// <para>Determines checkbox element's "checked" attribute based on the following precedence:</para>
+        /// <list type="number">
+        /// <item>
+        /// <see cref="ModelBinding.ModelStateDictionary"/> entry for the string representation of the
+        /// <paramref name="expression"/> if entry exists and can be converted to a <see cref="bool"/>.
+        /// </item>
+        /// <item>
+        /// <paramref name="expression"/> result if it is non-<c>null</c> and can be parsed as a
+        /// <see cref="bool"/>.
+        /// </item>
+        /// <item>Existing "checked" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>Otherwise, does not include a "checked" attribute.</item>
+        /// </list>
+        /// <para>
+        /// In all but the <paramref name="htmlAttributes"/> case, includes a "checked" attribute with value "checked"
+        /// if the <see cref="bool"/> values is <c>true</c>; does not include the attribute otherwise.
+        /// </para>
+        /// </remarks>
         HtmlString CheckBoxFor([NotNull] Expression<Func<TModel, bool>> expression, object htmlAttributes);
 
         /// <summary>
-        /// Returns HTML markup for each property in the object that is represented by the specified expression, using
+        /// Returns HTML markup for the <paramref name="expression"/>, using a display template, specified HTML field
-        /// the template, an HTML field ID, and additional view data.
+        /// name, and additional view data. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
         /// </summary>
-        /// <typeparam name="TValue">The type of the value.</typeparam>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// <param name="expression">An expression that identifies the object that contains the properties to display.
+        /// <param name="templateName">The name of the template used to create the HTML markup.</param>
-        /// </param>
-        /// <param name="templateName">The name of the template that is used to render the object.</param>
         /// <param name="htmlFieldName">
-        /// A string that is used to disambiguate the names of HTML input elements that are rendered for properties
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for properties
         /// that have the same name.
         /// </param>
         /// <param name="additionalViewData">
-        /// An anonymous object or dictionary that can contain additional view data that will be merged into the
+        /// An anonymous <see cref="object"/> or <see cref="IDictionary{string, object}"/> that can contain additional
-        /// <see cref="ViewDataDictionary{TModel}"/> instance that is created for the template.
+        /// view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/> instance created for the
+        /// template.
         /// </param>
-        /// <returns>The HTML markup for each property in the object that is represented by the expression.</returns>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the created HTML.</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> display template includes markup for each property in the
+        /// <see cref="expression"/> result.
+        /// </remarks>
         HtmlString DisplayFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression,
                                       string templateName,
                                       string htmlFieldName,
@@ -56,7 +84,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// <summary>
         /// Returns the display name for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">The expression to be evaluated against the current model.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
         /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
         /// <returns>A <see cref="string"/> containing the display name.</returns>
         string DisplayNameFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression);
@@ -65,7 +93,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// Returns the display name for the specified <paramref name="expression"/>
         /// if the current model represents a collection.
         /// </summary>
-        /// <param name="expression">The expression to be evaluated against an item in the current model.</param>
+        /// <param name="expression">An expression to be evaluated against an item in the current model.</param>
         /// <typeparam name="TModelItem">The type of items in the model collection.</typeparam>
         /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
         /// <returns>A <see cref="string"/> containing the display name.</returns>
@@ -75,7 +103,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// <summary>
         /// Returns the simple display text for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">The expression to be evaluated against the current model.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
         /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
         /// <returns>
         /// A <see cref="string"/> containing the simple display text.
@@ -85,21 +113,28 @@ namespace Microsoft.AspNet.Mvc.Rendering
         string DisplayTextFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression);
 
         /// <summary>
-        /// Returns a single-selection HTML &lt;select&gt; element for the object that is represented
+        /// Returns a single-selection HTML &lt;select&gt; element for the <paramref name="expression"/>, using the
-        /// by the specified expression using the specified list items, option label, and HTML attributes.
+        /// specified list items, option label, and HTML attributes.
         /// </summary>
-        /// <typeparam name="TProperty">The type of the value.</typeparam>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// <param name="expression">An expression that identifies the value to display.</param>
+        /// <param name="selectList">
-        /// <param name="selectList">A collection of <see cref="SelectListItem"/> objects that are used to populate the
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
-        /// drop-down list.</param>
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
-        /// <param name="optionLabel">The text for a default empty item. This parameter can be null.</param>
+        /// </param>
+        /// <param name="optionLabel">
+        /// The text for a default empty item. Does not include such an item if argument is <c>null</c>.
+        /// </param>
         /// <param name="htmlAttributes">
-        /// An object that contains the HTML attributes to set for the &lt;select&gt; element. Alternatively, an
+        /// An <see cref="object"/> that contains the HTML attributes for the &lt;select&gt; element. Alternatively, an
         /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <returns>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
-        /// An HTML &lt;select&gt; element with an &lt;option&gt; subelement for each item in the list.
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
-        /// </returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set &lt;select&gt; element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute.
+        /// </remarks>
         HtmlString DropDownListFor<TProperty>(
             [NotNull] Expression<Func<TModel, TProperty>> expression,
             IEnumerable<SelectListItem> selectList,
@@ -107,78 +142,108 @@ namespace Microsoft.AspNet.Mvc.Rendering
             object htmlAttributes);
 
         /// <summary>
-        /// Returns an HTML input element for each property in the object that is represented by the specified
+        /// Returns HTML markup for the <paramref name="expression"/>, using an editor template, specified HTML field
-        /// expression, using the specified template, an HTML field ID, and additional view data.
+        /// name, and additional view data. The template is found using the <paramref name="templateName"/> or the
+        /// <paramref name="expression"/>'s <see cref="ModelBinding.ModelMetadata"/>.
         /// </summary>
-        /// <typeparam name="TValue">The type of the value.</typeparam>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// <param name="expression">An expression that identifies the object that contains the properties to edit.
+        /// <param name="templateName">The name of the template that is used to create the HTML markup.</param>
-        /// </param>
-        /// <param name="templateName">The name of the template that is used to render the object.</param>
         /// <param name="htmlFieldName">
-        /// A string that is used to disambiguate the names of HTML input elements that are rendered for properties
+        /// A <see cref="string"/> used to disambiguate the names of HTML elements that are created for properties
         /// that have the same name.
         /// </param>
         /// <param name="additionalViewData">
-        /// An anonymous object or dictionary that can contain additional view data that will be merged into the
+        /// An anonymous <see cref="object"/> or <see cref="IDictionary{string, object}"/> that can contain additional
-        /// <see cref="ViewDataDictionary{TModel}"/> instance that is created for the template.
+        /// view data that will be merged into the <see cref="ViewDataDictionary{TModel}"/> instance created for the
+        /// template.
         /// </param>
-        /// <returns>The HTML markup for the input elements for each property in the object that is represented by the
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
-        /// expression.</returns>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element(s).</returns>
+        /// <remarks>
+        /// For example the default <see cref="object"/> editor template includes &lt;label&gt; and &lt;input&gt;
+        /// elements for each property in the <see cref="expression"/> result.
+        /// </remarks>
         HtmlString EditorFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression,
             string templateName,
             string htmlFieldName,
             object additionalViewData);
 
         /// <summary>
-        /// Render an input element of type "hidden".
+        /// Returns an &lt;input&gt; element of type "hidden" for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// An expression that identifies the object that contains the properties to render.
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element.</returns>
-        /// </param>
+        /// <remarks>
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// <para>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set &lt;input&gt; element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute.
+        /// </para>
+        /// <para>Determines &lt;input&gt; element's "value" attribute based on the following precedence:</para>
+        /// <list type="number">
+        /// <item>
+        /// <see cref="ModelBinding.ModelStateDictionary"/> entry for the string representation of the
+        /// <paramref name="expression"/> if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item>
+        /// <paramref name="expression"/> result if it is non-<c>null</c> and can be parsed as a
+        /// <see cref="string"/>.
+        /// </item>
+        /// <item>Existing "value" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>Otherwise, <c>string.Empty</c>.</item>
+        /// </list>
+        /// </remarks>
         HtmlString HiddenFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression,
             object htmlAttributes);
 
         /// <summary>
         /// Returns the HTML element Id for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">The expression to be evaluated against the current model.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
         /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
         /// <returns>A <see cref="string"/> containing the element Id.</returns>
         string IdFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression);
 
         /// <summary>
-        /// Returns an HTML label element and the property name of the property that is represented by the specified
+        /// Returns a &lt;label&gt; element for the specified <paramref name="expression"/>.
-        /// expression.
         /// </summary>
-        /// <param name="expression">An expression that identifies the property to display.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.</param>
+        /// <param name="labelText">The inner text of the element.</param>
-        /// <typeparam name="TValue">The type of the value.</typeparam>
+        /// <param name="htmlAttributes">
-        /// <returns>
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
-        /// An HTML label element and the property name of the property that is represented by the expression.
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
-        /// </returns>
+        /// </param>
+        /// <typeparam name="TValue">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;label&gt; element.</returns>
         HtmlString LabelFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression,
                                     string labelText,
                                     object htmlAttributes);
 
         /// <summary>
-        /// Returns a multi-selection HTML &lt;select&gt; element for the object that is represented by the specified
+        /// Returns a multi-selection &lt;select&gt; element for the <paramref name="expression"/>, using the
-        /// expression using the specified list items and HTML attributes.
+        /// specified list items and HTML attributes.
         /// </summary>
-        /// <typeparam name="TProperty">The type of the property.</typeparam>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// <param name="expression">An expression that identifies the object that contains the properties to
+        /// <param name="selectList">
-        /// display.</param>
+        /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;select&gt; element with
-        /// <param name="selectList">A collection of <see cref="SelectListItem"/> objects that are used to populate the
+        /// &lt;optgroup&gt; and &lt;option&gt; elements.
-        /// drop-down list.</param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <returns>
+        /// <param name="htmlAttributes">
-        /// An HTML &lt;select&gt; element with an &lt;option&gt; subelement for each item in the list.
+        /// An <see cref="object"/> that contains the HTML attributes for the &lt;select&gt; element. Alternatively, an
-        /// </returns>
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// </param>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;select&gt; element.</returns>
+        /// <remarks>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set &lt;select&gt; element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute.
+        /// </remarks>
         HtmlString ListBoxFor<TProperty>(
             [NotNull] Expression<Func<TModel, TProperty>> expression,
             IEnumerable<SelectListItem> selectList,
@@ -187,81 +252,174 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// <summary>
         /// Returns the full HTML element name for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">The expression to be evaluated against the current model.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
         /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
         /// <returns>A <see cref="string"/> containing the element name.</returns>
         string NameFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression);
 
         /// <summary>
-        /// Render an input element of type "password".
+        /// Returns an &lt;input&gt; element of type "password" for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// An expression that identifies the object that contains the properties to render.
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element.</returns>
-        /// </param>
+        /// <remarks>
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// <para>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set &lt;input&gt; element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute.
+        /// </para>
+        /// <para>Determines &lt;input&gt; element's "value" attribute based on the following precedence:</para>
+        /// <list type="number">
+        /// <item>
+        /// <paramref name="expression"/> result if it is non-<c>null</c> and can be parsed as a
+        /// <see cref="string"/>.
+        /// </item>
+        /// <item>Existing "value" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>Otherwise, <c>string.Empty</c>.</item>
+        /// </list>
+        /// </remarks>
         HtmlString PasswordFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression,
             object htmlAttributes);
 
         /// <summary>
-        /// Render an input element of type "radio".
+        /// Returns an &lt;input&gt; element of type "radio" for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// An expression that identifies the object that contains the properties to render.
+        /// <param name="value">Value to include in the element. Must not be <c>null</c>.</param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="value">
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
-        /// Value to compare with current expression value to determine whether radio button is checked.
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element.</returns>
-        /// </param>
+        /// <remarks>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// <para>
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
-        /// </param>
+        /// <paramref name="expression"/> to set &lt;select&gt; element's "name" attribute. Sanitizes the string
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute. Converts the
+        /// <paramref name="value"/> to a <see cref="string"/> to set element's "value" attribute.
+        /// </para>
+        /// <para>Determines &lt;input&gt; element's "checked" attribute based on the following precedence:</para>
+        /// <list type="number">
+        /// <item>
+        /// <see cref="ModelBinding.ModelStateDictionary"/> entry for the string representation of the
+        /// <paramref name="expression"/> if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item>
+        /// <paramref name="expression"/> result if it is non-<c>null</c> and can be parsed as a <see cref="string"/>.
+        /// </item>
+        /// <item>Existing "checked" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>Otherwise, does not include a "checked" attribute.</item>
+        /// </list>
+        /// <para>
+        /// In all but the <paramref name="htmlAttributes"/> and default cases, includes a "checked" attribute with
+        /// value "checked" if the <see cref="string"/> values is equal to a converted <see cref="string"/> for
+        /// <paramref name="value"/>; does not include the attribute otherwise.
+        /// </para>
+        /// </remarks>
         HtmlString RadioButtonFor<TProperty>(
             [NotNull] Expression<Func<TModel, TProperty>> expression,
             [NotNull] object value,
             object htmlAttributes);
 
         /// <summary>
-        /// Render a textarea.
+        /// Returns a &lt;textarea&gt; element for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">An expression, relative to the current model.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
         /// <param name="rows">Number of rows in the textarea.</param>
         /// <param name="columns">Number of columns in the textarea.</param>
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// <param name="htmlAttributes">
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;textarea&gt; element.</returns>
+        /// <remarks>
+        /// <para>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set &lt;textarea&gt; element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute.
+        /// </para>
+        /// <para>Determines &lt;textarea&gt; element's content based on the following precedence:</para>
+        /// <list type="number">
+        /// <item>
+        /// <see cref="ModelBinding.ModelStateDictionary"/> entry for the string representation of the
+        /// <paramref name="expression"/> if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item>
+        /// <paramref name="expression"/> result if it is non-<c>null</c> and can be parsed as a <see cref="string"/>.
+        /// </item>
+        /// <item>Otherwise, <c>string.Empty</c>.</item>
+        /// </list>
+        /// </remarks>
         HtmlString TextAreaFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression,
             int rows, int columns, object htmlAttributes);
 
         /// <summary>
-        /// Render an input element of type "text".
+        /// Returns an &lt;input&gt; element of type "text" for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// An expression that identifies the object that contains the properties to render.
+        /// <param name="format">
+        /// The composite format <see cref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
         /// </param>
-        /// <param name="format"></param>
+        /// <param name="htmlAttributes">
-        /// <param name="htmlAttributes">An object that contains the HTML attributes to set for the element.
+        /// An <see cref="object"/> that contains the HTML attributes for the element. Alternatively, an
-        /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
+        /// <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <returns>New <see cref="HtmlString"/> containing the rendered HTML.</returns>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>A new <see cref="HtmlString"/> containing the &lt;input&gt; element.</returns>
+        /// <remarks>
+        /// <para>
+        /// Combines <see cref="TemplateInfo.HtmlFieldPrefix"/> and the string representation of the
+        /// <paramref name="expression"/> to set &lt;input&gt; element's "name" attribute. Sanitizes the string
+        /// representation of the <paramref name="expression"/> to set element's "id" attribute.
+        /// </para>
+        /// <para>Determines &lt;input&gt; element's "value" attribute based on the following precedence:</para>
+        /// <list type="number">
+        /// <item>
+        /// <see cref="ModelBinding.ModelStateDictionary"/> entry for the string representation of the
+        /// <paramref name="expression"/> if entry exists and can be converted to a <see cref="string"/>.
+        /// </item>
+        /// <item>
+        /// <paramref name="expression"/> result if it is non-<c>null</c> and can be parsed as a <see cref="string"/>.
+        /// Formats result using <paramref name="format"/> or converts result to a <see cref="string"/> directly if
+        /// <paramref name="format"/> is <c>null</c> or empty.
+        /// </item>
+        /// <item>Existing "value" entry in <paramref name="htmlAttributes"/> if any.</item>
+        /// <item>Otherwise, <c>string.Empty</c>.</item>
+        /// </list>
+        /// </remarks>
         HtmlString TextBoxFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression, string format,
             object htmlAttributes);
 
         /// <summary>
-        /// Returns the validation message for the specified expression
+        /// Returns the validation message if an error exists in the <see cref="ModelBinding.ModelStateDictionary"/>
+        /// object for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">An expression, relative to the current model.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
-        /// <param name="message">The message to be displayed. This will always be visible but client-side
+        /// <param name="message">
-        /// validation may update the associated CSS class.</param>
+        /// The message to be displayed. If <c>null</c> or empty, method extracts an error string from the
-        /// <param name="htmlAttributes"> An object that contains the HTML attributes to set for the element.
+        /// <see cref="ModelBinding.ModelStateDictionary"/> object. Message will always be visible but client-side
+        /// validation may update the associated CSS class.
+        /// </param>
+        /// <param name="htmlAttributes">
+        /// An <see cref="object"/> that contains the HTML attributes for the <paramref name="tag"/> element.
         /// Alternatively, an <see cref="IDictionary{string, object}"/> instance containing the HTML attributes.
         /// </param>
-        /// <param name="tag">The tag to wrap the <paramref name="message"/> in the generated HTML.
+        /// <param name="tag">
-        /// Its default value is <see cref="ViewContext.ValidationMessageElement" />.</param>
+        /// The tag to wrap the <paramref name="message"/> in the generated HTML. Its default value is
-        /// <returns>An <see cref="HtmlString"/> that contains the validation message</returns>
+        /// <see cref="ViewContext.ValidationMessageElement"/>.
+        /// </param>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
+        /// <returns>
+        /// A new <see cref="HtmlString"/> containing the <paramref name="tag"/> element. <c>null</c> if the
+        /// <paramref name="expression"/> is valid and client-side validation is disabled.
+        /// </returns>
         HtmlString ValidationMessageFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression,
             string message,
             object htmlAttributes,
@@ -270,7 +428,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// <summary>
         /// Returns the formatted value for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">The expression to be evaluated against the current model.</param>
+        /// <param name="expression">An expression to be evaluated against the current model.</param>
         /// <param name="format">
         /// The composite format <see cref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
         /// </param>