Improve `IUrlHelper` and related doc comments

- #4245, #4507

src/Microsoft.AspNetCore.Mvc.Abstractions/IUrlHelper.cs

@@ -16,11 +16,13 @@ namespace Microsoft.AspNetCore.Mvc
         ActionContext ActionContext { get; }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL specified by <see cref="UrlActionContext"/> for an action
+        /// Generates a URL with an absolute path for an action method, which contains the action
-        /// method, which contains action name, controller name, route values, protocol to use, host name, and fragment.
+        /// name, controller name, route values, protocol to use, host name, and fragment specified by
+        /// <see cref="UrlActionContext"/>. Generates an absolute URL if <see cref="UrlActionContext.Protocol"/> and
+        /// <see cref="UrlActionContext.Host"/> are non-<c>null</c>.
         /// </summary>
         /// <param name="actionContext">The context object for the generated URLs for an action method.</param>
-        /// <returns>The fully qualified or absolute URL to an action method.</returns>
+        /// <returns>The generated URL.</returns>
         string Action(UrlActionContext actionContext);
 
         /// <summary>
@@ -35,43 +37,47 @@ namespace Microsoft.AspNetCore.Mvc
         string Content(string contentPath);
 
         /// <summary>
-        /// Returns a value that indicates whether the URL is local. A URL with an absolute path is considered local
+        /// Returns a value that indicates whether the URL is local. A URL is considered local if it does not have a
-        /// if it does not have a host/authority part. URLs using virtual paths ('~/') are also local.
+        /// host / authority part and it has an absolute path. URLs using virtual paths ('~/') are also local.
         /// </summary>
         /// <param name="url">The URL.</param>
         /// <returns><c>true</c> if the URL is local; otherwise, <c>false</c>.</returns>
         /// <example>
         /// <para>
         /// For example, the following URLs are considered local:
+        /// <code>
         /// /Views/Default/Index.html
         /// ~/Index.html
+        /// </code>
         /// </para>
         /// <para>
         /// The following URLs are non-local:
+        /// <code>
         /// ../Index.html
         /// http://www.contoso.com/
         /// http://localhost/Index.html
+        /// </code>
         /// </para>
         /// </example>
         bool IsLocalUrl(string url);
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL specified by <see cref="UrlRouteContext"/>, which
+        /// Generates a URL with an absolute path, which contains the route name, route values, protocol to use, host
-        /// contains the route name, the route values, protocol to use, host name and fragment.
+        /// name, and fragment specified by <see cref="UrlRouteContext"/>. Generates an absolute URL if
+        /// <see cref="UrlActionContext.Protocol"/> and <see cref="UrlActionContext.Host"/> are non-<c>null</c>.
         /// </summary>
         /// <param name="routeContext">The context object for the generated URLs for a route.</param>
-        /// <returns>The fully qualified or absolute URL.</returns>
+        /// <returns>The generated URL.</returns>
         string RouteUrl(UrlRouteContext routeContext);
 
         /// <summary>
-        /// Generates an absolute URL using the specified route name and values.
+        /// Generates an absolute URL for the specified <paramref name="routeName"/> and route
+        /// <paramref name="values"/>, which contains the protocol (such as "http" or "https") and host name from the
+        /// current request.
         /// </summary>
-        /// <param name="routeName">The name of the route that is used to generate the URL.</param>
+        /// <param name="routeName">The name of the route that is used to generate URL.</param>
-        /// <param name="values">An object that contains the route values.</param>
+        /// <param name="values">An object that contains route values.</param>
         /// <returns>The generated absolute URL.</returns>
-        /// <remarks>
-        /// The protocol and host is obtained from the current request.
-        /// </remarks>
         string Link(string routeName, object values);
     }
 }

src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlActionContext.cs

@@ -27,7 +27,7 @@ namespace Microsoft.AspNetCore.Mvc.Routing
         }
 
         /// <summary>
-        /// The object that contains the route parameters that <see cref="IUrlHelper.Action(UrlActionContext)"/>
+        /// The object that contains the route values that <see cref="IUrlHelper.Action(UrlActionContext)"/>
         /// uses to generate URLs.
         /// </summary>
         public object Values
@@ -37,7 +37,7 @@ namespace Microsoft.AspNetCore.Mvc.Routing
         }
 
         /// <summary>
-        /// The protocol for the URLs that <see cref="IUrlHelper.Action(UrlActionContext)"/> generates
+        /// The protocol for the URLs that <see cref="IUrlHelper.Action(UrlActionContext)"/> generates,
         /// such as "http" or "https"
         /// </summary>
         public string Protocol

