Docs improvements (#5613)

* docs improvements

* small addition

* Apply suggestions from code review

Co-authored-by: Stephen Toub <[email protected]>

---------

Co-authored-by: Stephen Toub <[email protected]>

Author: gewarren

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);