Improve IUrlHelper and related doc comments

- #4245, #4507

Author: dougbu

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

@@ -16,11 +16,13 @@ public interface IUrlHelper
         ActionContext ActionContext { get; }
 
         /// <summary>
-        /// Generates a fully qualified or absolute URL specified by <see cref="UrlActionContext"/> for an action
-        /// method, which contains action name, controller name, route values, protocol to use, host name, and fragment.
+        /// Generates a URL with an absolute path for an action method, which contains the action
+        /// 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 @@ public interface IUrlHelper
         string Content(string contentPath);
 
         /// <summary>
-        /// Returns a value that indicates whether the URL is local. A URL with an absolute path is considered local
-        /// if it does not have a host/authority part. URLs using virtual paths ('~/') are also local.
+        /// Returns a value that indicates whether the URL is local. A URL is considered local if it does not have a
+        /// 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
-        /// contains the route name, the route values, protocol to use, host name and fragment.
+        /// Generates a URL with an absolute path, which contains the route name, route values, protocol to use, host
+        /// 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="values">An object that contains the route values.</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 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 @@ public string Controller
         }
 
         /// <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 @@ public object Values
         }
 
         /// <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 @@ public string RouteName
         }
 
         /// <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 @@ public object Values
         }
 
         /// <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 @@ public class UrlHelper : IUrlHelper
         private readonly RouteValueDictionary _routeValueDictionary;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="UrlHelper"/> class using the specified action context and
-        /// action selector.
+        /// Initializes a new instance of the <see cref="UrlHelper"/> class using the specified
+        /// <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 @@ public UrlHelper(ActionContext actionContext)
         /// <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 @@ public virtual string RouteUrl(UrlRouteContext routeContext)
         }
 
         /// <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 @@ private StringBuilder GetStringBuilder()
         /// <summary>
         /// Generates the URL using the specified components.
         /// </summary>
-        /// <param name="protocol">The protocol.</param>
-        /// <param name="host">The host.</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>
         /// <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)
         {
@@ -268,7 +282,7 @@ protected virtual string GenerateUrl(string protocol, string host, VirtualPathDa
             // VirtualPathData.VirtualPath returns string.Empty instead of null.
             Debug.Assert(pathData.VirtualPath != null);
 
-            // Perf: In most of the common cases, GenerateUrl is called with a null protocol, host and fragment. 
+            // Perf: In most of the common cases, GenerateUrl is called with a null protocol, host and fragment.
             // In such cases, we might not need to build any URL as the url generated is mostly same as the virtual path available in pathData.
             // For such common cases, this FastGenerateUrl method saves a string allocation per GenerateUrl call.
             string url;