Add high-pri doc comments for views, controllers, HTML helpers, Startup

src/Microsoft.AspNet.Mvc.Abstractions/IActionResult.cs

@@ -5,8 +5,18 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNet.Mvc
 {
+    /// <summary>
+    /// Defines a contract that represents the result of an action method.
+    /// </summary>
     public interface IActionResult
     {
+        /// <summary>
+        /// Executes the result operation of the action method asynchronously. This method is called by MVC to process
+        /// the result of an action method.
+        /// </summary>
+        /// <param name="context">The context in which the result is executed. The context information includes
+        /// information about the action that was executed and request information.</param>
+        /// <returns>A task that represents the asynchronous execute operation.</returns>
         Task ExecuteResultAsync(ActionContext context);
     }
 }

src/Microsoft.AspNet.Mvc.Core/ActionResult.cs

@@ -5,14 +5,32 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNet.Mvc
 {
+    /// <summary>
+    /// A default implementation of <see cref="IActionResult"/>.
+    /// </summary>
     public abstract class ActionResult : IActionResult
     {
+        /// <summary>
+        /// Executes the result operation of the action method asynchronously. This method is called by MVC to process
+        /// the result of an action method.
+        /// The default implementation of this method calls the <see cref="ExecuteResult(ActionContext)"/> method and
+        /// returns a completed task.
+        /// </summary>
+        /// <param name="context">The context in which the result is executed. The context information includes
+        /// information about the action that was executed and request information.</param>
+        /// <returns>A task that represents the asynchronous execute operation.</returns>
         public virtual Task ExecuteResultAsync(ActionContext context)
         {
             ExecuteResult(context);
             return Task.FromResult(true);
         }
 
+        /// <summary>
+        /// Executes the result operation of the action method synchronously. This method is called by MVC to process
+        /// the result of an action method.
+        /// </summary>
+        /// <param name="context">The context in which the result is executed. The context information includes
+        /// information about the action that was executed and request information.</param>
         public virtual void ExecuteResult(ActionContext context)
         {
         }

src/Microsoft.AspNet.Mvc.Core/Builder/MvcApplicationBuilderExtensions.cs

@@ -18,7 +18,7 @@ namespace Microsoft.AspNet.Builder
         /// Adds MVC to the <see cref="IApplicationBuilder"/> request execution pipeline.
         /// </summary>
         /// <param name="app">The <see cref="IApplicationBuilder"/>.</param>
-        /// <returns>The <paramref name="app"/>.</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         /// <remarks>This method only supports attribute routing. To add conventional routes use
         /// <see cref="UseMvc(IApplicationBuilder, Action{IRouteBuilder})"/>.</remarks>
         public static IApplicationBuilder UseMvc(this IApplicationBuilder app)
@@ -39,7 +39,7 @@ namespace Microsoft.AspNet.Builder
         /// '{controller=Home}/{action=Index}/{id?}'.
         /// </summary>
         /// <param name="app">The <see cref="IApplicationBuilder"/>.</param>
-        /// <returns>The <paramref name="app"/>.</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseMvcWithDefaultRoute(this IApplicationBuilder app)
         {
             if (app == null)
@@ -60,7 +60,7 @@ namespace Microsoft.AspNet.Builder
         /// </summary>
         /// <param name="app">The <see cref="IApplicationBuilder"/>.</param>
         /// <param name="configureRoutes">A callback to configure MVC routes.</param>
-        /// <returns>The <paramref name="app"/>.</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseMvc(
             this IApplicationBuilder app,
             Action<IRouteBuilder> configureRoutes)

src/Microsoft.AspNet.Mvc.Razor/RazorPage.cs

@@ -46,6 +46,9 @@ namespace Microsoft.AspNet.Mvc.Razor
             _writerScopes = new Stack<TextWriter>();
         }
 
+        /// <summary>
+        /// An <see cref="HttpContext"/> representing the current request execution.
+        /// </summary>
         public HttpContext Context
         {
             get
@@ -81,7 +84,7 @@ namespace Microsoft.AspNet.Mvc.Razor
         public IPageExecutionContext PageExecutionContext { get; set; }
 
         /// <summary>
-        /// Gets the TextWriter that the page is writing output to.
+        /// Gets the <see cref="TextWriter"/> that the page is writing output to.
         /// </summary>
         public virtual TextWriter Output
         {
@@ -97,6 +100,9 @@ namespace Microsoft.AspNet.Mvc.Razor
             }
         }
 
+        /// <summary>
+        /// Gets the <see cref="ClaimsPrincipal"/> of the current logged in user.
+        /// </summary>
         public virtual ClaimsPrincipal User
         {
             get
@@ -110,6 +116,9 @@ namespace Microsoft.AspNet.Mvc.Razor
             }
         }
 
+        /// <summary>
+        /// Gets the dynamic view data dictionary.
+        /// </summary>
         public dynamic ViewBag
         {
             get
@@ -821,6 +830,10 @@ namespace Microsoft.AspNet.Mvc.Razor
             EndContext();
         }
 
