Docs improvements

src/Generators/Shared/RoslynExtensions.cs

@@ -38,7 +38,7 @@ internal static class RoslynExtensions
     /// </list>
     /// </summary>
     /// <param name="compilation">The <see cref="Compilation"/> to consider for analysis.</param>
-    /// <param name="fullyQualifiedMetadataName">The fully-qualified metadata type name to find.</param>
+    /// <param name="fullyQualifiedMetadataName">The fully qualified metadata type name to find.</param>
     /// <returns>The symbol to use for code analysis; otherwise, <see langword="null"/>.</returns>
     // Copied from: https://github.com/dotnet/roslyn/blob/af7b0ebe2b0ed5c335a928626c25620566372dd1/src/Workspaces/SharedUtilitiesAndExtensions/Compiler/Core/Extensions/CompilationExtensions.cs
     public static INamedTypeSymbol? GetBestTypeByMetadataName(this Compilation compilation, string fullyQualifiedMetadataName)
@@ -94,7 +94,7 @@ internal static class RoslynExtensions
 
     /// <summary>
     /// A thin wrapper over <see cref="GetBestTypeByMetadataName(Compilation, string)"/>,
-    /// but taking the type itself rather than the fully-qualified metadata type name.
+    /// but taking the type itself rather than the fully qualified metadata type name.
     /// </summary>
     /// <param name="compilation">The <see cref="Compilation"/> to consider for analysis.</param>
     /// <param name="type">The type to find.</param>

src/Libraries/Microsoft.Extensions.AI.Abstractions/AITool.cs

@@ -3,7 +3,7 @@
 
 namespace Microsoft.Extensions.AI;
 
