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 `<remarks>` describing behaviour of input helpers e.g. `CheckBox()`
- 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

nits:
- "The expression" -> "An expression"
- make examples for `ObjectToDictionary()` and `AnonymousObjectToHtmlAttributes()` more consistent
- move `<typeparam/>` elements (that existed) after all `<param/>` elements

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

@@ -126,7 +126,7 @@ public HtmlString ActionLink(
         /// 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 @@ public static IDictionary<string, object> ObjectToDictionary(object obj)
         /// 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>

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

@@ -29,7 +29,7 @@ public static string DisplayNameForModel([NotNull] this IHtmlHelper htmlHelper)
         /// <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/HtmlHelperFormExtensions.cs

@@ -3,21 +3,56 @@
 
 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>
         public static MvcForm BeginForm([NotNull] this IHtmlHelper htmlHelper)
         {
             // Generates <form action="{current url}" method="post">.
             return htmlHelper.BeginForm(actionName: null, controllerName: null, routeValues: null,
                                         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>
         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>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             FormMethod method,
@@ -27,12 +62,37 @@ public static MvcForm BeginForm(
                                         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>
         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>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             string actionName,
@@ -42,6 +102,23 @@ public static MvcForm BeginForm(
                                         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>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             string actionName,
@@ -52,6 +129,17 @@ public static MvcForm BeginForm(
                                         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>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             string actionName,
@@ -62,6 +150,24 @@ public static MvcForm BeginForm(
                                         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>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             string actionName,
@@ -73,6 +179,22 @@ public static MvcForm BeginForm(
                                         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>
         public static MvcForm BeginForm(
             [NotNull] this IHtmlHelper htmlHelper,
             string actionName,