.Net: Update missing documentation (microsoft#2538)

### Motivation and Context

<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->
CA1591 was suppressed, so many files were missing documentation. This
removes that suppression and adds comments. I used
https://github.com/mkarle/sk-autodocs to automatically generate the
documentation.

### Description
- Unsuppressed CA1591 from top-level editorconfig but kept it suppressed
for unit tests
- Ran `dotnet build | Out-File -FilePath .\log.log` to get a log of
missing XML documentation
- Ran ` sk-autodocs --dotnet-build-log log.log` to generate
documentation for the files missing documentation
- Went through each file and (hopefully) corrected any mistakes. The
most common problems were that it would change the namespace to braces
or remove the empty line at the end.

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [ ] The code builds clean without any errors or warnings
- [ ] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [ ] All unit tests pass, and I have added new tests where possible
- [ ] I didn't break anyone 😄

---------

Co-authored-by: Lisa Harrylock <[email protected]>
Co-authored-by: Mark Wallace <[email protected]>

Author: 3 people

.editorconfig

@@ -163,7 +163,6 @@ dotnet_diagnostic.CA1032.severity = none # We're using RCS1194 which seems to co
 dotnet_diagnostic.CA1034.severity = none # Do not nest type. Alternatively, change its accessibility so that it is not externally visible
 dotnet_diagnostic.CA1062.severity = none # Disable null check, C# already does it for us
 dotnet_diagnostic.CA1303.severity = none # Do not pass literals as localized parameters
-dotnet_diagnostic.CS1591.severity = none # Missing XML comment for publicly visible type or member
 dotnet_diagnostic.CA1805.severity = none # Member is explicitly initialized to its default value
 dotnet_diagnostic.CA1822.severity = none # Member does not access instance data and can be marked as static
 dotnet_diagnostic.CA1848.severity = none # For improved performance, use the LoggerMessage delegates

dotnet/samples/ApplicationInsightsExample/Program.cs

@@ -35,6 +35,10 @@ public sealed class Program
     /// </remarks>
     private static LogLevel LogLevel = LogLevel.Information;
 
+    /// <summary>
+    /// The main entry point for the application.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
     public static async Task Main()
     {
         var serviceProvider = GetServiceProvider();

dotnet/samples/KernelSyntaxExamples/KernelSyntaxExamples.csproj

@@ -9,7 +9,7 @@
     <OutputType>Exe</OutputType>
     <IsPackable>false</IsPackable>
     <!-- Suppress: "Declare types in namespaces", "Require ConfigureAwait" -->
-    <NoWarn>CA1050;CA1707;CA2007;VSTHRD111</NoWarn>
+    <NoWarn>CA1050;CA1707;CA2007;VSTHRD111;CS1591</NoWarn>
   </PropertyGroup>
   <ItemGroup>
     <None Remove="appsettings.json" />
@@ -64,4 +64,5 @@
     <EmbeddedResource Include="Resources\30-system-prompt.txt" />
     <EmbeddedResource Include="Resources\30-user-context.txt" />
   </ItemGroup>
+
 </Project>

dotnet/samples/NCalcSkills/LanguageCalculatorSkill.cs

@@ -61,6 +61,10 @@ [End of Examples]
 Question: {{ $input }}
 ";
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="LanguageCalculatorSkill"/> class.
+    /// </summary>
+    /// <param name="kernel">The kernel to be used for creating the semantic function.</param>
     public LanguageCalculatorSkill(IKernel kernel)
     {
         this._mathTranslator = kernel.CreateSemanticFunction(
@@ -73,6 +77,12 @@ public LanguageCalculatorSkill(IKernel kernel)
             topP: 1);
     }
 
+    /// <summary>
+    /// Calculates the result of a non-trivial math expression.
+    /// </summary>
+    /// <param name="input">A valid mathematical expression that could be executed by a calculator capable of more advanced math functions like sine/cosine/floor.</param>
+    /// <param name="context">The context for the skill execution.</param>
+    /// <returns>A <see cref="Task{TResult}"/> representing the result of the asynchronous operation.</returns>
     [SKFunction, SKName("Calculator"), Description("Useful for getting the result of a non-trivial math expression.")]
     public async Task<string> CalculateAsync(
         [Description("A valid mathematical expression that could be executed by a calculator capable of more advanced math functions like sin/cosine/floor.")]

dotnet/samples/NCalcSkills/SimpleCalculatorSkill.cs

@@ -6,14 +6,18 @@
 namespace NCalcSkills;
 
 /// <summary>
-///  Simple calculator skill
+/// Simple calculator skill that evaluates a mathematical expression.
 /// </summary>
 public class SimpleCalculatorSkill
 {
     private readonly ISKFunction _mathTranslator;
 
     private static readonly string[] s_stopSequences = new[] { "Problem:", "Solution:" };
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SimpleCalculatorSkill"/> class.
+    /// </summary>
+    /// <param name="kernel">The kernel used to create the semantic function.</param>
     public SimpleCalculatorSkill(IKernel kernel)
     {
         this._mathTranslator = kernel.CreateSemanticFunction(

dotnet/src/Connectors/Connectors.AI.HuggingFace/HuggingFaceModelResultExtension.cs

@@ -7,13 +7,16 @@
 
 namespace Microsoft.SemanticKernel;
 
+/// <summary>
+/// Provides an extension method for working with Hugging Face model results.
+/// </summary>
 public static class HuggingFaceModelResultExtension
 {
     /// <summary>
-    /// Retrieves a typed <see cref="TextCompletionResponse"/> hugging face result from PromptResult/>.
+    /// Retrieves a typed <see cref="TextCompletionResponse"/> hugging face result from <see cref="ModelResult"/>.
     /// </summary>
-    /// <param name="resultBase">Current context</param>
-    /// <returns>Hugging face result <see cref="TextCompletionResponse"/></returns>
+    /// <param name="resultBase">The <see cref="ModelResult"/> instance to retrieve the hugging face result from.</param>
+    /// <returns>A <see cref="TextCompletionResponse"/> instance containing the hugging face result.</returns>
     public static TextCompletionResponse GetHuggingFaceResult(this ModelResult resultBase)
     {
         return resultBase.GetResult<TextCompletionResponse>();

dotnet/src/Connectors/Connectors.AI.HuggingFace/TextEmbedding/TextEmbeddingResponse.cs

@@ -8,15 +8,18 @@
 namespace Microsoft.SemanticKernel.Connectors.AI.HuggingFace.TextEmbedding;
 
 /// <summary>
-/// HTTP Schema for embedding response.
+/// Represents the response from the Hugging Face text embedding API.
 /// </summary>
 public sealed class TextEmbeddingResponse
 {
     /// <summary>
-    /// Model containing embedding.
+    /// Represents the embedding vector for a given text.
     /// </summary>
     public sealed class EmbeddingVector
     {
+        /// <summary>
+        /// The embedding vector as a ReadOnlyMemory of float values.
+        /// </summary>
         [JsonPropertyName("embedding")]
         [JsonConverter(typeof(ReadOnlyMemoryConverter))]
         public ReadOnlyMemory<float> Embedding { get; set; }

dotnet/src/Connectors/Connectors.AI.Oobabooga/TextCompletion/OobaboogaTextCompletion.cs

@@ -24,6 +24,9 @@ namespace Microsoft.SemanticKernel.Connectors.AI.Oobabooga.TextCompletion;
 /// </summary>
 public sealed class OobaboogaTextCompletion : ITextCompletion
 {
+    /// <summary>
+    /// The URI path for blocking API requests.
+    /// </summary>
     public const string BlockingUriPath = "/api/v1/generate";
     private const string StreamingUriPath = "/api/v1/stream";
 
@@ -41,7 +44,7 @@ public sealed class OobaboogaTextCompletion : ITextCompletion
     private long _lastCallTicks = long.MaxValue;
 
     /// <summary>
-    /// Controls the size of the buffer used to received websocket packets
+    /// Controls the size of the buffer used to receive websocket packets.
     /// </summary>
     public int WebSocketBufferSize { get; set; } = 2048;
 

dotnet/src/Connectors/Connectors.AI.Oobabooga/TextCompletion/TextCompletionStreamingResponse.cs

@@ -5,11 +5,18 @@
 namespace Microsoft.SemanticKernel.Connectors.AI.Oobabooga.TextCompletion;
 
 /// <summary>
-/// HTTP Schema for streaming completion response. Adapted from <see href="https://github.com/oobabooga/text-generation-webui/blob/main/extensions/api/streaming_api.py"/>
+/// Represents the HTTP schema for streaming completion response. Adapted from <see href="https://github.com/oobabooga/text-generation-webui/blob/main/extensions/api/streaming_api.py"/>.
 /// </summary>
 public sealed class TextCompletionStreamingResponse
 {
+    /// <summary>
+    /// Constant string representing the event that is fired when text is received from a websocket.
+    /// </summary>
     public const string ResponseObjectTextStreamEvent = "text_stream";
+
+    /// <summary>
+    /// Constant string representing the event that is fired when streaming from a websocket ends.
+    /// </summary>
     public const string ResponseObjectStreamEndEvent = "stream_end";
 
     /// <summary>

dotnet/src/Connectors/Connectors.AI.OpenAI/AzureSdk/AzureOpenAIClientBase.cs

@@ -11,7 +11,9 @@
 using Microsoft.SemanticKernel.Diagnostics;
 
 namespace Microsoft.SemanticKernel.Connectors.AI.OpenAI.AzureSdk;
-
+/// <summary>
+/// Base class for Azure OpenAI clients.
+/// </summary>
 public abstract class AzureOpenAIClientBase : ClientBase
 {
     /// <summary>
@@ -20,7 +22,7 @@ public abstract class AzureOpenAIClientBase : ClientBase
     private protected override OpenAIClient Client { get; }
 
     /// <summary>
-    /// Creates a new Azure OpenAI client instance using API Key auth
+    /// Initializes a new instance of the <see cref="AzureOpenAIClientBase"/> class using API Key authentication.
     /// </summary>
     /// <param name="modelId">Azure OpenAI model ID or deployment name, see https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource</param>
     /// <param name="endpoint">Azure OpenAI deployment URL, see https://learn.microsoft.com/azure/cognitive-services/openai/quickstart</param>
@@ -50,7 +52,7 @@ private protected AzureOpenAIClientBase(
     }
 
     /// <summary>
-    /// Creates a new Azure OpenAI client instance supporting AAD auth
+    /// Initializes a new instance of the <see cref="AzureOpenAIClientBase"/> class supporting AAD authentication.
     /// </summary>
     /// <param name="modelId">Azure OpenAI model ID or deployment name, see https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource</param>
     /// <param name="endpoint">Azure OpenAI deployment URL, see https://learn.microsoft.com/azure/cognitive-services/openai/quickstart</param>
@@ -79,8 +81,8 @@ private protected AzureOpenAIClientBase(
     }
 
     /// <summary>
-    /// Creates a new Azure OpenAI client instance using the specified OpenAIClient
-    /// Note: instances created this way might not have the  default diagnostics settings,
+    /// Initializes a new instance of the <see cref="AzureOpenAIClientBase"/> class using the specified OpenAIClient.
+    /// Note: instances created this way might not have the default diagnostics settings,
     /// it's up to the caller to configure the client.
     /// </summary>
     /// <param name="modelId">Azure OpenAI model ID or deployment name, see https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource</param>
@@ -101,6 +103,7 @@ private protected AzureOpenAIClientBase(
     /// <summary>
     /// Options used by the Azure OpenAI client, e.g. User Agent.
     /// </summary>
+    /// <returns>An instance of <see cref="OpenAIClientOptions"/>.</returns>
     private static OpenAIClientOptions GetClientOptions()
     {
         return new OpenAIClientOptions

dotnet/src/Connectors/Connectors.AI.OpenAI/AzureSdk/ClientBase.cs

@@ -21,6 +21,9 @@ namespace Microsoft.SemanticKernel.Connectors.AI.OpenAI.AzureSdk;
 
 #pragma warning disable CA2208 // Instantiate argument exceptions correctly
 
+/// <summary>
+/// Base class for AI clients that provides common functionality for interacting with OpenAI services.
+/// </summary>
 public abstract class ClientBase
 {
     private const int MaxResultsPerPrompt = 128;

dotnet/src/Connectors/Connectors.AI.OpenAI/AzureSdk/OpenAIClientBase.cs

@@ -10,6 +10,9 @@
 
 namespace Microsoft.SemanticKernel.Connectors.AI.OpenAI.AzureSdk;
 
+/// <summary>
+/// Base class for OpenAI clients, providing common functionality and properties.
+/// </summary>
 public abstract class OpenAIClientBase : ClientBase
 {
     /// <summary>
@@ -18,11 +21,11 @@ public abstract class OpenAIClientBase : ClientBase
     private protected override OpenAIClient Client { get; }
 
     /// <summary>
-    /// Create an instance of the OpenAI connector
+    /// Initializes a new instance of the <see cref="OpenAIClientBase"/> class.
     /// </summary>
-    /// <param name="modelId">Model name</param>
-    /// <param name="apiKey">OpenAI API Key</param>
-    /// <param name="organization">OpenAI Organization Id (usually optional)</param>
+    /// <param name="modelId">Model name.</param>
+    /// <param name="apiKey">OpenAI API Key.</param>
+    /// <param name="organization">OpenAI Organization Id (usually optional).</param>
     /// <param name="httpClient">Custom <see cref="HttpClient"/> for HTTP requests.</param>
     /// <param name="loggerFactory">The <see cref="ILoggerFactory"/> to use for logging. If null, no logging will be performed.</param>
     private protected OpenAIClientBase(
@@ -52,7 +55,7 @@ private protected OpenAIClientBase(
     }
 
     /// <summary>
-    /// Creates a new OpenAI client instance using the specified OpenAIClient
+    /// Initializes a new instance of the <see cref="OpenAIClientBase"/> class using the specified OpenAIClient.
     /// Note: instances created this way might not have the default diagnostics settings,
     /// it's up to the caller to configure the client.
     /// </summary>
@@ -83,6 +86,7 @@ private protected void LogActionDetails([CallerMemberName] string? callerMemberN
     /// <summary>
     /// Options used by the OpenAI client, e.g. User Agent.
     /// </summary>
+    /// <returns>An instance of <see cref="OpenAIClientOptions"/> with the configured options.</returns>
     private static OpenAIClientOptions GetClientOptions()
     {
         return new OpenAIClientOptions

dotnet/src/Connectors/Connectors.AI.OpenAI/ImageGeneration/OpenAIImageGeneration.cs

@@ -12,7 +12,9 @@
 using Microsoft.SemanticKernel.Text;
 
 namespace Microsoft.SemanticKernel.Connectors.AI.OpenAI.ImageGeneration;
-
+/// <summary>
+/// A class for generating images using OpenAI's API.
+/// </summary>
 public class OpenAIImageGeneration : OpenAIClientBase, IImageGeneration
 {
     /// <summary>
@@ -31,7 +33,7 @@ public class OpenAIImageGeneration : OpenAIClientBase, IImageGeneration
     private readonly string _authorizationHeaderValue;
 
     /// <summary>
-    /// Create a new instance of OpenAI image generation service
+    /// Initializes a new instance of the <see cref="OpenAIImageGeneration"/> class.
     /// </summary>
     /// <param name="apiKey">OpenAI API key, see https://platform.openai.com/account/api-keys</param>
     /// <param name="organization">OpenAI organization id. This is usually optional unless your account belongs to multiple organizations.</param>

dotnet/src/Connectors/Connectors.AI.OpenAI/OpenAIModelResultExtensions.cs

@@ -8,6 +8,9 @@
 
 namespace Microsoft.SemanticKernel;
 
+/// <summary>
+/// Provides extension methods for working with OpenAI model results.
+/// </summary>
 public static class OpenAIModelResultExtension
 {
     /// <summary>

dotnet/src/Connectors/Connectors.AI.OpenAI/Tokenizers/GPT3Tokenizer.cs

@@ -164,16 +164,31 @@ static unsafe int EncodingUtf8GetBytes(ReadOnlySpan<char> chars, Span<byte> byte
         }
     }
 
+    /// <summary>
+    /// Tokenizes the text in the provided StringBuilder.
+    /// </summary>
+    /// <param name="stringBuilder">StringBuilder containing the text to tokenize</param>
+    /// <returns>List of token IDs</returns>
     public static List<int> Encode(StringBuilder? stringBuilder) =>
         stringBuilder is not null
             ? Encode(stringBuilder.ToString())
             : new List<int>();
 
+    /// <summary>
+    /// Tokenizes the text in the provided char array.
+    /// </summary>
+    /// <param name="chars">Char array containing the text to tokenize</param>
+    /// <returns>List of token IDs</returns>
     public static List<int> Encode(char[]? chars) =>
         chars is not null
             ? Encode(new string(chars))
             : new List<int>();
 
+    /// <summary>
+    /// Tokenizes the text in the provided IEnumerable of chars.
+    /// </summary>
+    /// <param name="chars">IEnumerable of chars containing the text to tokenize</param>
+    /// <returns>List of token IDs</returns>
     public static List<int> Encode(IEnumerable<char>? chars) =>
         chars is not null
             ? Encode(string.Concat(chars))