src/Microsoft.AspNetCore.Mvc.Abstractions/Routing/UrlRouteContext.cs

@@ -18,7 +18,8 @@ namespace Microsoft.AspNetCore.Mvc.Routing
         }
 
         /// <summary>
-        /// The object that contains the route values for the generated URLs.
+        /// The object that contains the route values that <see cref="IUrlHelper.RouteUrl(UrlRouteContext)"/>
+        /// uses to generate URLs.
         /// </summary>
         public object Values
         {
@@ -27,7 +28,7 @@ namespace Microsoft.AspNetCore.Mvc.Routing
         }
 
         /// <summary>
-        /// The protocol for the URLs that <see cref="IUrlHelper.RouteUrl(UrlRouteContext)"/> generates
+        /// The protocol for the URLs that <see cref="IUrlHelper.RouteUrl(UrlRouteContext)"/> generates,
         /// such as "http" or "https"
         /// </summary>
         public string Protocol

src/Microsoft.AspNetCore.Mvc.Core/Routing/UrlHelper.cs

@@ -23,8 +23,8 @@ namespace Microsoft.AspNetCore.Mvc.Routing
         private readonly RouteValueDictionary _routeValueDictionary;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="UrlHelper"/> class using the specified action context and
+        /// Initializes a new instance of the <see cref="UrlHelper"/> class using the specified
-        /// action selector.
+        /// <paramref name="actionContext"/>.
         /// </summary>
         /// <param name="actionContext">The <see cref="Mvc.ActionContext"/> for the current request.</param>
         public UrlHelper(ActionContext actionContext)
@@ -41,10 +41,20 @@ namespace Microsoft.AspNetCore.Mvc.Routing
         /// <inheritdoc />
         public ActionContext ActionContext { get; }
 
+        /// <summary>
+        /// Gets the <see cref="RouteValueDictionary"/> associated with the current request.
+        /// </summary>
         protected RouteValueDictionary AmbientValues => ActionContext.RouteData.Values;
 
+        /// <summary>
+        /// Gets the <see cref="Http.HttpContext"/> associated with the current request.
+        /// </summary>
         protected HttpContext HttpContext => ActionContext.HttpContext;
 
+        /// <summary>
+        /// Gets the top-level <see cref="IRouter"/> associated with the current request. Generally an
+        /// <see cref="IRouteCollection"/> implementation.
+        /// </summary>
         protected IRouter Router => ActionContext.RouteData.Routers[0];
 
         /// <inheritdoc />
@@ -116,11 +126,15 @@ namespace Microsoft.AspNetCore.Mvc.Routing
         }
 
         /// <summary>
-        /// Gets the <see cref="VirtualPathData"/> for the specified route values by using the specified route name.
+        /// Gets the <see cref="VirtualPathData"/> for the specified <paramref name="routeName"/> and route
+        /// <paramref name="values"/>.
         /// </summary>
         /// <param name="routeName">The name of the route that is used to generate the <see cref="VirtualPathData"/>.
         /// </param>
