Doc improvements (#6794)

* doc improvements

* Apply suggestions from code review

---------

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

Author: gewarren

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

@@ -22,7 +22,7 @@ public CitationAnnotation()
     /// Gets or sets the title or name of the source.
     /// </summary>
     /// <remarks>
-    /// This could be the title of a document, a title from a web page, a name of a file, or similarly descriptive text.
+    /// This value could be the title of a document, the title from a web page, the name of a file, or similarly descriptive text.
     /// </remarks>
     public string? Title { get; set; }
 
@@ -34,7 +34,7 @@ public CitationAnnotation()
     /// <summary>Gets or sets a source identifier associated with the annotation.</summary>
     /// <remarks>
     /// This is a provider-specific identifier that can be used to reference the source material by
-    /// an ID. This may be a document ID, or a file ID, or some other identifier for the source material
+    /// an ID. This might be a document ID, a file ID, or some other identifier for the source material
     /// that can be used to uniquely identify it with the provider.
     /// </remarks>
     public string? FileId { get; set; }

src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionDeclaration.cs

@@ -11,9 +11,9 @@ namespace Microsoft.Extensions.AI;
 /// <summary>Represents a function that can be described to an AI service.</summary>
 /// <remarks>
 /// <see cref="AIFunctionDeclaration"/> is the base class for <see cref="AIFunction"/>, which
-/// adds the ability to invoke the function. Components may type test <see cref="AITool"/> instances
+/// adds the ability to invoke the function. Components can type test <see cref="AITool"/> instances
 /// for <see cref="AIFunctionDeclaration"/> to determine whether they can be described as functions,
-/// and may type test for <see cref="AIFunction"/> to determine whether they can be invoked.
+/// and can type test for <see cref="AIFunction"/> to determine whether they can be invoked.
 /// </remarks>
 public abstract class AIFunctionDeclaration : AITool
 {
@@ -36,7 +36,7 @@ protected AIFunctionDeclaration()
     ///   "properties": {
     ///     "a" : { "type": "number" },
     ///     "b" : { "type": "number", "default": 1 }
-    ///   }, 
+    ///   },
     ///   "required" : ["a"]
     /// }
     /// </code>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionFactory.cs

@@ -40,8 +40,8 @@ private protected HostedMcpServerToolApprovalMode()
     /// <summary>
     /// Instantiates a <see cref="HostedMcpServerToolApprovalMode"/> that specifies approval behavior for individual tool names.
     /// </summary>
-    /// <param name="alwaysRequireApprovalToolNames">The list of tools names that always require approval.</param>
-    /// <param name="neverRequireApprovalToolNames">The list of tools names that never require approval.</param>
+    /// <param name="alwaysRequireApprovalToolNames">The list of tool names that always require approval.</param>
+    /// <param name="neverRequireApprovalToolNames">The list of tool names that never require approval.</param>
     /// <returns>An instance of <see cref="HostedMcpServerToolRequireSpecificApprovalMode"/> for the specified tool names.</returns>
     public static HostedMcpServerToolRequireSpecificApprovalMode RequireSpecific(IList<string>? alwaysRequireApprovalToolNames, IList<string>? neverRequireApprovalToolNames)
         => new(alwaysRequireApprovalToolNames, neverRequireApprovalToolNames);

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

@@ -21,7 +21,7 @@ public class ImageGenerationOptions
     /// Gets or sets the size of the generated image.
     /// </summary>
     /// <remarks>
-    /// If a provider only supports fixed sizes the closest supported size will be used.
+    /// If a provider only supports fixed sizes, the closest supported size is used.
     /// </remarks>
     public Size? ImageSize { get; set; }
 
@@ -39,16 +39,16 @@ public class ImageGenerationOptions
     /// Gets or sets a callback responsible for creating the raw representation of the image generation options from an underlying implementation.
     /// </summary>
     /// <remarks>
-    /// The underlying <see cref="IImageGenerator" /> implementation may have its own representation of options.
+    /// The underlying <see cref="IImageGenerator" /> implementation can have its own representation of options.
     /// When <see cref="IImageGenerator.GenerateAsync" /> is invoked with an <see cref="ImageGenerationOptions" />,
-    /// that implementation may convert the provided options into its own representation in order to use it while performing
+    /// that implementation can convert the provided options into its own representation in order to use it while performing
     /// the operation. For situations where a consumer knows  which concrete <see cref="IImageGenerator" /> is being used
-    /// and how it represents options, a new instance of that implementation-specific options type may be returned by this
-    /// callback, for the <see cref="IImageGenerator" />implementation to use instead of creating a new instance.
-    /// Such implementations may mutate the supplied options instance further based on other settings supplied on this
+    /// and how it represents options, a new instance of that implementation-specific options type can be returned by this
+    /// callback for the <see cref="IImageGenerator" /> implementation to use instead of creating a new instance.
+    /// Such implementations might mutate the supplied options instance further based on other settings supplied on this
     /// <see cref="ImageGenerationOptions" /> instance or from other inputs, therefore, it is <b>strongly recommended</b> to not
     /// return shared instances and instead make the callback return a new instance on each call.
-    /// This is typically used to set an implementation-specific setting that isn't otherwise exposed from the strongly-typed
+    /// This is typically used to set an implementation-specific setting that isn't otherwise exposed from the strongly typed
     /// properties on <see cref="ImageGenerationOptions" />.
     /// </remarks>
     [JsonIgnore]
@@ -81,7 +81,7 @@ public virtual ImageGenerationOptions Clone()
 /// Represents the requested response format of the generated image.
 /// </summary>
 /// <remarks>
-/// Not all implementations support all response formats and this value may be ignored by the implementation if not supported.
+/// Not all implementations support all response formats and this value might be ignored by the implementation if not supported.
 /// </remarks>
 [Experimental("MEAI001")]
 public enum ImageGenerationResponseFormat

src/Libraries/Microsoft.Extensions.AI.Abstractions/Image/ImageGenerationOptions.cs

@@ -39,10 +39,12 @@ public ImageGenerationResponse(IList<AIContent>? contents)
     public object? RawRepresentation { get; set; }
 
     /// <summary>
-    /// Gets or sets the generated content items.  Content will typically be DataContent for
-    /// images streamed from the generator or UriContent for remotely hosted images, but may also
-    /// be provider specific content types that represent the generated images.
+    /// Gets or sets the generated content items.
     /// </summary>
+    /// <remarks>
+    /// Content is typically <see cref="DataContent"/> for images streamed from the generator, or <see cref="UriContent"/> for remotely hosted images, but
+    /// can also be provider-specific content types that represent the generated images.
+    /// </remarks>
     [AllowNull]
     public IList<AIContent> Contents
     {

src/Libraries/Microsoft.Extensions.AI.Abstractions/Image/ImageGenerationResponse.cs

@@ -11,7 +11,7 @@
 
 namespace Microsoft.Extensions.AI;
 
-/// <summary>Extensions for <see cref="IImageGenerator"/>.</summary>
+/// <summary>Provides extension methods for <see cref="IImageGenerator"/>.</summary>
 [Experimental("MEAI001")]
 public static class ImageGeneratorExtensions
 {
@@ -102,7 +102,7 @@ public static TService GetRequiredService<TService>(this IImageGenerator generat
     /// <param name="prompt">The prompt to guide the image generation.</param>
     /// <param name="options">The image generation options to configure the request.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <exception cref="ArgumentNullException"><paramref name="generator"/> or <paramref name="prompt"/> are <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="generator"/> or <paramref name="prompt"/> is <see langword="null"/>.</exception>
     /// <returns>The images generated by the generator.</returns>
     public static Task<ImageGenerationResponse> GenerateImagesAsync(
         this IImageGenerator generator,
@@ -124,7 +124,7 @@ public static Task<ImageGenerationResponse> GenerateImagesAsync(
     /// <param name="prompt">The prompt to guide the image editing.</param>
     /// <param name="options">The image generation options to configure the request.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <exception cref="ArgumentNullException"><paramref name="generator"/>, <paramref name="originalImages"/>, or <paramref name="prompt"/> are <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="generator"/>, <paramref name="originalImages"/>, or <paramref name="prompt"/> is <see langword="null"/>.</exception>
     /// <returns>The images generated by the generator.</returns>
     public static Task<ImageGenerationResponse> EditImagesAsync(
         this IImageGenerator generator,
@@ -148,7 +148,7 @@ public static Task<ImageGenerationResponse> EditImagesAsync(
     /// <param name="prompt">The prompt to guide the image generation.</param>
     /// <param name="options">The image generation options to configure the request.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <exception cref="ArgumentNullException"><paramref name="generator"/>, <paramref name="originalImage"/>, or <paramref name="prompt"/> are <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="generator"/>, <paramref name="originalImage"/>, or <paramref name="prompt"/> is <see langword="null"/>.</exception>
     /// <returns>The images generated by the generator.</returns>
     public static Task<ImageGenerationResponse> EditImageAsync(
         this IImageGenerator generator,
@@ -174,7 +174,7 @@ public static Task<ImageGenerationResponse> EditImageAsync(
     /// <param name="options">The image generation options to configure the request.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <exception cref="ArgumentNullException">
-    /// <paramref name="generator"/>, <paramref name="fileName"/>, or <paramref name="prompt"/> are <see langword="null"/>.
+    /// <paramref name="generator"/>, <paramref name="fileName"/>, or <paramref name="prompt"/> is <see langword="null"/>.
     /// </exception>
     /// <returns>The images generated by the generator.</returns>
     public static Task<ImageGenerationResponse> EditImageAsync(

src/Libraries/Microsoft.Extensions.AI.Abstractions/Image/ImageGeneratorExtensions.cs

@@ -19,9 +19,9 @@ public HostedFileSearchTool()
 
     /// <summary>Gets or sets a collection of <see cref="AIContent"/> to be used as input to the file search tool.</summary>
     /// <remarks>
-    /// If no explicit inputs are provided, the service will determine what inputs should be searched. Different services
-    /// support different kinds of inputs, e.g. some may respect <see cref="HostedFileContent"/> using provider-specific file IDs,
-    /// others may support binary data uploaded as part of the request in <see cref="DataContent"/>, while others may support
+    /// If no explicit inputs are provided, the service determines what inputs should be searched. Different services
+    /// support different kinds of inputs, for example, some might respect <see cref="HostedFileContent"/> using provider-specific file IDs,
+    /// others might support binary data uploaded as part of the request in <see cref="DataContent"/>, and others might support
     /// content in a hosted vector store and represented by a <see cref="HostedVectorStoreContent"/>.
     /// </remarks>
     public IList<AIContent>? Inputs { get; set; }

src/Libraries/Microsoft.Extensions.AI.Abstractions/Tools/HostedFileSearchTool.cs

@@ -67,11 +67,11 @@ public HostedMcpServerTool(string serverName, Uri url)
     /// </summary>
     /// <remarks>
     /// <para>
-    /// You can set this property to <see cref="HostedMcpServerToolApprovalMode.AlwaysRequire"/> to require approval for all tool calls, 
+    /// You can set this property to <see cref="HostedMcpServerToolApprovalMode.AlwaysRequire"/> to require approval for all tool calls,
     /// or to <see cref="HostedMcpServerToolApprovalMode.NeverRequire"/> to never require approval.
     /// </para>
     /// <para>
-    /// The default value is <see langword="null"/>, which some providers may treat the same as <see cref="HostedMcpServerToolApprovalMode.AlwaysRequire"/>.
+    /// The default value is <see langword="null"/>, which some providers might treat the same as <see cref="HostedMcpServerToolApprovalMode.AlwaysRequire"/>.
     /// </para>
     /// <para>
     /// The underlying provider is not guaranteed to support or honor the approval mode.

src/Libraries/Microsoft.Extensions.AI.Abstractions/Tools/HostedMcpServerTool.cs

@@ -19,7 +19,7 @@ namespace Microsoft.Extensions.AI;
 /// implementations that enforce vendor-specific restrictions on what constitutes a valid JSON schema for a given function or response format.
 /// </para>
 /// <para>
-/// It is recommended <see cref="IChatClient"/> implementations with schema transformation requirements should create a single static instance of this cache.
+/// It is recommended <see cref="IChatClient"/> implementations with schema transformation requirements create a single static instance of this cache.
 /// </para>
 /// </remarks>
 public sealed class AIJsonSchemaTransformCache
@@ -56,7 +56,7 @@ public AIJsonSchemaTransformCache(AIJsonSchemaTransformOptions transformOptions)
     /// <summary>
     /// Gets or creates a transformed JSON schema for the specified <see cref="AIFunction"/> instance.
     /// </summary>
-    /// <param name="function">The function whose JSON schema we want to transform.</param>
+    /// <param name="function">The function whose JSON schema is to be transformed.</param>
     /// <returns>The transformed JSON schema corresponding to <see cref="TransformOptions"/>.</returns>
     [EditorBrowsable(EditorBrowsableState.Never)] // maintained for binary compat; functionality for AIFunction is satisfied by AIFunctionDeclaration overload
     public JsonElement GetOrCreateTransformedSchema(AIFunction function) =>
@@ -65,7 +65,7 @@ public JsonElement GetOrCreateTransformedSchema(AIFunction function) =>
     /// <summary>
     /// Gets or creates a transformed JSON schema for the specified <see cref="AIFunctionDeclaration"/> instance.
     /// </summary>
-    /// <param name="function">The function whose JSON schema we want to transform.</param>
+    /// <param name="function">The function whose JSON schema is to be transformed.</param>
     /// <returns>The transformed JSON schema corresponding to <see cref="TransformOptions"/>.</returns>
     public JsonElement GetOrCreateTransformedSchema(AIFunctionDeclaration function)
     {
@@ -76,7 +76,7 @@ public JsonElement GetOrCreateTransformedSchema(AIFunctionDeclaration function)
     /// <summary>
     /// Gets or creates a transformed JSON schema for the specified <see cref="ChatResponseFormatJson"/> instance.
     /// </summary>
-    /// <param name="responseFormat">The response format whose JSON schema we want to transform.</param>
+    /// <param name="responseFormat">The response format whose JSON schema is to be transformed.</param>
     /// <returns>The transformed JSON schema corresponding to <see cref="TransformOptions"/>.</returns>
     public JsonElement? GetOrCreateTransformedSchema(ChatResponseFormatJson responseFormat)
     {