Add documentation to Microsoft.Extensions.Http

src/libraries/Microsoft.Extensions.Http/src/HttpMessageHandlerBuilder.cs

@@ -61,6 +61,21 @@ public abstract class HttpMessageHandlerBuilder
         /// </returns>
         public abstract HttpMessageHandler Build();
 
+        /// <summary>
+        /// Constructs an instance of <see cref="HttpMessageHandler"/> by chaining <paramref name="additionalHandlers"/> one after another with <paramref name="primaryHandler"/> in the
+        /// end of the chain. The resulting pipeline is used by <see cref="IHttpClientFactory"/> infrastructure to create <see cref="HttpClient"/> instances with customized message
+        /// handlers. The resulting pipeline can also be accessed by using <see cref="IHttpMessageHandlerFactory"/> instead of <see cref="IHttpClientFactory"/>.
+        /// </summary>
+        /// <param name="primaryHandler">An instance of <see cref="HttpMessageHandler"/> to operate at the bottom of the handler chain and actually handle the HTTP transport operations.</param>
+        /// <param name="additionalHandlers">An ordered list of <see cref="DelegatingHandler"/> instances to be invoked as part
+        /// of sending an <see cref="HttpRequestMessage"/> and receiving an <see cref="HttpResponseMessage"/>.
+        /// The handlers are invoked in a top-down fashion. That is, the first entry is invoked first for
+        /// an outbound request message but last for an inbound response message.</param>
+        /// <returns>The HTTP message handler chain.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="primaryHandler "/> or <paramref name="additionalHandlers "/> is <see langword="null"/>.</exception>
+        /// <exception cref="InvalidOperationException"><paramref name="additionalHandlers "/> contains a <see langword="null"/> entry.
+        /// -or-
+        /// The <c>DelegatingHandler.InnerHandler</c> property must be <see langword="null"/>. <c>DelegatingHandler</c> instances provided to <c>HttpMessageHandlerBuilder</c> must not be reused or cached.</exception>
         protected internal static HttpMessageHandler CreateHandlerPipeline(HttpMessageHandler primaryHandler, IEnumerable<DelegatingHandler> additionalHandlers)
         {
             // This is similar to https://github.com/aspnet/AspNetWebStack/blob/master/src/System.Net.Http.Formatting/HttpClientFactory.cs#L58

src/libraries/Microsoft.Extensions.Http/src/IHttpMessageHandlerBuilderFilter.cs

@@ -16,6 +16,7 @@ public interface IHttpMessageHandlerBuilderFilter
         /// Applies additional initialization to the <see cref="HttpMessageHandlerBuilder"/>
         /// </summary>
         /// <param name="next">A delegate which will run the next <see cref="IHttpMessageHandlerBuilderFilter"/>.</param>
+        /// <returns>The configured <see cref="HttpMessageHandlerBuilder"/>.</returns>
         Action<HttpMessageHandlerBuilder> Configure(Action<HttpMessageHandlerBuilder> next);
     }
 }

src/libraries/Microsoft.Extensions.Http/src/Logging/LoggingHttpMessageHandler.cs

@@ -10,13 +10,21 @@
 
 namespace Microsoft.Extensions.Http.Logging
 {
+    /// <summary>
+    /// Handles logging of the lifecycle for an HTTP request.
+    /// </summary>
     public class LoggingHttpMessageHandler : DelegatingHandler
     {
         private ILogger _logger;
         private readonly HttpClientFactoryOptions _options;
 
         private static readonly Func<string, bool> _shouldNotRedactHeaderValue = (header) => false;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="LoggingHttpMessageHandler"/> class with a specified logger.
+        /// </summary>
+        /// <param name="logger">The <see cref="ILogger"/> to log to.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="logger"/> is <see langword="null"/>.</exception>
         public LoggingHttpMessageHandler(ILogger logger)
         {
             if (logger == null)
@@ -27,6 +35,12 @@ public LoggingHttpMessageHandler(ILogger logger)
             _logger = logger;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="LoggingHttpMessageHandler"/> class with a specified logger and options.
+        /// </summary>
+        /// <param name="logger">The <see cref="ILogger"/> to log to.</param>
+        /// <param name="options">The <see cref="HttpClientFactoryOptions"/> used to configure the <see cref="LoggingHttpMessageHandler"/> instance.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="logger"/> or <paramref name="options"/> is <see langword="null"/>.</exception>
         public LoggingHttpMessageHandler(ILogger logger, HttpClientFactoryOptions options)
         {
             if (logger == null)
@@ -43,6 +57,8 @@ public LoggingHttpMessageHandler(ILogger logger, HttpClientFactoryOptions option
             _options = options;
         }
 
+        /// <inheritdoc />
+        /// <remarks>Loggs the request to and response from the sent <see cref="HttpRequestMessage"/>.</remarks>
         protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
         {
             if (request == null)

src/libraries/Microsoft.Extensions.Http/src/Logging/LoggingScopeHttpMessageHandler.cs

@@ -10,13 +10,21 @@
 
 namespace Microsoft.Extensions.Http.Logging
 {
+    /// <summary>
+    /// Handles logging of the lifecycle for an HTTP request within a log scope.
+    /// </summary>
     public class LoggingScopeHttpMessageHandler : DelegatingHandler
     {
         private ILogger _logger;
         private readonly HttpClientFactoryOptions _options;
 
         private static readonly Func<string, bool> _shouldNotRedactHeaderValue = (header) => false;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="LoggingScopeHttpMessageHandler"/> class with a specified logger.
+        /// </summary>
+        /// <param name="logger">The <see cref="ILogger"/> to log to.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="logger"/> is <see langword="null"/>.</exception>
         public LoggingScopeHttpMessageHandler(ILogger logger)
         {
             if (logger == null)
@@ -27,6 +35,12 @@ public LoggingScopeHttpMessageHandler(ILogger logger)
             _logger = logger;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="LoggingScopeHttpMessageHandler"/> class with a specified logger and options.
+        /// </summary>
+        /// <param name="logger">The <see cref="ILogger"/> to log to.</param>
+        /// <param name="options">The <see cref="HttpClientFactoryOptions"/> used to configure the <see cref="LoggingScopeHttpMessageHandler"/> instance.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="logger"/> or <paramref name="options"/> is <see langword="null"/>.</exception>
         public LoggingScopeHttpMessageHandler(ILogger logger, HttpClientFactoryOptions options)
         {
             if (logger == null)
@@ -43,6 +57,8 @@ public LoggingScopeHttpMessageHandler(ILogger logger, HttpClientFactoryOptions o
             _options = options;
         }
 
+        /// <inheritdoc />
+        /// <remarks>Loggs the request to and response from the sent <see cref="HttpRequestMessage"/>.</remarks>
         protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
         {
             if (request == null)