Add XML doc comments to types in Azure.Core

eng/CodeAnalysis.ruleset

@@ -190,7 +190,7 @@
         <Rule Id="SA1626"  Action="None" />          <!-- Single-line comments should not use documentation style slashes -->
         <Rule Id="SA1627"  Action="None" />          <!-- Documentation text should not be empty -->
         <Rule Id="SA1628"  Action="None" />          <!-- Documentation text should begin with a capital letter -->
-        <Rule Id="SA1629"  Action="None" />          <!-- Documentation text should end with a period -->
+        <Rule Id="SA1629"  Action="Info" />          <!-- Documentation text should end with a period -->
         <Rule Id="SA1630"  Action="None" />          <!-- Documentation text should contain whitespace -->
         <Rule Id="SA1631"  Action="None" />          <!-- Documentation should meet character percentage -->
         <Rule Id="SA1632"  Action="None" />          <!-- Documentation text should meet minimum character length -->

sdk/core/Azure.Core/src/AccessToken.cs

@@ -5,18 +5,33 @@
 
 namespace Azure.Core
 {
+    /// <summary>
+    /// Represents an Azure service bearer access token with expiry information.
+    /// </summary>
     public struct AccessToken
     {
+        /// <summary>
+        /// Creates a new instance of <see cref="AccessToken"/> using the provided <paramref name="accessToken"/> and <paramref name="expiresOn"/>.
+        /// </summary>
+        /// <param name="accessToken">The bearer access token value.</param>
+        /// <param name="expiresOn">The bearer access token expiry date.</param>
         public AccessToken(string accessToken, DateTimeOffset expiresOn)
         {
             Token = accessToken;
             ExpiresOn = expiresOn;
         }
 
-        public string Token { get; private set; }
+        /// <summary>
+        /// Get the access token value.
+        /// </summary>
+        public string Token { get; }
 
-        public DateTimeOffset ExpiresOn { get; private set; }
+        /// <summary>
+        /// Gets the time when the provided token expires.
+        /// </summary>
+        public DateTimeOffset ExpiresOn { get; }
 
+        /// <inheritdoc />
         public override bool Equals(object? obj)
         {
             if (obj is AccessToken accessToken)
@@ -27,6 +42,7 @@ public override bool Equals(object? obj)
             return false;
         }
 
+        /// <inheritdoc />
         public override int GetHashCode()
         {
             return Token.GetHashCode() ^ ExpiresOn.GetHashCode();

sdk/core/Azure.Core/src/AsyncPageable.cs

@@ -41,7 +41,7 @@ protected AsyncPageable(CancellationToken cancellationToken) =>
 
         /// <summary>
         /// Enumerate the values a <see cref="Page{T}"/> at a time.  This may
-        /// make mutliple service requests.
+        /// make multiple service requests.
         /// </summary>
         /// <param name="continuationToken">
         /// A continuation token indicating where to resume paging or null to
@@ -60,7 +60,7 @@ public abstract IAsyncEnumerable<Page<T>> AsPages(
 
         /// <summary>
         /// Enumerate the values in the collection asynchronously.  This may
-        /// make mutliple service requests.
+        /// make multiple service requests.
         /// </summary>
         /// <param name="cancellationToken">
         /// The <see cref="CancellationToken"/> used for requests made while

sdk/core/Azure.Core/src/AzureExtensions.cs

@@ -7,6 +7,9 @@
 
 namespace Azure
 {
+    /// <summary>
+    /// Extension for various <see cref="Azure"/> types.
+    /// </summary>
     public static class AzureExtensions
     {
         /// <summary>

sdk/core/Azure.Core/src/ClientOptions.cs

@@ -8,26 +8,48 @@
 
 namespace Azure.Core
 {
+    /// <summary>
+    /// Base type for all client option types, exposes various common client options like <see cref="Diagnostics"/>, <see cref="Retry"/>, <see cref="Transport"/>.
+    /// </summary>
     public abstract class ClientOptions
     {
         private HttpPipelineTransport _transport = HttpClientTransport.Shared;
 
+        /// <summary>
+        /// Creates a new instance of <see cref="ClientOptions"/>.
+        /// </summary>
         protected ClientOptions()
         {
             Retry = new RetryOptions();
             Diagnostics = new DiagnosticsOptions();
         }
 
+        /// <summary>
+        /// The <see cref="HttpPipelineTransport"/> to be used for this client. Defaults to an instance of <see cref="HttpClientTransport"/>.
+        /// </summary>
         public HttpPipelineTransport Transport
         {
             get => _transport;
             set => _transport = value ?? throw new ArgumentNullException(nameof(value));
         }
 
+        /// <summary>
+        /// Gets the client diagnostic options.
+        /// </summary>
         public DiagnosticsOptions Diagnostics { get; }
 
+        /// <summary>
+        /// Gets the client retry options.
+        /// </summary>
         public RetryOptions Retry { get; }
 
+        /// <summary>
+        /// Adds an <see cref="HttpPipeline"/> policy into the client pipeline. The position of policy in the pipeline is controlled by <paramref name="position"/> parameter.
+        /// If you want the policy to execute once per client request use <see cref="HttpPipelinePosition.PerCall"/> otherwise use <see cref="HttpPipelinePosition.PerRetry"/>
+        /// to run the policy for every retry. Note that the same instance of <paramref name="policy"/> would be added to all pipelines of client constructed using this <see cref="ClientOptions"/> object.
+        /// </summary>
+        /// <param name="policy">The <see cref="HttpPipelinePolicy"/> instance to be added to the pipeline.</param>
+        /// <param name="position">The position of policy in the pipeline.</param>
         public void AddPolicy(HttpPipelinePolicy policy, HttpPipelinePosition position)
         {
             switch (position)
@@ -47,15 +69,16 @@ public void AddPolicy(HttpPipelinePolicy policy, HttpPipelinePosition position)
 
         internal IList<HttpPipelinePolicy> PerRetryPolicies { get; } = new List<HttpPipelinePolicy>();
 
-        #region nobody wants to see these
+        /// <inheritdoc />
         [EditorBrowsable(EditorBrowsableState.Never)]
         public override bool Equals(object? obj) => base.Equals(obj);
 
+        /// <inheritdoc />
         [EditorBrowsable(EditorBrowsableState.Never)]
         public override int GetHashCode() => base.GetHashCode();
 
+        /// <inheritdoc />
         [EditorBrowsable(EditorBrowsableState.Never)]
         public override string ToString() => base.ToString();
-        #endregion
     }
 }

sdk/core/Azure.Core/src/Cryptography/IKeyEncryptionKey.cs

@@ -8,7 +8,7 @@
 namespace Azure.Core.Cryptography
 {
     /// <summary>
-    /// A key which is used to encrypt, or wrap, another key
+    /// A key which is used to encrypt, or wrap, another key.
     /// </summary>
     public interface IKeyEncryptionKey
     {
@@ -18,39 +18,39 @@ public interface IKeyEncryptionKey
         string KeyId { get; }
 
         /// <summary>
-        /// Encrypts the specified key using the specified algorithm
+        /// Encrypts the specified key using the specified algorithm.
         /// </summary>
-        /// <param name="algorithm">The key wrap algorithm used to encrypt the specified key</param>
-        /// <param name="key">The key to be encrypted</param>
+        /// <param name="algorithm">The key wrap algorithm used to encrypt the specified key.</param>
+        /// <param name="key">The key to be encrypted.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns>The encrypted key bytes</returns>
+        /// <returns>The encrypted key bytes.</returns>
         byte[] WrapKey(string algorithm, ReadOnlyMemory<byte> key, CancellationToken cancellationToken = default);
 
         /// <summary>
-        /// Encrypts the specified key using the specified algorithm
+        /// Encrypts the specified key using the specified algorithm.
         /// </summary>
-        /// <param name="algorithm">The key wrap algorithm used to encrypt the specified key</param>
-        /// <param name="key">The key to be encrypted</param>
+        /// <param name="algorithm">The key wrap algorithm used to encrypt the specified key.</param>
+        /// <param name="key">The key to be encrypted.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns>The encrypted key bytes</returns>
+        /// <returns>The encrypted key bytes.</returns>
         Task<byte[]> WrapKeyAsync(string algorithm, ReadOnlyMemory<byte> key, CancellationToken cancellationToken = default);
 
         /// <summary>
-        /// Decrypts the specified encrpted key using the specified algorithm
+        /// Decrypts the specified encrypted key using the specified algorithm.
         /// </summary>
-        /// <param name="algorithm">The key wrap algorithm which was used to encrypt the specified encrypted key</param>
-        /// <param name="encryptedKey">The encrypted key to be decrypted</param>
+        /// <param name="algorithm">The key wrap algorithm which was used to encrypt the specified encrypted key.</param>
+        /// <param name="encryptedKey">The encrypted key to be decrypted.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns>The decrpted key bytes</returns>
+        /// <returns>The decrypted key bytes.</returns>
         byte[] UnwrapKey(string algorithm, ReadOnlyMemory<byte> encryptedKey, CancellationToken cancellationToken = default);
 
         /// <summary>
-        /// Decrypts the specified encrpted key using the specified algorithm
+        /// Decrypts the specified encrypted key using the specified algorithm.
         /// </summary>
-        /// <param name="algorithm">The key wrap algorithm which was used to encrypt the specified encrypted key</param>
-        /// <param name="encryptedKey">The encrypted key to be decrypted</param>
+        /// <param name="algorithm">The key wrap algorithm which was used to encrypt the specified encrypted key.</param>
+        /// <param name="encryptedKey">The encrypted key to be decrypted.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns>The decrpted key bytes</returns>
+        /// <returns>The decrypted key bytes.</returns>
         Task<byte[]> UnwrapKeyAsync(string algorithm, ReadOnlyMemory<byte> encryptedKey, CancellationToken cancellationToken = default);
     }
 }

sdk/core/Azure.Core/src/Cryptography/IKeyEncryptionKeyResolver.cs

@@ -12,19 +12,19 @@ namespace Azure.Core.Cryptography
     public interface IKeyEncryptionKeyResolver
     {
         /// <summary>
-        /// Retrieves the key encryption key corresponding to the specified keyId
+        /// Retrieves the key encryption key corresponding to the specified keyId.
         /// </summary>
-        /// <param name="keyId">The key idenitifier of the key encryption key to retrieve</param>
+        /// <param name="keyId">The key identifier of the key encryption key to retrieve.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns>The key encryption key corresponding to the specified keyId</returns>
+        /// <returns>The key encryption key corresponding to the specified keyId.</returns>
         IKeyEncryptionKey Resolve(string keyId, CancellationToken cancellationToken = default);
 
         /// <summary>
-        /// Retrieves the key encryption key corresponding to the specified keyId
+        /// Retrieves the key encryption key corresponding to the specified keyId.
         /// </summary>
-        /// <param name="keyId">The key idenitifier of the key encryption key to retrieve</param>
+        /// <param name="keyId">The key identifier of the key encryption key to retrieve.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns>The key encryption key corresponding to the specified keyId</returns>
+        /// <returns>The key encryption key corresponding to the specified keyId.</returns>
         Task<IKeyEncryptionKey> ResolveAsync(string keyId, CancellationToken cancellationToken = default);
     }
 }

sdk/core/Azure.Core/src/Diagnostics/AzureEventSourceListener.cs

@@ -11,11 +11,17 @@
 namespace Azure.Core.Diagnostics
 {
     /// <summary>
-    /// Implementation of <see cref="EventListener"/> that listens to events produces by Azure SDK Client libraries
+    /// Implementation of <see cref="EventListener"/> that listens to events produces by Azure SDK Client libraries.
     /// </summary>
     public class AzureEventSourceListener: EventListener
     {
+        /// <summary>
+        /// The trait name that has to be present on all event sources collected by this listener.
+        /// </summary>
         public const string TraitName = "AzureEventSource";
+        /// <summary>
+        /// The trait value that has to be present on all event sources collected by this listener.
+        /// </summary>
         public const string TraitValue = "true";
 
         private readonly List<EventSource> _eventSources = new List<EventSource>();
@@ -42,6 +48,7 @@ public AzureEventSourceListener(Action<EventWrittenEventArgs, string> log, Event
             _eventSources.Clear();
         }
 
+        /// <inheritdoc />
         protected sealed override void OnEventSourceCreated(EventSource eventSource)
         {
             base.OnEventSourceCreated(eventSource);
@@ -57,13 +64,14 @@ protected sealed override void OnEventSourceCreated(EventSource eventSource)
             }
         }
 
+        /// <inheritdoc />
         protected sealed override void OnEventWritten(EventWrittenEventArgs eventData)
         {
             _log(eventData, EventSourceEventFormatting.Format(eventData));
         }
 
         /// <summary>
-        /// Creates a new instance of <see cref="AzureEventSourceListener"/> that forwards events to <see cref="Console.WriteLine(string)"/>
+        /// Creates a new instance of <see cref="AzureEventSourceListener"/> that forwards events to <see cref="Console.WriteLine(string)"/>.
         /// </summary>
         /// <param name="level">The level of events to enable.</param>
         public static AzureEventSourceListener CreateConsoleLogger(EventLevel level = EventLevel.Informational)
@@ -72,7 +80,7 @@ public static AzureEventSourceListener CreateConsoleLogger(EventLevel level = Ev
         }
 
         /// <summary>
-        /// Creates a new instance of <see cref="AzureEventSourceListener"/> that forwards events to <see cref="Trace.WriteLine(object)"/>
+        /// Creates a new instance of <see cref="AzureEventSourceListener"/> that forwards events to <see cref="Trace.WriteLine(object)"/>.
         /// </summary>
         /// <param name="level">The level of events to enable.</param>
         public static AzureEventSourceListener CreateTraceLogger(EventLevel level = EventLevel.Informational)

sdk/core/Azure.Core/src/DiagnosticsOptions.cs

@@ -3,9 +3,13 @@
 
 using System;
 using System.Collections.Generic;
+using System.Runtime.InteropServices;
 
 namespace Azure.Core
 {
+    /// <summary>
+    /// Exposes client options related to logging, telemetry and distributed tracing.
+    /// </summary>
     public class DiagnosticsOptions
     {
         private const int MaxApplicationIdLength = 24;
@@ -26,10 +30,21 @@ internal DiagnosticsOptions()
             LoggedQueryParameters = new List<string>();
         }
 
+        /// <summary>
+        /// Get or sets value indicating whether HTTP pipeline logging is enabled.
+        /// </summary>
         public bool IsLoggingEnabled { get; set; } = true;
 
+        /// <summary>
+        /// Gets or sets value indicating whether distributed tracing spans are going to be created for this clients methods calls and HTTP calls.
+        /// </summary>
         public bool IsDistributedTracingEnabled { get; set; } = true;
 
+        /// <summary>
+        /// Gets or sets value indicating whether the "User-Agent" header containing <see cref="ApplicationId"/>, client library package name and version, <see cref="RuntimeInformation.FrameworkDescription"/>
+        /// and <see cref="RuntimeInformation.OSDescription"/> should be sent.
+        /// The default value can be controlled process wide by setting <c>AZURE_TELEMETRY_DISABLED</c> to <c>true</c>, <c>false</c>, <c>1</c> or <c>0</c>.
+        /// </summary>
         public bool IsTelemetryEnabled { get; set; }
 
         /// <summary>
@@ -52,6 +67,9 @@ internal DiagnosticsOptions()
         /// </summary>
         public IList<string> LoggedQueryParameters { get; }
 
+        /// <summary>
+        /// Gets or sets the value sent a the first part of "User-Agent" headers for all requests issues by this client. Defaults to <see cref="DefaultApplicationId"/>.
+        /// </summary>
         public string? ApplicationId
         {
             get => _applicationId;
@@ -65,6 +83,9 @@ public string? ApplicationId
             }
         }
 
+        /// <summary>
+        /// Gets or sets the default application id. Default application id would be set on all instances.
+        /// </summary>
         public static string? DefaultApplicationId { get; set; }
 
         private static bool? EnvironmentVariableToBool(string value)