-/// <summary>Represents a tool that may be specified to an AI service.</summary>
+/// <summary>Represents a tool that can be specified to an AI service.</summary>
 public class AITool
 {
     /// <summary>Initializes a new instance of the <see cref="AITool"/> class.</summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientExtensions.cs

@@ -14,10 +14,10 @@ public static class ChatClientExtensions
     /// <summary>Asks the <see cref="IChatClient"/> for an object of type <typeparamref name="TService"/>.</summary>
     /// <typeparam name="TService">The type of the object to be retrieved.</typeparam>
     /// <param name="client">The client.</param>
-    /// <param name="serviceKey">An optional key that may be used to help identify the target service.</param>
+    /// <param name="serviceKey">An optional key that can be used to help identify the target service.</param>
     /// <returns>The found object, otherwise <see langword="null"/>.</returns>
     /// <remarks>
-    /// The purpose of this method is to allow for the retrieval of strongly-typed services that may be provided by the <see cref="IChatClient"/>,
+    /// The purpose of this method is to allow for the retrieval of strongly typed services that may be provided by the <see cref="IChatClient"/>,
     /// including itself or any services it might be wrapping.
     /// </remarks>
     public static TService? GetService<TService>(this IChatClient client, object? serviceKey = null)

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientMetadata.cs

@@ -11,7 +11,7 @@ public class ChatClientMetadata
     /// <summary>Initializes a new instance of the <see cref="ChatClientMetadata"/> class.</summary>
     /// <param name="providerName">The name of the chat completion provider, if applicable.</param>
     /// <param name="providerUri">The URL for accessing the chat completion provider, if applicable.</param>
-    /// <param name="modelId">The id of the chat completion model used, if applicable.</param>
+    /// <param name="modelId">The ID of the chat completion model used, if applicable.</param>
     public ChatClientMetadata(string? providerName = null, Uri? providerUri = null, string? modelId = null)
     {
         ModelId = modelId;
@@ -25,7 +25,7 @@ public ChatClientMetadata(string? providerName = null, Uri? providerUri = null,
     /// <summary>Gets the URL for accessing the chat completion provider.</summary>
     public Uri? ProviderUri { get; }
 
-    /// <summary>Gets the id of the model used by this chat completion provider.</summary>
-    /// <remarks>This may be null if either the name is unknown or there are multiple possible models associated with this instance.</remarks>
+    /// <summary>Gets the ID of the model used by this chat completion provider.</summary>
+    /// <remarks>This value can be null if either the name is unknown or there are multiple possible models associated with this instance.</remarks>
     public string? ModelId { get; }
 }

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatCompletion.cs

@@ -40,7 +40,7 @@ public IList<ChatMessage> Choices
     /// <summary>Gets the chat completion message.</summary>
     /// <remarks>
     /// If there are multiple choices, this property returns the first choice.
-    /// If <see cref="Choices"/> is empty, this will throw. Use <see cref="Choices"/> to access all choices directly."/>.
+    /// If <see cref="Choices"/> is empty, this property will throw. Use <see cref="Choices"/> to access all choices directly.
     /// </remarks>
     [JsonIgnore]
     public ChatMessage Message

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatFinishReason.cs

@@ -42,9 +42,9 @@ public ChatFinishReason(string value)
     /// <summary>
     /// Compares two instances.
     /// </summary>
-    /// <param name="left">Left argument of the comparison.</param>
-    /// <param name="right">Right argument of the comparison.</param>
-    /// <returns><see langword="true" /> when equal, <see langword="false" /> otherwise.</returns>
+    /// <param name="left">The left argument of the comparison.</param>
+    /// <param name="right">The right argument of the comparison.</param>
+    /// <returns><see langword="true" /> if the two instances are equal; <see langword="false" /> if they aren't equal.</returns>
     public static bool operator ==(ChatFinishReason left, ChatFinishReason right)
     {
         return left.Equals(right);
@@ -53,9 +53,9 @@ public ChatFinishReason(string value)
     /// <summary>
     /// Compares two instances.
     /// </summary>
-    /// <param name="left">Left argument of the comparison.</param>
-    /// <param name="right">Right argument of the comparison.</param>
-    /// <returns><see langword="true" /> when not equal, <see langword="false" /> otherwise.</returns>
+    /// <param name="left">The left argument of the comparison.</param>
+    /// <param name="right">The right argument of the comparison.</param>
+    /// <returns><see langword="true" /> if the two instances aren't equal; <see langword="false" /> if they are equal.</returns>
     public static bool operator !=(ChatFinishReason left, ChatFinishReason right)
     {
         return !(left == right);

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatMessage.cs

@@ -55,7 +55,7 @@ public string? AuthorName
     /// </summary>
     /// <remarks>
     /// If there is no <see cref="TextContent"/> instance in <see cref="Contents" />, then the getter returns <see langword="null" />,
-    /// and the setter will add a new <see cref="TextContent"/> instance with the provided value.
+    /// and the setter adds a new <see cref="TextContent"/> instance with the provided value.
     /// </remarks>
     [JsonIgnore]
     public string? Text

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs

@@ -35,12 +35,12 @@ public class ChatOptions
     /// </summary>
     /// <remarks>
     /// If null, no response format is specified and the client will use its default.
-    /// This may be set to <see cref="ChatResponseFormat.Text"/> to specify that the response should be unstructured text,
+    /// This property can be set to <see cref="ChatResponseFormat.Text"/> to specify that the response should be unstructured text,
     /// to <see cref="ChatResponseFormat.Json"/> to specify that the response should be structured JSON data, or
     /// an instance of <see cref="ChatResponseFormatJson"/> constructed with a specific JSON schema to request that the
     /// response be structured JSON data according to that schema. It is up to the client implementation if or how
     /// to honor the request. If the client implementation doesn't recognize the specific kind of <see cref="ChatResponseFormat"/>,
-    /// it may be ignored.
+    /// it can be ignored.
     /// </remarks>
     public ChatResponseFormat? ResponseFormat { get; set; }
 

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseFormat.cs

@@ -29,7 +29,7 @@ private protected ChatResponseFormat()
 
     /// <summary>Creates a <see cref="ChatResponseFormatJson"/> representing structured JSON data with the specified schema.</summary>
     /// <param name="schema">The JSON schema.</param>
-    /// <param name="schemaName">An optional name of the schema, e.g. if the schema represents a particular class, this could be the name of the class.</param>
+    /// <param name="schemaName">An optional name of the schema. For example, if the schema represents a particular class, this could be the name of the class.</param>
     /// <param name="schemaDescription">An optional description of the schema.</param>
     /// <returns>The <see cref="ChatResponseFormatJson"/> instance.</returns>
     public static ChatResponseFormatJson ForJsonSchema(

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatRole.cs

@@ -32,7 +32,7 @@ namespace Microsoft.Extensions.AI;
     /// Gets the value associated with this <see cref="ChatRole"/>.
     /// </summary>
     /// <remarks>
-    /// The value is what will be serialized into the "role" message field of the Chat Message format.
+    /// The value will be serialized into the "role" message field of the Chat Message format.
     /// </remarks>
     public string Value { get; }
 
@@ -50,9 +50,9 @@ public ChatRole(string value)
     /// Returns a value indicating whether two <see cref="ChatRole"/> instances are equivalent, as determined by a
     /// case-insensitive comparison of their values.
     /// </summary>
-    /// <param name="left"> the first <see cref="ChatRole"/> instance to compare.</param>
-    /// <param name="right"> the second <see cref="ChatRole"/> instance to compare.</param>
-    /// <returns> true if left and right are both null or have equivalent values; false otherwise. </returns>
+    /// <param name="left">The first <see cref="ChatRole"/> instance to compare.</param>
+    /// <param name="right">The second <see cref="ChatRole"/> instance to compare.</param>
+    /// <returns><see langword="true"/> if left and right are both null or have equivalent values; otherwise, <see langword="false"/>.</returns>
     public static bool operator ==(ChatRole left, ChatRole right)
     {
         return left.Equals(right);
@@ -62,9 +62,9 @@ public ChatRole(string value)
     /// Returns a value indicating whether two <see cref="ChatRole"/> instances are not equivalent, as determined by a
     /// case-insensitive comparison of their values.
     /// </summary>
-    /// <param name="left"> the first <see cref="ChatRole"/> instance to compare. </param>
-    /// <param name="right"> the second <see cref="ChatRole"/> instance to compare. </param>
-    /// <returns> false if left and right are both null or have equivalent values; true otherwise. </returns>
+    /// <param name="left">The first <see cref="ChatRole"/> instance to compare. </param>
+    /// <param name="right">The second <see cref="ChatRole"/> instance to compare. </param>
+    /// <returns><see langword="true"/> if left and right have different values; <see langword="false"/> if they have equivalent values or are both null.</returns>
     public static bool operator !=(ChatRole left, ChatRole right)
     {
         return !(left == right);

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatToolMode.cs

@@ -29,14 +29,14 @@ private protected ChatToolMode()
     /// Gets a predefined <see cref="ChatToolMode"/> indicating that tool usage is optional.
     /// </summary>
     /// <remarks>
-    /// <see cref="ChatOptions.Tools"/> may contain zero or more <see cref="AITool"/>
+    /// <see cref="ChatOptions.Tools"/> can contain zero or more <see cref="AITool"/>
     /// instances, and the <see cref="IChatClient"/> is free to invoke zero or more of them.
     /// </remarks>
     public static AutoChatToolMode Auto { get; } = new AutoChatToolMode();
 
     /// <summary>
     /// Gets a predefined <see cref="ChatToolMode"/> indicating that tool usage is required,
-    /// but that any tool may be selected. At least one tool must be provided in <see cref="ChatOptions.Tools"/>.
+    /// but that any tool can be selected. At least one tool must be provided in <see cref="ChatOptions.Tools"/>.
     /// </summary>
     public static RequiredChatToolMode RequireAny { get; } = new(requiredFunctionName: null);
 

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/DelegatingChatClient.cs

@@ -38,7 +38,7 @@ public void Dispose()
     protected IChatClient InnerClient { get; }
 
     /// <summary>Provides a mechanism for releasing unmanaged resources.</summary>
-    /// <param name="disposing">true if being called from <see cref="Dispose()"/>; otherwise, false.</param>
+    /// <param name="disposing"><see langword="true"/> if being called from <see cref="Dispose()"/>; otherwise, <see langword="false"/>.</param>
     protected virtual void Dispose(bool disposing)
     {
         if (disposing)

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/IChatClient.cs

@@ -15,7 +15,7 @@ namespace Microsoft.Extensions.AI;
 /// It is expected that all implementations of <see cref="IChatClient"/> support being used by multiple requests concurrently.
 /// </para>
 /// <para>
-/// However, implementations of <see cref="IChatClient"/> may mutate the arguments supplied to <see cref="CompleteAsync"/> and
+/// However, implementations of <see cref="IChatClient"/> might mutate the arguments supplied to <see cref="CompleteAsync"/> and
 /// <see cref="CompleteStreamingAsync"/>, such as by adding additional messages to the messages list or configuring the options
 /// instance. Thus, consumers of the interface either should avoid using shared instances of these arguments for concurrent
 /// invocations or should otherwise ensure by construction that no <see cref="IChatClient"/> instances are used which might employ
@@ -31,8 +31,8 @@ public interface IChatClient : IDisposable
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>The response messages generated by the client.</returns>
     /// <remarks>
-    /// The returned messages will not have been added to <paramref name="chatMessages"/>. However, any intermediate messages generated implicitly
-    /// by the client, including any messages for roundtrips to the model as part of the implementation of this request, will be included.
+    /// The returned messages aren't added to <paramref name="chatMessages"/>. However, any intermediate messages generated implicitly
+    /// by the client, including any messages for roundtrips to the model as part of the implementation of this request, are included.
     /// </remarks>
     Task<ChatCompletion> CompleteAsync(
         IList<ChatMessage> chatMessages,
@@ -45,8 +45,8 @@ Task<ChatCompletion> CompleteAsync(
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>The response messages generated by the client.</returns>
     /// <remarks>
-    /// The returned messages will not have been added to <paramref name="chatMessages"/>. However, any intermediate messages generated implicitly
-    /// by the client, including any messages for roundtrips to the model as part of the implementation of this request, will be included.
+    /// The returned messages aren't added to <paramref name="chatMessages"/>. However, any intermediate messages generated implicitly
+    /// by the client, including any messages for roundtrips to the model as part of the implementation of this request, are included.
     /// </remarks>
     IAsyncEnumerable<StreamingChatCompletionUpdate> CompleteStreamingAsync(
         IList<ChatMessage> chatMessages,
@@ -58,10 +58,10 @@ IAsyncEnumerable<StreamingChatCompletionUpdate> CompleteStreamingAsync(
 
     /// <summary>Asks the <see cref="IChatClient"/> for an object of the specified type <paramref name="serviceType"/>.</summary>
     /// <param name="serviceType">The type of object being requested.</param>
-    /// <param name="serviceKey">An optional key that may be used to help identify the target service.</param>
+    /// <param name="serviceKey">An optional key that can be used to help identify the target service.</param>
     /// <returns>The found object, otherwise <see langword="null"/>.</returns>
     /// <remarks>
-    /// The purpose of this method is to allow for the retrieval of strongly-typed services that may be provided by the <see cref="IChatClient"/>,
+    /// The purpose of this method is to allow for the retrieval of strongly typed services that might be provided by the <see cref="IChatClient"/>,
     /// including itself or any services it might be wrapping.
     /// </remarks>
     object? GetService(Type serviceType, object? serviceKey = null);

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/RequiredChatToolMode.cs

@@ -8,8 +8,8 @@
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
-/// Indicates that a chat tool must be called. It may optionally nominate a specific function,
-/// or if not, indicates that any of them may be selected.
+/// Represents a mode where a chat tool must be called. This class can optionally nominate a specific function
+/// or indicate that any of the functions can be selected.
 /// </summary>
 [DebuggerDisplay("{DebuggerDisplay,nq}")]
 public sealed class RequiredChatToolMode : ChatToolMode
@@ -18,7 +18,7 @@ public sealed class RequiredChatToolMode : ChatToolMode
     /// Gets the name of a specific <see cref="AIFunction"/> that must be called.
     /// </summary>
     /// <remarks>
-    /// If the value is <see langword="null"/>, any available function may be selected (but at least one must be).
+    /// If the value is <see langword="null"/>, any available function can be selected (but at least one must be).
     /// </remarks>
     public string? RequiredFunctionName { get; }
 
@@ -27,8 +27,8 @@ public sealed class RequiredChatToolMode : ChatToolMode
     /// </summary>
     /// <param name="requiredFunctionName">The name of the function that must be called.</param>
     /// <remarks>
-    /// <paramref name="requiredFunctionName"/> may be <see langword="null"/>. However, it is preferable to use
-    /// <see cref="ChatToolMode.RequireAny"/> when any function may be selected.
+    /// <paramref name="requiredFunctionName"/> can be <see langword="null"/>. However, it's preferable to use
+    /// <see cref="ChatToolMode.RequireAny"/> when any function can be selected.
     /// </remarks>
     public RequiredChatToolMode(string? requiredFunctionName)
     {

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AudioContent.cs

@@ -15,7 +15,7 @@ public class AudioContent : DataContent
     /// <summary>
     /// Initializes a new instance of the <see cref="AudioContent"/> class.
     /// </summary>
-    /// <param name="uri">The URI of the content. This may be a data URI.</param>
+    /// <param name="uri">The URI of the content. This can be a data URI.</param>
     /// <param name="mediaType">The media type (also known as MIME type) represented by the content.</param>
     public AudioContent(Uri uri, string? mediaType = null)
         : base(uri, mediaType)
@@ -25,7 +25,7 @@ public AudioContent(Uri uri, string? mediaType = null)
     /// <summary>
     /// Initializes a new instance of the <see cref="AudioContent"/> class.
     /// </summary>
-    /// <param name="uri">The URI of the content. This may be a data URI.</param>
+    /// <param name="uri">The URI of the content. This can be a data URI.</param>
     /// <param name="mediaType">The media type (also known as MIME type) represented by the content.</param>
     [JsonConstructor]
     public AudioContent([StringSyntax(StringSyntaxAttribute.Uri)] string uri, string? mediaType = null)