Fix typos [mostly] in the bot.builder namespace (#3349)

libraries/Microsoft.Bot.Builder.ApplicationInsights/BotTelemetryClient.cs

@@ -9,7 +9,7 @@
 namespace Microsoft.Bot.Builder.ApplicationInsights
 {
     /// <summary>
-    /// Instanciates a BotTelemetryCLient object.
+    /// A logging client for bot telemetry.
     /// </summary>
     public class BotTelemetryClient : IBotTelemetryClient
     {
@@ -18,7 +18,7 @@ public class BotTelemetryClient : IBotTelemetryClient
         /// <summary>
         /// Initializes a new instance of the <see cref="BotTelemetryClient"/> class.
         /// </summary>
-        /// <param name="telemetryClient">the telemetry client.</param>
+        /// <param name="telemetryClient">The telemetry client to forward bot events to.</param>
         public BotTelemetryClient(TelemetryClient telemetryClient)
         {
             _telemetryClient = telemetryClient ?? throw new ArgumentNullException(nameof(telemetryClient));

libraries/Microsoft.Bot.Builder/AdapterExtensions.cs

@@ -6,24 +6,34 @@ namespace Microsoft.Bot.Builder
     public static class AdapterExtensions
     {
         /// <summary>
-        /// Register storage with the adapter so that is available via TurnContext.Get&lt;IStorage&gt;().
+        /// Registers a storage layer with the adapter. The storage object will be available via the turn context's
+        /// <see cref="TurnContext.TurnState"/>.<see cref="TurnContextStateCollection.Get{IStorage}"/> method.
         /// </summary>
-        /// <param name="botAdapter">bot adapter to register storage with.</param>
-        /// <param name="storage">IStorage implementation to register.</param>
-        /// <returns>bot adapter.</returns>
+        /// <param name="botAdapter">The <see cref="BotAdapter"/> on which to register the storage object.</param>
+        /// <param name="storage">The <see cref="IStorage"/> object to register.</param>
+        /// <returns>The updated adapter.</returns>
+        /// <remarks>
+        /// This adds <see cref="IMiddleware"/> to the adapter to register the storage layer.
+        /// </remarks>
         public static BotAdapter UseStorage(this BotAdapter botAdapter, IStorage storage)
         {
             return botAdapter.Use(new RegisterClassMiddleware<IStorage>(storage));
         }
 
         /// <summary>
-        /// Register UserState and ConversationState objects so they are accessible via TurnContext.Get&lt;UserState&gt;() and add auto save middleware.
+        /// Registers user and conversation state objects with the adapter. These objects will be available via the turn context's
+        /// <see cref="TurnContext.TurnState"/>.<see cref="TurnContextStateCollection.Get{T}"/> method.
         /// </summary>
-        /// <param name="botAdapter">bot adapater to add save state to.</param>
-        /// <param name="userState">UserState to use (default is new UserState(registered storage)).</param>
-        /// <param name="conversationState">ConversationState to use (default is new ConversationState (registered storage)).</param>
-        /// <param name="auto">automatically manage state (default is true), if set to false, it is your responsibility to load and save state.</param>
-        /// <returns>Botadapter.</returns>
+        /// <param name="botAdapter">The <see cref="BotAdapter"/> on which to register the storage object.</param>
+        /// <param name="userState">The <see cref="UserState"/> object to register.</param>
+        /// <param name="conversationState">The <see cref="ConversationState"/> object to register.</param>
+        /// <param name="auto">`true` to automatically persist state each turn; otherwise, `false`.
+        /// When false, it is your responsibility to persist state each turn.</param>
+        /// <returns>The updated adapter.</returns>
+        /// <remarks>
+        /// This adds <see cref="IMiddleware"/> to register the user and conversation state management objects.
+        /// If <paramref name="auto"/> is true, this also adds middleware to automatically persist state before each turn ends.
+        /// </remarks>
         public static BotAdapter UseState(this BotAdapter botAdapter, UserState userState, ConversationState conversationState, bool auto = true)
         {
             if (botAdapter == null)

libraries/Microsoft.Bot.Builder/Adapters/TestAdapter.cs

@@ -712,7 +712,7 @@ private void Enqueue(Activity activity)
         {
             lock (_activeQueueLock)
             {
-                // if there are pending requests, fulfil them with the activity.
+                // if there are pending requests, fulfill them with the activity.
                 while (_queuedRequests.Any())
                 {
                     var tcs = _queuedRequests.Dequeue();

libraries/Microsoft.Bot.Builder/Adapters/TestFlow.cs

@@ -47,7 +47,7 @@ public TestFlow(TestAdapter adapter, BotCallbackHandler callback = null)
         /// </summary>
         /// <param name="task">The exchange to add to the exchanges in the existing flow.</param>
         /// <param name="flow">The flow to build up from. This provides the test adapter to use,
-        /// the bot turn processing locig to test, and a set of exchanges to model and test.</param>
+        /// the bot turn processing logic to test, and a set of exchanges to model and test.</param>
         public TestFlow(Task task, TestFlow flow)
         {
             _testTask = task ?? Task.CompletedTask;
@@ -60,7 +60,7 @@ public TestFlow(Task task, TestFlow flow)
         /// </summary>
         /// <param name="getTask">The exchange to add to the exchanges in the existing flow.</param>
         /// <param name="flow">The flow to build up from. This provides the test adapter to use,
-        /// the bot turn processing locig to test, and a set of exchanges to model and test.</param>
+        /// the bot turn processing logic to test, and a set of exchanges to model and test.</param>
         public TestFlow(Func<Task> getTask, TestFlow flow)
         {
             _testTask = getTask != null ? getTask() : Task.CompletedTask;
@@ -309,7 +309,7 @@ public TestFlow AssertReply(IActivity expected, IEqualityComparer<IActivity> equ
         /// Adds an assertion that the turn processing logic responds as expected.
         /// </summary>
         /// <param name="validateActivity">A validation method to apply to an activity from the bot.
-        /// This activity should throw an exception if validation wfails.</param>
+        /// This activity should throw an exception if validation fails.</param>
         /// <param name="description">A message to send if the actual response is not as expected.</param>
         /// <param name="timeout">The amount of time in milliseconds within which a response is expected.</param>
         /// <returns>A new <see cref="TestFlow"/> object that appends this assertion to the modeled exchange.</returns>

libraries/Microsoft.Bot.Builder/AutoSaveStateMiddleware.cs

@@ -8,8 +8,12 @@
 namespace Microsoft.Bot.Builder
 {
     /// <summary>
-    ///  Middleware to automatically call .SaveChanges() at the end of the turn for all BotState class it is managing.
+    ///  Middleware to automatically persist state before the end of each turn.
     /// </summary>
+    /// <remarks>
+    /// This calls <see cref="BotState.SaveChangesAsync(ITurnContext, bool, CancellationToken)"/>
+    /// on each state object it manages.
+    /// </remarks>
     public class AutoSaveStateMiddleware : IMiddleware
     {
         /// <summary>
@@ -33,10 +37,10 @@ public AutoSaveStateMiddleware(BotStateSet botStateSet)
         public BotStateSet BotStateSet { get; set; }
 
         /// <summary>
-        /// Add a BotState to the list of sources to load.
+        /// Adds a state management object to the list of states to manage.
         /// </summary>
-        /// <param name="botState">botState to manage.</param>
-        /// <returns>botstateset for chaining more .Use().</returns>
+        /// <param name="botState">The bot state to add.</param>
+        /// <returns>The updated <see cref="BotStateSet"/> object.</returns>
         public AutoSaveStateMiddleware Add(BotState botState)
         {
             if (botState == null)
@@ -49,12 +53,15 @@ public AutoSaveStateMiddleware Add(BotState botState)
         }
 
         /// <summary>
-        /// Middleware implementation which calls savesChanges automatically at the end of the turn.
+        /// Before the turn ends, calls <see cref="BotState.SaveChangesAsync(ITurnContext, bool, CancellationToken)"/>
+        /// on each state object.
         /// </summary>
-        /// <param name="turnContext">turn context.</param>
-        /// <param name="next">next middlware.</param>
-        /// <param name="cancellationToken">cancellationToken.</param>
-        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+        /// <param name="turnContext">The context object for this turn.</param>
+        /// <param name="next">The delegate to call to continue the bot middleware pipeline.</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>
+        /// <remarks>This middleware persists state after the bot logic completes and before the turn ends.</remarks>
         public async Task OnTurnAsync(ITurnContext turnContext, NextDelegate next, CancellationToken cancellationToken = default(CancellationToken))
         {
             await next(cancellationToken).ConfigureAwait(false);

libraries/Microsoft.Bot.Builder/BotFrameworkAdapter.cs

@@ -1271,11 +1271,11 @@ private IConnectorClient CreateConnectorClient(string serviceUrl, AppCredentials
         }
 
         /// <summary>
-        /// Gets the application credentials. App Credentials are cached so as to ensure we are not refreshing
-        /// token every time.
+        /// Gets the application credentials. App credentials are cached to avoid refreshing the
+        /// token each time.
         /// </summary>
-        /// <param name="appId">The application identifier (AAD Id for the bot).</param>
-        /// <param name="oAuthScope">The scope for the token, skills will use the Skill App Id. </param>
+        /// <param name="appId">The application identifier (AAD ID for the bot).</param>
+        /// <param name="oAuthScope">The scope for the token. Skills use the skill's app ID. </param>
         /// <param name="cancellationToken">Cancellation token.</param>
         /// <returns>App credentials.</returns>
         private async Task<AppCredentials> GetAppCredentialsAsync(string appId, string oAuthScope = null, CancellationToken cancellationToken = default)

libraries/Microsoft.Bot.Builder/BotState.cs

@@ -345,8 +345,8 @@ internal string ComputeHash(object obj)
         }
 
         /// <summary>
-        /// Implements IPropertyAccessor for an IPropertyContainer.
-        /// Note the semantic of this accessor are intended to be lazy, this means teh Get, Set and Delete
+        /// Implements an <see cref="IStatePropertyAccessor{T}"/> for a property container.
+        /// Note the semantics of this accessor are intended to be lazy, this means the Get, Set and Delete
         /// methods will first call LoadAsync. This will be a no-op if the data is already loaded.
         /// The implication is you can just use this accessor in the application code directly without first calling LoadAsync
         /// this approach works with the AutoSaveStateMiddleware which will save as needed at the end of a turn.

libraries/Microsoft.Bot.Builder/ChannelServiceHandler.cs

@@ -240,9 +240,9 @@ protected virtual Task<IList<ChannelAccount>> OnGetActivityMembersAsync(ClaimsId
         /// * IsGroup set to true if this is not a direct message (default is false)
         /// * Array containing the members to include in the conversation
         ///
-        /// The return value is a ResourceResponse which contains a conversation id
+        /// The return value is a ResourceResponse which contains a conversation ID
         /// which is suitable for use
-        /// in the message payload and REST API uris.
+        /// in the message payload and REST API URIs.
         ///
         /// Most channels only support the semantics of bots initiating a direct
         /// message conversation.  An example of how to do that would be:
@@ -410,13 +410,13 @@ private async Task<ClaimsIdentity> AuthenticateAsync(string authHeader)
                 var isAuthDisabled = await _credentialProvider.IsAuthenticationDisabledAsync().ConfigureAwait(false);
                 if (isAuthDisabled)
                 {
-                    // In the scenario where Auth is disabled, we still want to have the
+                    // In the scenario where auth is disabled, we still want to have the
                     // IsAuthenticated flag set in the ClaimsIdentity. To do this requires
                     // adding in an empty claim.
                     return new ClaimsIdentity(new List<Claim>(), "anonymous");
                 }
 
-                // No Auth Header. Auth is required. Request is not authorized.
+                // No auth header. Auth is required. Request is not authorized.
                 throw new UnauthorizedAccessException();
             }
 

libraries/Microsoft.Bot.Builder/IBotTelemetryClient.cs

@@ -7,7 +7,7 @@
 namespace Microsoft.Bot.Builder
 {
     /// <summary>
-    /// Logging client for Bot Telemetry.
+    /// Describes a logging client for bot telemetry.
     /// </summary>
     public interface IBotTelemetryClient
     {

libraries/Microsoft.Bot.Builder/IStatePropertyAccessor.cs

@@ -8,18 +8,19 @@
 namespace Microsoft.Bot.Builder
 {
     /// <summary>
-    /// Interface which defines methods for how you can get data from a property source such as BotState.
+    /// Interface which defines methods for how you can get data from a property source,
+    /// such as <see cref="BotState"/>.
     /// </summary>
     /// <typeparam name="T">type of the property.</typeparam>
     public interface IStatePropertyAccessor<T> : IStatePropertyInfo
     {
         /// <summary>
-        /// Get the property value from the source.
-        /// If the property is not set, and no default value was defined, a <see cref="MissingMemberException"/> is thrown.
+        /// Gets the property value from the source.
         /// </summary>
         /// <param name="turnContext">Turn Context.</param>
         /// <param name="defaultValueFactory">Function which defines the property value to be returned if no value has been set.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
+        /// <exception cref="MissingMemberException">The property has no value and no <paramref name="defaultValueFactory"/>.</exception>
         /// <returns>A <see cref="Task"/> representing the result of the asynchronous operation.</returns>
         Task<T> GetAsync(ITurnContext turnContext, Func<T> defaultValueFactory = null, CancellationToken cancellationToken = default(CancellationToken));
 

libraries/Microsoft.Bot.Builder/IStatePropertyInfo.cs

@@ -4,7 +4,7 @@
 namespace Microsoft.Bot.Builder
 {
     /// <summary>
-    /// This is metadata about the property including policy info.
+    /// Metadata about a property, including policy info.
     /// </summary>
     public interface IStatePropertyInfo
     {

libraries/Microsoft.Bot.Builder/InvokeResponse.cs

@@ -4,25 +4,25 @@
 namespace Microsoft.Bot.Builder
 {
     /// <summary>
-    /// Tuple class containing an HTTP Status Code and a JSON Serializable
-    /// object. The HTTP Status code is, in the invoke activity scenario, what will
-    /// be set in the resulting POST. The Body of the resulting POST will be
-    /// the JSON Serialized content from the Body property.
+    /// A tuple class containing an HTTP status code and a JSON-serializable
+    /// object. The HTTP status code is, in the invoke activity scenario, what will
+    /// be set in the resulting POST. The body of the resulting POST will be
+    /// the JSON-serialized content from the <see cref="Body"/> property.
     /// </summary>
     public class InvokeResponse
     {
         /// <summary>Gets or sets the HTTP status code for the response.</summary>
         /// <value>The HTTP status code.</value>
         /// <remarks>
-        /// The POST that is generated in response to the incoming Invoke Activity
-        /// will have the HTTP Status code specificied by this field.
+        /// The POST that is generated in response to the incoming invoke activity
+        /// will have the HTTP status code specified by this field.
         /// </remarks>
         public int Status { get; set; }
 
         /// <summary>Gets or sets the body content for the response.</summary>
         /// <value>The body content.</value>
         /// <remarks>
-        /// The POST that is generated in response to the incoming Invoke Activity
+        /// The POST that is generated in response to the incoming invoke activity
         /// will have a body generated by JSON serializing the object in this field.
         /// </remarks>
         public object Body { get; set; }

libraries/Microsoft.Bot.Builder/MiddlewareSet.cs

@@ -70,7 +70,7 @@ private Task ReceiveActivityInternalAsync(ITurnContext turnContext, BotCallbackH
             // Check if we're at the end of the middleware list yet
             if (nextMiddlewareIndex == _middleware.Count)
             {
-                // If all the Middlware ran, the "leading edge" of the tree is now complete.
+                // If all the middleware ran, the "leading edge" of the tree is now complete.
                 // This means it's time to run any developer specified callback.
                 // Once this callback is done, the "trailing edge" calls are then completed. This
                 // allows code that looks like:
@@ -86,7 +86,7 @@ private Task ReceiveActivityInternalAsync(ITurnContext turnContext, BotCallbackH
             // Get the next piece of middleware
             var nextMiddleware = _middleware[nextMiddlewareIndex];
 
-            // Execute the next middleware passing a closure that will recurse back into this method at the next piece of middlware as the NextDelegate
+            // Execute the next middleware passing a closure that will recurse back into this method at the next piece of middleware as the NextDelegate
             return nextMiddleware.OnTurnAsync(
                 turnContext,
                 (ct) => ReceiveActivityInternalAsync(turnContext, callback, nextMiddlewareIndex + 1, ct),

libraries/Microsoft.Bot.Builder/PathUtils.cs

@@ -5,11 +5,12 @@ namespace Microsoft.Bot.Builder
     public static class PathUtils
     {
         /// <summary>
-        /// Normalize authored path to os path.
+        /// Normalizes authored path to OS-compatible path.
         /// </summary>
         /// <remarks>
-        /// path is from authored content which doesn't know what OS it is running on.
-        /// This method treats / and \ both as separators regardless of OS, for windows that means / -> \ and for linux/mac \ -> /.
+        /// Path is from authored content which doesn't know what OS it is running on.
+        /// This method treats / and \ both as separators regardless of OS, for Windows that means
+        /// changing all `/` characters to `/`, and for Linux/Mac `\` to `/`.
         /// This allows author to use ../foo.lg or ..\foo.lg as equivalents for importing.
         /// </remarks>
         /// <param name="ambigiousPath">authoredPath.</param>
@@ -18,12 +19,12 @@ public static string NormalizePath(string ambigiousPath)
         {
             if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
             {
-                // map linux/mac sep -> windows
+                // Map Linux/Mac separator to Windows.
                 return ambigiousPath.Replace("/", "\\");
             }
             else
             {
-                // map windows sep -> linux/mac
+                // Map Windows separator to Linux/Mac.
                 return ambigiousPath.Replace("\\", "/");
             }
         }