Add missing code docs to integration libraries (#4137)

* Added code docs to AppInsights Core lib

* Add missing code docs to integration libraries

Co-authored-by: Chris Mullins <[email protected]>

libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/ApplicationBuilderExtensions.cs

@@ -6,8 +6,14 @@
 
 namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.Core
 {
+    /// <summary>
+    /// ApplicationBuilder extension methods for use when registering Application Insights services at startup.
+    /// </summary>
     public static class ApplicationBuilderExtensions
     {
+        /// <summary>
+        /// Constant key used for Application Insights Instrumentation Key.
+        /// </summary>
         public const string AppInsightsInstrumentationKey = "ApplicationInsights:InstrumentationKey";
 
         /// <summary>

libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core.csproj

@@ -22,11 +22,6 @@
     <DebugSymbols>true</DebugSymbols>
   </PropertyGroup>
 
-  <PropertyGroup>
-    <!-- These documentation warnings excludes should be removed as part of https://github.com/microsoft/botbuilder-dotnet/issues/4052 -->
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
-  </PropertyGroup>
-
   <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
     <FrameworkReference Include="Microsoft.AspNetCore.App" />
   </ItemGroup>

libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/ServiceCollectionExtensions.cs

@@ -13,6 +13,9 @@
 
 namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.Core
 {
+    /// <summary>
+    /// Services collection extension methods for use when configuring Application Insights at startup.
+    /// </summary>
     public static class ServiceCollectionExtensions
     {
         /// <summary>

libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetryBotIdInitializer.cs

@@ -17,14 +17,23 @@ namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.Core
     /// </summary>
     public class TelemetryBotIdInitializer : ITelemetryInitializer
     {
+        /// <summary>
+        /// Constant key used for storing activity information in turn state.
+        /// </summary>
         public static readonly string BotActivityKey = "BotBuilderActivity";
+
         private readonly IHttpContextAccessor _httpContextAccessor;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TelemetryBotIdInitializer"/> class.
+        /// </summary>
+        /// <param name="httpContextAccessor">The HttpContextAccessor used to access the current HttpContext.</param>
         public TelemetryBotIdInitializer(IHttpContextAccessor httpContextAccessor)
         {
             _httpContextAccessor = httpContextAccessor ?? throw new ArgumentNullException(nameof(httpContextAccessor));
         }
 
+        /// <inheritdoc/>
         public void Initialize(ITelemetry telemetry)
         {
             if (telemetry == null)

libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetrySaveBodyASPMiddleware.cs

@@ -12,20 +12,32 @@
 
 namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.Core
 {
-    // This class has been deprecated in favor of using TelemetryInitializerMiddleware in
-    // Microsoft.Bot.Integration.ApplicationInsights.Core and Microsoft.Bot.Integration.ApplicationInsights.WebApi
+    /// <summary>
+    /// Middleware to store the incoming activity request body into the HttpContext items collection.
+    /// This class has been deprecated in favor of using TelemetryInitializerMiddleware in
+    /// Microsoft.Bot.Integration.ApplicationInsights.Core and Microsoft.Bot.Integration.ApplicationInsights.WebApi.
+    /// </summary>
     [Obsolete("This class is deprecated. Please add TelemetryInitializerMiddleware to your adapter's middleware pipeline instead.")]
     [SuppressMessage("Globalization", "CA1307:Specify StringComparison", Justification = "This class is deprecated, we won't fix FxCop issues")]
     [SuppressMessage("AsyncUsage.CSharp.Naming", "UseAsyncSuffix:Use Async suffix", Justification = "This class is deprecated, we won't fix FxCop issues")]
     public class TelemetrySaveBodyASPMiddleware
     {
         private readonly RequestDelegate _next;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TelemetrySaveBodyASPMiddleware"/> class.
+        /// </summary>
+        /// <param name="next">The delegate to the next piece of middleware in the pipeline.</param>
         public TelemetrySaveBodyASPMiddleware(RequestDelegate next)
         {
             _next = next ?? throw new ArgumentNullException(nameof(next));
         }
 
+        /// <summary>
+        /// Invokes the TelemetrySaveBodyASPMiddleware middleware.
+        /// </summary>
+        /// <param name="httpContext">The HttpContext.</param>
+        /// <returns>A task that represents the work queued to execute.</returns>
         public async Task Invoke(HttpContext httpContext)
         {
             var request = httpContext.Request;

libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi.csproj

@@ -22,11 +22,6 @@
     <DebugType>Full</DebugType>
     <DebugSymbols>true</DebugSymbols>
   </PropertyGroup>
-
-  <PropertyGroup>
-    <!-- These documentation warnings excludes should be removed as part of https://github.com/microsoft/botbuilder-dotnet/issues/4052 -->
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
-  </PropertyGroup>
 
   <PropertyGroup>
     <AssemblyName>Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi</AssemblyName>

libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi/TelemetryBotIdInitializer.cs

@@ -18,8 +18,15 @@ namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi
     /// </summary>
     public class TelemetryBotIdInitializer : ITelemetryInitializer
     {
+        /// <summary>
+        /// Constant key used for storing activity information in turn state.
+        /// </summary>
         public static readonly string BotActivityKey = "BotBuilderActivity";
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TelemetryBotIdInitializer"/> class.
+        /// </summary>
+        /// <param name="telemetry">The telemetry item to be logged to Application Insights.</param>
         public void Initialize(ITelemetry telemetry)
         {
             var httpContext = HttpContext.Current;

libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpAdapter.cs

@@ -56,16 +56,42 @@ public BotFrameworkHttpAdapter(
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BotFrameworkHttpAdapter"/> class,
+        /// using a credential provider.
+        /// </summary>
+        /// <param name="credentialProvider">The credential provider.</param>
+        /// <param name="channelProvider">The channel provider.</param>
+        /// <param name="logger">The ILogger implementation this adapter should use.</param>
         public BotFrameworkHttpAdapter(ICredentialProvider credentialProvider = null, IChannelProvider channelProvider = null, ILogger<BotFrameworkHttpAdapter> logger = null)
             : this(credentialProvider ?? new SimpleCredentialProvider(), new AuthenticationConfiguration(), channelProvider, null, null, null, logger)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BotFrameworkHttpAdapter"/> class,
+        /// using a credential provider.
+        /// </summary>
+        /// <param name="credentialProvider">The credential provider.</param>
+        /// <param name="channelProvider">The channel provider.</param>
+        /// <param name="httpClient">The <see cref="HttpClient"/> used.</param>
+        /// <param name="logger">The ILogger implementation this adapter should use.</param>
         public BotFrameworkHttpAdapter(ICredentialProvider credentialProvider, IChannelProvider channelProvider, HttpClient httpClient, ILogger<BotFrameworkHttpAdapter> logger)
             : this(credentialProvider ?? new SimpleCredentialProvider(), new AuthenticationConfiguration(), channelProvider, null, httpClient, null, logger)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BotFrameworkHttpAdapter"/> class.
+        /// </summary>
+        /// <param name="configuration">An <see cref="IConfiguration"/> instance.</param>
+        /// <param name="credentialProvider">The credential provider.</param>
+        /// <param name="authConfig">The authentication configuration.</param>
+        /// <param name="channelProvider">The channel provider.</param>
+        /// <param name="connectorClientRetryPolicy">Retry policy for retrying HTTP operations.</param>
+        /// <param name="customHttpClient">The HTTP client.</param>
+        /// <param name="middleware">The middleware to initially add to the adapter.</param>
+        /// <param name="logger">The ILogger implementation this adapter should use.</param>
         protected BotFrameworkHttpAdapter(
             IConfiguration configuration,
             ICredentialProvider credentialProvider,
@@ -87,11 +113,25 @@ protected BotFrameworkHttpAdapter(
             }
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BotFrameworkHttpAdapter"/> class.
+        /// </summary>
+        /// <param name="configuration">An <see cref="IConfiguration"/> instance.</param>
+        /// <param name="logger">The ILogger implementation this adapter should use.</param>
         protected BotFrameworkHttpAdapter(IConfiguration configuration, ILogger<BotFrameworkHttpAdapter> logger = null)
             : this(configuration, new ConfigurationCredentialProvider(configuration), new AuthenticationConfiguration(), new ConfigurationChannelProvider(configuration), logger: logger)
         {
         }
-
+
+        /// <summary>
+        /// This method can be called from inside a POST method on any Controller implementation.
+        /// </summary>
+        /// <param name="httpRequest">The HTTP request object, typically in a POST handler by a Controller.</param>
+        /// <param name="httpResponse">The HTTP response object.</param>
+        /// <param name="bot">The bot implementation.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used by other objects
+        /// or threads to receive notice of cancellation.</param>
+        /// <returns>A task that represents the work queued to execute.</returns>
         public async Task ProcessAsync(HttpRequest httpRequest, HttpResponse httpResponse, IBot bot, CancellationToken cancellationToken = default)
         {
             if (httpRequest == null)

libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpClient.cs

@@ -29,6 +29,13 @@ namespace Microsoft.Bot.Builder.Integration.AspNet.Core
     /// </remarks>
     public class BotFrameworkHttpClient : BotFrameworkClient
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BotFrameworkHttpClient"/> class.
+        /// </summary>
+        /// <param name="httpClient">A <see cref="HttpClient"/>.</param>
+        /// <param name="credentialProvider">An instance of <see cref="ICredentialProvider"/>.</param>
+        /// <param name="channelProvider">An instance of <see cref="IChannelProvider"/>.</param>
+        /// <param name="logger">An instance of <see cref="ILogger"/>.</param>
         public BotFrameworkHttpClient(
             HttpClient httpClient,
             ICredentialProvider credentialProvider,
@@ -42,16 +49,43 @@ public BotFrameworkHttpClient(
             ConnectorClient.AddDefaultRequestHeaders(HttpClient);
         }
 
-        // Cache for appCredentials to speed up token acquisition (a token is not requested unless is expired)
-        // AppCredentials are cached using appId + scope (this last parameter is only used if the app credentials are used to call a skill)
+        /// <summary>
+        /// Gets the Cache for appCredentials to speed up token acquisition (a token is not requested unless is expired).
+        /// AppCredentials are cached using appId + scope (this last parameter is only used if the app credentials are used to call a skill).
+        /// </summary>
+        /// <value>ConcurrentDictionary of <see cref="AppCredentials"/>.</value>
         protected static ConcurrentDictionary<string, AppCredentials> AppCredentialMapCache { get; } = new ConcurrentDictionary<string, AppCredentials>();
 
+        /// <summary>
+        /// Gets the channel provider for this adapter.
+        /// </summary>
+        /// <value>
+        /// The channel provider for this adapter.
+        /// </value>
         protected IChannelProvider ChannelProvider { get; }
 
+        /// <summary>
+        /// Gets the credential provider for this adapter.
+        /// </summary>
+        /// <value>
+        /// The credential provider for this adapter.
+        /// </value>
         protected ICredentialProvider CredentialProvider { get; }
 
+        /// <summary>
+        /// Gets the HttpClient for this adapter.
+        /// </summary>
+        /// <value>
+        /// The HttpClient for this adapter.
+        /// </value>
         protected HttpClient HttpClient { get; }
 
+        /// <summary>
+        /// Gets the logger for this adapter.
+        /// </summary>
+        /// <value>
+        /// The logger for this adapter.
+        /// </value>
         protected ILogger Logger { get; }
 
         /// <summary>

libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotMessageHandler.cs

@@ -11,8 +11,20 @@
 
 namespace Microsoft.Bot.Builder.Integration.AspNet.Core.Handlers
 {
+    /// <summary>
+    /// A handler to process incoming http requests via using an adapter.
+    /// </summary>
     public class BotMessageHandler : BotMessageHandlerBase
     {
+        /// <summary>
+        /// Deserializes the incoming request using a BotMessageHandler, processes it with an <see cref="IAdapterIntegration"/>
+        /// and returns an <see cref="InvokeResponse"/>.
+        /// </summary>
+        /// <param name="request">A <see cref="HttpRequest"/>.</param>
+        /// <param name="adapter">An instance of <see cref="IAdapterIntegration"/>.</param>
+        /// <param name="botCallbackHandler">An instance of <see cref="BotCallbackHandler"/>.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/>.</param>
+        /// <returns>An <see cref="InvokeResponse"/> returned from the adapter.</returns>
         protected override async Task<InvokeResponse> ProcessMessageRequestAsync(HttpRequest request, IAdapterIntegration adapter, BotCallbackHandler botCallbackHandler, CancellationToken cancellationToken)
         {
             Activity activity;

libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotMessageHandlerBase.cs

@@ -14,14 +14,29 @@
 
 namespace Microsoft.Bot.Builder.Integration.AspNet.Core.Handlers
 {
+    /// <summary>
+    /// Abstract base class for a bot message handler.
+    /// </summary>
     public abstract class BotMessageHandlerBase
     {
+        /// <summary>
+        /// A <see cref="JsonSerializer"/> for use when serializing bot messages.
+        /// </summary>
         public static readonly JsonSerializer BotMessageSerializer = JsonSerializer.Create(MessageSerializerSettings.Create());
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BotMessageHandlerBase"/> class.
+        /// </summary>
         public BotMessageHandlerBase()
         {
         }
 
+        /// <summary>
+        /// Handles common behavior for handling requests, including checking valid request method and content type.
+        /// Processes the request using the registered adapter and bot and writes the result to the response on the <see cref="HttpContext"/>.
+        /// </summary>
+        /// <param name="httpContext">The <see cref="HttpContext"/>.</param>
+        /// <returns>A Task that represents the work to be executed.</returns>
         public async Task HandleAsync(HttpContext httpContext)
         {
             var request = httpContext.Request;
@@ -95,6 +110,15 @@ public async Task HandleAsync(HttpContext httpContext)
             }
         }
 
+        /// <summary>
+        /// Abstract method to process the incoming request using the registered adapter and bot and
+        /// to return an <see cref="InvokeResponse"/>.
+        /// </summary>
+        /// <param name="request">A <see cref="HttpRequest"/>.</param>
+        /// <param name="adapter">An instance of <see cref="IAdapterIntegration"/>.</param>
+        /// <param name="botCallbackHandler">An instance of <see cref="BotCallbackHandler"/>.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/>.</param>
+        /// <returns>An <see cref="InvokeResponse"/> returned from the adapter.</returns>
         protected abstract Task<InvokeResponse> ProcessMessageRequestAsync(HttpRequest request, IAdapterIntegration adapter, BotCallbackHandler botCallbackHandler, CancellationToken cancellationToken);
     }
 }

libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/ConfigurationChannelProvider.cs

@@ -21,6 +21,10 @@ public sealed class ConfigurationChannelProvider : SimpleChannelProvider
         /// </summary>
         public const string ChannelServiceKey = "ChannelService";
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ConfigurationChannelProvider"/> class.
+        /// </summary>
+        /// <param name="configuration">An instance of <see cref="IConfiguration"/>.</param>
         public ConfigurationChannelProvider(IConfiguration configuration)
         {
             this.ChannelService = configuration.GetSection(ChannelServiceKey)?.Value;

libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/ConfigurationCredentialProvider.cs

@@ -17,6 +17,10 @@ namespace Microsoft.Bot.Builder.BotFramework
     /// </remarks>
     public sealed class ConfigurationCredentialProvider : SimpleCredentialProvider
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ConfigurationCredentialProvider"/> class.
+        /// </summary>
+        /// <param name="configuration">An instance of <see cref="IConfiguration"/>.</param>
         public ConfigurationCredentialProvider(IConfiguration configuration)
         {
             this.AppId = configuration.GetSection(MicrosoftAppCredentials.MicrosoftAppIdKey)?.Value;

libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/HttpHelper.cs

@@ -13,8 +13,14 @@
 
 namespace Microsoft.Bot.Builder.Integration.AspNet.Core
 {
+    /// <summary>
+    /// Helper class with methods to help with reading and responding to http requests.
+    /// </summary>
     public static class HttpHelper
     {
+        /// <summary>
+        /// An instance of <see cref="JsonSerializerSettings"/> used by the <see cref="ChannelServiceController"/>.
+        /// </summary>
         public static readonly JsonSerializerSettings BotMessageSerializerSettings = new JsonSerializerSettings
         {
             NullValueHandling = NullValueHandling.Ignore,
@@ -26,8 +32,17 @@ public static class HttpHelper
             Converters = new List<JsonConverter> { new Iso8601TimeSpanConverter() }
         };
 
+        /// <summary>
+        /// An instance of <see cref="JsonSerializer"/> created using <see cref="BotMessageSerializerSettings"/>.
+        /// </summary>
         public static readonly JsonSerializer BotMessageSerializer = JsonSerializer.Create(BotMessageSerializerSettings);
 
+        /// <summary>
+        /// Accepts an incoming HttpRequest and deserializes it using the <see cref="BotMessageSerializer"/>.
+        /// </summary>
+        /// <typeparam name="T">The type to deserialize the request into.</typeparam>
+        /// <param name="request">The HttpRequest.</param>
+        /// <returns>The deserialized request.</returns>
         public static async Task<T> ReadRequestAsync<T>(HttpRequest request)
         {
             try
@@ -53,6 +68,14 @@ public static async Task<T> ReadRequestAsync<T>(HttpRequest request)
             }
         }
 
+        /// <summary>
+        /// If an <see cref="InvokeResponse"/> is provided the status and body of the <see cref="InvokeResponse"/>
+        /// are used to set the status and body of the <see cref="HttpResponse"/>. If no <see cref="InvokeResponse"/>
+        /// is provided then the status of the <see cref="HttpResponse"/> is set to 200.
+        /// </summary>
+        /// <param name="response">A HttpResponse.</param>
+        /// <param name="invokeResponse">An instance of <see cref="InvokeResponse"/>.</param>
+        /// <returns>A Task representing the work to be executed.</returns>
         public static async Task WriteResponseAsync(HttpResponse response, InvokeResponse invokeResponse)
         {
             if (response == null)