From 257d202a14e5ae1a0f66f7b4636acb86ab0f47bc Mon Sep 17 00:00:00 2001
From: Ryan Nowak <nowakra@gmail.com>
Date: Wed, 30 Aug 2017 12:52:10 -0700
Subject: [PATCH] Make AddMvcCore docs scarier

Fixes #6632
---
 .../MvcCoreServiceCollectionExtensions.cs     | 26 +++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/src/Microsoft.AspNetCore.Mvc.Core/DependencyInjection/MvcCoreServiceCollectionExtensions.cs b/src/Microsoft.AspNetCore.Mvc.Core/DependencyInjection/MvcCoreServiceCollectionExtensions.cs
index 23103c6ee1..d168060524 100644
--- a/src/Microsoft.AspNetCore.Mvc.Core/DependencyInjection/MvcCoreServiceCollectionExtensions.cs
+++ b/src/Microsoft.AspNetCore.Mvc.Core/DependencyInjection/MvcCoreServiceCollectionExtensions.cs
@@ -30,10 +30,21 @@ namespace Microsoft.Extensions.DependencyInjection
     public static class MvcCoreServiceCollectionExtensions
     {
         /// <summary>
-        /// Adds essential MVC services to the specified <see cref="IServiceCollection" />.
+        /// Adds the minimum essential MVC services to the specified <see cref="IServiceCollection" />. Addtional services
+        /// including MVC's support for authorization, formatters, and validation must be added separately using the 
+        /// <see cref="IMvcCoreBuilder"/> returned from this method.
         /// </summary>
         /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
         /// <returns>An <see cref="IMvcCoreBuilder"/> that can be used to further configure the MVC services.</returns>
+        /// <remarks>
+        /// The <see cref="MvcCoreServiceCollectionExtensions.AddMvcCore(IServiceCollection)"/> approach for configuring
+        /// MVC is provided for experienced MVC developers who wish to have full control over the set of default services 
+        /// registered. <see cref="MvcCoreServiceCollectionExtensions.AddMvcCore(IServiceCollection)"/> will register
+        /// the minimum set of services necessary to route requests and invoke controllers. It is not expected that any 
+        /// application will satisfy its requirements with just a call to
+        /// <see cref="MvcCoreServiceCollectionExtensions.AddMvcCore(IServiceCollection)"/>. Additional configuration using the 
+        /// <see cref="IMvcCoreBuilder"/> will be required.
+        /// </remarks>
         public static IMvcCoreBuilder AddMvcCore(this IServiceCollection services)
         {
             if (services == null)
@@ -92,11 +103,22 @@ namespace Microsoft.Extensions.DependencyInjection
         }
 
         /// <summary>
-        /// Adds essential MVC services to the specified <see cref="IServiceCollection" />.
+        /// Adds the minimum essential MVC services to the specified <see cref="IServiceCollection" />. Addtional services
+        /// including MVC's support for authorization, formatters, and validation must be added separately using the 
+        /// <see cref="IMvcCoreBuilder"/> returned from this method.
         /// </summary>
         /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
         /// <param name="setupAction">An <see cref="Action{MvcOptions}"/> to configure the provided <see cref="MvcOptions"/>.</param>
         /// <returns>An <see cref="IMvcCoreBuilder"/> that can be used to further configure the MVC services.</returns>
+        /// <remarks>
+        /// The <see cref="MvcCoreServiceCollectionExtensions.AddMvcCore(IServiceCollection)"/> approach for configuring
+        /// MVC is provided for experienced MVC developers who wish to have full control over the set of default services 
+        /// registered. <see cref="MvcCoreServiceCollectionExtensions.AddMvcCore(IServiceCollection)"/> will register
+        /// the minimum set of services necessary to route requests and invoke controllers. It is not expected that any 
+        /// application will satisfy its requirements with just a call to
+        /// <see cref="MvcCoreServiceCollectionExtensions.AddMvcCore(IServiceCollection)"/>. Additional configuration using the 
+        /// <see cref="IMvcCoreBuilder"/> will be required.
+        /// </remarks>
         public static IMvcCoreBuilder AddMvcCore(
             this IServiceCollection services,
             Action<MvcOptions> setupAction)