-        /// <param name="values">A dictionary that contains the parameters for a route.</param>
+        /// <param name="values">
+        /// The <see cref="RouteValueDictionary"/>. The <see cref="Router"/> uses these values, in combination with
+        /// <see cref="AmbientValues"/>, to generate the URL.
+        /// </param>
         /// <returns>The <see cref="VirtualPathData"/>.</returns>
         protected virtual VirtualPathData GetVirtualPathData(string routeName, RouteValueDictionary values)
         {
@@ -253,10 +267,10 @@ namespace Microsoft.AspNetCore.Mvc.Routing
         /// <summary>
         /// Generates the URL using the specified components.
         /// </summary>
-        /// <param name="protocol">The protocol.</param>
+        /// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
-        /// <param name="host">The host.</param>
+        /// <param name="host">The host name for the URL.</param>
         /// <param name="pathData">The <see cref="VirtualPathData"/>.</param>
-        /// <param name="fragment">The URL fragment.</param>
+        /// <param name="fragment">The fragment for the URL.</param>
         /// <returns>The generated URL.</returns>
         protected virtual string GenerateUrl(string protocol, string host, VirtualPathData pathData, string fragment)
         {

src/Microsoft.AspNetCore.Mvc.Core/UrlHelperExtensions.cs

@@ -9,9 +9,10 @@ namespace Microsoft.AspNetCore.Mvc
     public static class UrlHelperExtensions
     {
         /// <summary>
-        /// Generates a fully qualified or absolute URL for an action method.
+        /// Generates a URL with an absolute path for an action method.
         /// </summary>
-        /// <returns>The fully qualified or absolute URL to an action method.</returns>
+        /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
+        /// <returns>The generated URL.</returns>
         public static string Action(this IUrlHelper helper)
         {
             if (helper == null)
@@ -29,11 +30,12 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for an action method by using the specified action name.
+        /// Generates a URL with an absolute path for an action method, which contains the specified
+        /// <paramref name="action"/> name.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="action">The name of the action method.</param>
-        /// <returns>The fully qualified or absolute URL to an action method.</returns>
+        /// <returns>The generated URL.</returns>
         public static string Action(this IUrlHelper helper, string action)
         {
             if (helper == null)
@@ -45,13 +47,13 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for an action method by using the specified action name,
+        /// Generates a URL with an absolute path for an action method, which contains the specified
-        /// and route values.
+        /// <paramref name="action"/> name and route <paramref name="values"/>.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="action">The name of the action method.</param>
         /// <param name="values">An object that contains route values.</param>
-        /// <returns>The fully qualified or absolute URL to an action method.</returns>
+        /// <returns>The generated URL.</returns>
         public static string Action(this IUrlHelper helper, string action, object values)
         {
             if (helper == null)
@@ -63,13 +65,13 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for an action method by using the specified action name,
+        /// Generates a URL with an absolute path for an action method, which contains the specified
-        /// and controller name.
+        /// <paramref name="action"/> and <paramref name="controller"/> names.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="action">The name of the action method.</param>
         /// <param name="controller">The name of the controller.</param>
-        /// <returns>The fully qualified or absolute URL to an action method.</returns>
+        /// <returns>The generated URL.</returns>
         public static string Action(this IUrlHelper helper, string action, string controller)
         {
             if (helper == null)
@@ -81,14 +83,14 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for an action method by using the specified action name,
+        /// Generates a URL with an absolute path for an action method, which contains the specified
-        /// controller name, and route values.
+        /// <paramref name="action"/> name, <paramref name="controller"/> name, and route <paramref name="values"/>.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="action">The name of the action method.</param>
         /// <param name="controller">The name of the controller.</param>
         /// <param name="values">An object that contains route values.</param>
-        /// <returns>The fully qualified or absolute URL to an action method.</returns>
+        /// <returns>The generated URL.</returns>
         public static string Action(this IUrlHelper helper, string action, string controller, object values)
         {
             if (helper == null)
@@ -100,15 +102,16 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for an action method by using the specified action name,
+        /// Generates a URL with an absolute path for an action method, which contains the specified
-        /// controller name, route values, and protocol to use.
+        /// <paramref name="action"/> name, <paramref name="controller"/> name, route <paramref name="values"/>, and
+        /// <paramref name="protocol"/> to use.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="action">The name of the action method.</param>
         /// <param name="controller">The name of the controller.</param>
         /// <param name="values">An object that contains route values.</param>
         /// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
-        /// <returns>The fully qualified or absolute URL to an action method.</returns>
+        /// <returns>The generated URL.</returns>
         public static string Action(
             this IUrlHelper helper,
             string action,
@@ -125,8 +128,11 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for an action method by using the specified action name,
+        /// Generates a URL with an absolute path for an action method, which contains the specified
-        /// controller name, route values, protocol to use, and host name.
+        /// <paramref name="action"/> name, <paramref name="controller"/> name, route <paramref name="values"/>,
+        /// <paramref name="protocol"/> to use, and <paramref name="host"/> name.
+        /// Generates an absolute URL if the <paramref name="protocol"/> and <paramref name="host"/> are
+        /// non-<c>null</c>.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="action">The name of the action method.</param>
@@ -134,7 +140,7 @@ namespace Microsoft.AspNetCore.Mvc
         /// <param name="values">An object that contains route values.</param>
         /// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
         /// <param name="host">The host name for the URL.</param>
-        /// <returns>The fully qualified or absolute URL to an action method.</returns>
+        /// <returns>The generated URL.</returns>
         public static string Action(
             this IUrlHelper helper,
             string action,
@@ -152,8 +158,11 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for an action method by using the specified action name,
+        /// Generates a URL with an absolute path for an action method, which contains the specified
-        /// controller name, route values, protocol to use, host name and fragment.
+        /// <paramref name="action"/> name, <paramref name="controller"/> name, route <paramref name="values"/>,
+        /// <paramref name="protocol"/> to use, <paramref name="host"/> name, and <paramref name="fragment"/>.
+        /// Generates an absolute URL if the <paramref name="protocol"/> and <paramref name="host"/> are
+        /// non-<c>null</c>.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="action">The name of the action method.</param>
@@ -162,7 +171,7 @@ namespace Microsoft.AspNetCore.Mvc
         /// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
         /// <param name="host">The host name for the URL.</param>
         /// <param name="fragment">The fragment for the URL.</param>
-        /// <returns>The fully qualified or absolute URL to an action method.</returns>
+        /// <returns>The generated URL.</returns>
         public static string Action(
             this IUrlHelper helper,
             string action,
@@ -189,11 +198,11 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for the specified route values.
+        /// Generates a URL with an absolute path for the specified route <paramref name="values"/>.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="values">An object that contains route values.</param>
-        /// <returns>The fully qualified or absolute URL.</returns>
+        /// <returns>The generated URL.</returns>
         public static string RouteUrl(this IUrlHelper helper, object values)
         {
             if (helper == null)
@@ -205,11 +214,11 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for the specified route name.
+        /// Generates a URL with an absolute path for the specified <paramref name="routeName"/>.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="routeName">The name of the route that is used to generate URL.</param>
-        /// <returns>The fully qualified or absolute URL.</returns>
+        /// <returns>The generated URL.</returns>
         public static string RouteUrl(this IUrlHelper helper, string routeName)
         {
             if (helper == null)
@@ -221,13 +230,13 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for the specified route values by
+        /// Generates a URL with an absolute path for the specified <paramref name="routeName"/> and route
-        /// using the specified route name.
+        /// <paramref name="values"/>.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="routeName">The name of the route that is used to generate URL.</param>
         /// <param name="values">An object that contains route values.</param>
-        /// <returns>The fully qualified or absolute URL.</returns>
+        /// <returns>The generated URL.</returns>
         public static string RouteUrl(this IUrlHelper helper, string routeName, object values)
         {
             if (helper == null)
@@ -239,14 +248,14 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for the specified route values by
+        /// Generates a URL with an absolute path for the specified route <paramref name="routeName"/> and route
-        /// using the specified route name, and protocol to use.
+        /// <paramref name="values"/>, which contains the specified <paramref name="protocol"/> to use.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="routeName">The name of the route that is used to generate URL.</param>
         /// <param name="values">An object that contains route values.</param>
         /// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
-        /// <returns>The fully qualified or absolute URL.</returns>
+        /// <returns>The generated URL.</returns>
         public static string RouteUrl(
             this IUrlHelper helper,
             string routeName,
@@ -262,15 +271,17 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for the specified route values by
+        /// Generates a URL with an absolute path for the specified route <paramref name="routeName"/> and route
-        /// using the specified route name, protocol to use, and host name.
+        /// <paramref name="values"/>, which contains the specified <paramref name="protocol"/> to use and
+        /// <paramref name="host"/> name. Generates an absolute URL if
+        /// <see cref="UrlActionContext.Protocol"/> and <see cref="UrlActionContext.Host"/> are non-<c>null</c>.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="routeName">The name of the route that is used to generate URL.</param>
         /// <param name="values">An object that contains route values.</param>
         /// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
         /// <param name="host">The host name for the URL.</param>
-        /// <returns>The fully qualified or absolute URL.</returns>
+        /// <returns>The generated URL.</returns>
         public static string RouteUrl(
             this IUrlHelper helper,
             string routeName,
@@ -287,8 +298,10 @@ namespace Microsoft.AspNetCore.Mvc
         }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL for the specified route values by
+        /// Generates a URL with an absolute path for the specified route <paramref name="routeName"/> and route
-        /// using the specified route name, protocol to use, host name and fragment.
+        /// <paramref name="values"/>, which contains the specified <paramref name="protocol"/> to use,
+        /// <paramref name="host"/> name and <paramref name="fragment"/>. Generates an absolute URL if
+        /// <see cref="UrlActionContext.Protocol"/> and <see cref="UrlActionContext.Host"/> are non-<c>null</c>.
         /// </summary>
         /// <param name="helper">The <see cref="IUrlHelper"/>.</param>
         /// <param name="routeName">The name of the route that is used to generate URL.</param>
@@ -296,7 +309,7 @@ namespace Microsoft.AspNetCore.Mvc
         /// <param name="protocol">The protocol for the URL, such as "http" or "https".</param>
         /// <param name="host">The host name for the URL.</param>
         /// <param name="fragment">The fragment for the URL.</param>
-        /// <returns>The fully qualified or absolute URL.</returns>
+        /// <returns>The generated URL.</returns>
         public static string RouteUrl(
             this IUrlHelper helper,
             string routeName,