+        /// <summary>
+        /// In a Razor layout page, renders the portion of a content page that is not within a named section.
+        /// </summary>
+        /// <returns>The HTML content to render.</returns>
         protected virtual HelperResult RenderBody()
         {
             if (RenderBodyDelegateAsync == null)
@@ -858,6 +871,11 @@ namespace Microsoft.AspNet.Mvc.Razor
             SectionWriters[name] = section;
         }
 
+        /// <summary>
+        /// Returns a value that indicates whether the specified section is defined in the content page.
+        /// </summary>
+        /// <param name="name">The section name to search for.</param>
+        /// <returns><c>true</c> if the specified section is defined in the content page; otherwise, <c>false</c>.</returns>
         public bool IsSectionDefined(string name)
         {
             if (name == null)

src/Microsoft.AspNet.Mvc.Razor/RazorPageOfT.cs

@@ -19,6 +19,9 @@ namespace Microsoft.AspNet.Mvc.Razor
     {
         private IModelMetadataProvider _provider;
 
+        /// <summary>
+        /// Gets the Model property of the <see cref="ViewData"/> property.
+        /// </summary>
         public TModel Model
         {
             get
@@ -27,6 +30,9 @@ namespace Microsoft.AspNet.Mvc.Razor
             }
         }
 
+        /// <summary>
+        /// Gets or sets the dictionary for view data.
+        /// </summary>
         [RazorInject]
         public ViewDataDictionary<TModel> ViewData { get; set; }
 

src/Microsoft.AspNet.Mvc.ViewFeatures/Rendering/MultiSelectList.cs

@@ -10,6 +10,11 @@ using Microsoft.AspNet.Mvc.ViewFeatures;
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Represents a list that lets users select multiple items.
+    /// This class is typically rendered as an HTML <code>&lt;select multiple="multiple"&gt;</code> element with the specified collection
+    /// of <see cref="SelectListItem"/> objects.
+    /// </summary>
     public class MultiSelectList : IEnumerable<SelectListItem>
     {
         private IList<SelectListGroup> _groups;

src/Microsoft.AspNet.Mvc.ViewFeatures/Rendering/SelectList.cs

@@ -6,6 +6,11 @@ using System.Collections;
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Represents a list that lets users select a single item.
+    /// This class is typically rendered as an HTML <code>&lt;select&gt;</code> element with the specified collection
+    /// of <see cref="SelectListItem"/> objects.
+    /// </summary>
     public class SelectList : MultiSelectList
     {
         public SelectList(IEnumerable items)

src/Microsoft.AspNet.Mvc.ViewFeatures/Rendering/SelectListItem.cs

@@ -3,10 +3,17 @@
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Represents an item in a <see cref="SelectList"/> or <see cref="MultiSelectList"/>.
+    /// This class is typically rendered as an HTML <code>&lt;option&gt;</code> element with the specified
+    /// attribute values.
+    /// </summary>
     public class SelectListItem
     {
         /// <summary>
         /// Gets or sets a value that indicates whether this <see cref="SelectListItem"/> is disabled.
+        /// This property is typically rendered as a <code>disabled="disabled"</code> attribute in the HTML
+        /// <code>&lt;option&gt;</code> element.
         /// </summary>
         public bool Disabled { get; set; }
 
@@ -17,10 +24,24 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// </summary>
         public SelectListGroup Group { get; set; }
 
+        /// <summary>
+        /// Gets or sets a value that indicates whether this <see cref="SelectListItem"/> is selected.
+        /// This property is typically rendered as a <code>selected="selected"</code> attribute in the HTML
+        /// <code>&lt;option&gt;</code> element.
+        /// </summary>
         public bool Selected { get; set; }
 
+        /// <summary>
+        /// Gets or sets a value that indicates the display text of this <see cref="SelectListItem"/>.
+        /// This property is typically rendered as the inner HTML in the HTML <code>&lt;option&gt;</code> element.
+        /// </summary>
         public string Text { get; set; }
 
+        /// <summary>
+        /// Gets or sets a value that indicates the value of this <see cref="SelectListItem"/>.
+        /// This property is typically rendered as a <code>value="..."</code> attribute in the HTML
+        /// <code>&lt;option&gt;</code> element.
+        /// </summary>
         public string Value { get; set; }
     }
 }

src/Microsoft.AspNet.Mvc.ViewFeatures/Rendering/TagBuilder.cs

@@ -14,11 +14,19 @@ using Microsoft.Extensions.WebEncoders;
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Contains methods and properties that are used to create HTML elements. This class is often used to write HTML
+    /// helpers and tag helpers.
+    /// </summary>
     [DebuggerDisplay("{DebuggerToString()}")]
     public class TagBuilder : IHtmlContent
     {
         private AttributeDictionary _attributes;
 
+        /// <summary>
+        /// Creates a new HTML tag that has the specified tag name.
+        /// </summary>
+        /// <param name="tagName">An HTML tag name.</param>
         public TagBuilder(string tagName)
         {
             if (string.IsNullOrEmpty(tagName))
@@ -47,8 +55,14 @@ namespace Microsoft.AspNet.Mvc.Rendering
             }
         }
 
+        /// <summary>
+        /// Gets the inner HTML content of the element.
+        /// </summary>
         public IHtmlContentBuilder InnerHtml { get; }
 
+        /// <summary>
+        /// Gets the tag name for this tag.
+        /// </summary>
         public string TagName { get; }
 
         /// <summary>
@@ -57,6 +71,12 @@ namespace Microsoft.AspNet.Mvc.Rendering
         /// <remarks>Defaults to <see cref="TagRenderMode.Normal"/>.</remarks>
         public TagRenderMode TagRenderMode { get; set; } = TagRenderMode.Normal;
 
+        /// <summary>
+        /// Adds a CSS class to the list of CSS classes in the tag.
+        /// If there are already CSS classes on the tag then a space character and the new class will be appended to
+        /// the existing list.
+        /// </summary>
+        /// <param name="value">The CSS class name to add.</param>
         public void AddCssClass(string value)
         {
             string currentValue;
@@ -144,16 +164,24 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return stringBuffer.ToString();
         }
 
-        public void GenerateId(string name, string idAttributeDotReplacement)
+        /// <summary>
+        /// Generates a sanitized ID attribute for the tag by using the specified name.
+        /// </summary>
+        /// <param name="name">The name to use to generate an ID attribute.</param>
+        /// <param name="invalidCharReplacement">
+        /// The <see cref="string"/> (normally a single <see cref="char"/>) to substitute for invalid characters in
+        /// <paramref name="name"/>.
+        /// </param>
+        public void GenerateId(string name, string invalidCharReplacement)
         {
-            if (idAttributeDotReplacement == null)
+            if (invalidCharReplacement == null)
             {
-                throw new ArgumentNullException(nameof(idAttributeDotReplacement));
+                throw new ArgumentNullException(nameof(invalidCharReplacement));
             }
 
             if (!Attributes.ContainsKey("id"))
             {
-                var sanitizedId = CreateSanitizedId(name, idAttributeDotReplacement);
+                var sanitizedId = CreateSanitizedId(name, invalidCharReplacement);
                 if (!string.IsNullOrEmpty(sanitizedId))
                 {
                     Attributes["id"] = sanitizedId;

src/Microsoft.AspNet.Mvc.ViewFeatures/ValidateAntiForgeryTokenAttribute.cs

@@ -9,6 +9,14 @@ using Microsoft.Extensions.DependencyInjection;
 
 namespace Microsoft.AspNet.Mvc
 {
+    /// <summary>
+    /// Specifies that the class or method that this attribute is applied validates the anti-forgery token.
+    /// If the anti-forgery token is not available, or if the token is invalid, the validation will fail
+    /// and the action method will not execute.
+    /// </summary>
+    /// <remarks>
+    /// This attribute helps defend against cross-site request forgery. It won't prevent other forgery or tampering attacks.
+    /// </remarks>
     [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = false, Inherited = true)]
     public class ValidateAntiForgeryTokenAttribute : Attribute, IFilterFactory, IOrderedFilter
     {

src/Microsoft.AspNet.Mvc/MvcServiceCollectionExtensions.cs

@@ -7,8 +7,16 @@ using Microsoft.AspNet.Mvc.Internal;
 
 namespace Microsoft.Extensions.DependencyInjection
 {
+    /// <summary>
+    /// Extension methods for setting up MVC services in an <see cref="IServiceCollection" />.
+    /// </summary>
     public static class MvcServiceCollectionExtensions
     {
+        /// <summary>
+        /// Adds MVC services to the specified <see cref="IServiceCollection" />.
+        /// </summary>
+        /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IMvcBuilder AddMvc(this IServiceCollection services)
         {
             if (services == null)
@@ -19,6 +27,12 @@ namespace Microsoft.Extensions.DependencyInjection
             return AddMvc(services, setupAction: null);
         }
 
+        /// <summary>
+        /// Adds MVC services to the specified <see cref="IServiceCollection" />.
+        /// </summary>
+        /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+        /// <param name="setupAction">An action delegate to configure the provided <see cref="MvcOptions"/>.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IMvcBuilder AddMvc(this IServiceCollection services, Action<MvcOptions> setupAction)
         {
             if (services == null)

test/Microsoft.AspNet.Mvc.ViewFeatures.Test/Rendering/TagBuilderTest.cs

@@ -65,7 +65,7 @@ namespace Microsoft.AspNet.Mvc.Core.Rendering
             tagBuilder.Attributes.Add("ID", "something");
 
             // Act
-            tagBuilder.GenerateId("else", idAttributeDotReplacement: "-");
+            tagBuilder.GenerateId("else", invalidCharReplacement: "-");
 
             // Assert
             var attribute = Assert.Single(tagBuilder.Attributes);