Enable xml doc comments for our client libraries

As part of enabling this a number of xml doc comments needed to be fixed or
warnings temporarily disabled to get a clean build. Follow-up issues will
be filed for each class of warnings that needed to be disabled.

eng/Directory.Build.Data.props

@@ -107,13 +107,16 @@
     <ImportDefaultReferences>false</ImportDefaultReferences>
     <UseProjectReferenceToAzureCore>true</UseProjectReferenceToAzureCore>
     <LangVersion>preview</LangVersion>
+    <DocumentationFile>$(IntermediateOutputPath)$(TargetFramework)\$(MSBuildProjectName).xml</DocumentationFile>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(IsTestProject)' == 'true' or '$(IsTestSupportProject)' == 'true'">
     <!-- Always fully sign test assemblies since we have a full public/private key -->
     <PublicSign>false</PublicSign>
     <DelaySign>false</DelaySign>
     <AssemblyOriginatorKeyFile>$(MSBuildThisFileDirectory)AzSdkTestLibKey.snk</AssemblyOriginatorKeyFile>
+    <!-- Disable doc comments for test projects -->
+    <DocumentationFile></DocumentationFile>
   </PropertyGroup>
 
   <Import Project="Versioning.props" />

sdk/appconfiguration/Azure.ApplicationModel.Configuration/src/Azure.ApplicationModel.Configuration.csproj

@@ -13,6 +13,9 @@
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
     <NoWarn>$(NoWarn);3021</NoWarn>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+
+    <!-- Disable warning for missing xml doc comments until we can add all the missing ones -->
+    <NoWarn>$(NoWarn);1591</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

sdk/appconfiguration/Azure.ApplicationModel.Configuration/src/ConfigurationClient.cs

@@ -504,6 +504,7 @@ private Request CreateGetRequest(string key, string label, DateTimeOffset accept
         /// Fetches the <see cref="ConfigurationSetting"/> from the configuration store that match the options selected in the <see cref="SettingSelector"/>.
         /// </summary>
         /// <param name="selector">Set of options for selecting settings from the configuration store.</param>
+        /// <param name="pageLink"></param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
         private async Task<PageResponse<ConfigurationSetting>> GetSettingsPageAsync(SettingSelector selector, string pageLink, CancellationToken cancellationToken = default)
         {
@@ -527,6 +528,7 @@ private async Task<PageResponse<ConfigurationSetting>> GetSettingsPageAsync(Sett
         /// Fetches the <see cref="ConfigurationSetting"/> from the configuration store that match the options selected in the <see cref="SettingSelector"/>.
         /// </summary>
         /// <param name="selector">Set of options for selecting settings from the configuration store.</param>
+        /// <param name="pageLink"></param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
         private PageResponse<ConfigurationSetting> GetSettingsPage(SettingSelector selector, string pageLink, CancellationToken cancellationToken = default)
         {
@@ -566,6 +568,7 @@ private Request CreateBatchRequest(SettingSelector selector, string pageLink)
         /// </summary>
         /// <remarks>Revisions are provided in descending order from their respective <see cref="ConfigurationSetting.LastModified"/> date.</remarks>
         /// <param name="selector">Set of options for selecting settings from the configuration store.</param>
+        /// <param name="pageLink"></param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
         private async Task<PageResponse<ConfigurationSetting>> GetRevisionsPageAsync(SettingSelector selector, string pageLink, CancellationToken cancellationToken = default)
         {
@@ -589,6 +592,7 @@ private async Task<PageResponse<ConfigurationSetting>> GetRevisionsPageAsync(Set
         /// </summary>
         /// <remarks>Revisions are provided in descending order from their respective <see cref="ConfigurationSetting.LastModified"/> date.</remarks>
         /// <param name="selector">Set of options for selecting settings from the configuration store.</param>
+        /// <param name="pageLink"></param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
         private PageResponse<ConfigurationSetting> GetRevisionsPage(SettingSelector selector, string pageLink, CancellationToken cancellationToken = default)
         {

sdk/core/Azure.Core.Extensions/src/Azure.Core.Extensions.csproj

@@ -14,10 +14,11 @@
     <!-- Make sure that we don't pull in additional dependencies during build or package -->
     <ImportDefaultReferences>false</ImportDefaultReferences>
 
-    <LangVersion>preview</LangVersion>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <EnableClientSdkAnalyzers>false</EnableClientSdkAnalyzers>
-    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+
+    <!-- Disable warning for missing xml doc comments until we can add all the missing ones -->
+    <NoWarn>$(NoWarn);1591</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

sdk/core/Azure.Core/src/Azure.Core.csproj

@@ -12,6 +12,9 @@
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <EnableClientSdkAnalyzers>false</EnableClientSdkAnalyzers>
+
+    <!-- Disable warning for missing xml doc comments until we can add all the missing ones -->
+    <NoWarn>$(NoWarn);1591</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

sdk/core/Azure.Core/src/Http/HttpRange.cs

@@ -46,6 +46,7 @@ public HttpRange(long? offset = default, long? count = default)
 
         /// <summary>
         /// Converts the specified range to a string.
+        /// </summary>
         /// <returns>String representation of the range.</returns>
         /// <remarks>For more information, see https://docs.microsoft.com/en-us/rest/api/storageservices/specifying-the-range-header-for-file-service-operations. </remarks>
         public override string ToString()

sdk/core/Azure.Core/src/Pipeline/HttpPipelinePolicy.cs

@@ -10,7 +10,7 @@ namespace Azure.Core.Pipeline
     public abstract class HttpPipelinePolicy
     {
         /// <summary>
-        /// Applies the policy to the <see cref="message"/>. Implementers are expected to mutate <see cref="HttpPipelineMessage.Request"/> before calling <see cref="ProcessNextAsync"/> and observe the <see cref="HttpPipelineMessage.Response"/> changes after.
+        /// Applies the policy to the <paramref name="message"/>. Implementers are expected to mutate <see cref="HttpPipelineMessage.Request"/> before calling <see cref="ProcessNextAsync"/> and observe the <see cref="HttpPipelineMessage.Response"/> changes after.
         /// Last policy in the pipeline is expected to set the <see cref="HttpPipelineMessage.Response"/>
         /// </summary>
         /// <param name="message">The <see cref="HttpPipelineMessage"/> this policy would be applied to.</param>
@@ -21,7 +21,7 @@ public abstract class HttpPipelinePolicy
         public abstract void Process(HttpPipelineMessage message, ReadOnlyMemory<HttpPipelinePolicy> pipeline);
 
         /// <summary>
-        /// Invokes the next <see cref="HttpPipelinePolicy"/> in the <see cref="pipeline"/>.
+        /// Invokes the next <see cref="HttpPipelinePolicy"/> in the <paramref name="pipeline"/>.
         /// </summary>
         /// <param name="message">The <see cref="HttpPipelineMessage"/> next policy would be applied to.</param>
         /// <param name="pipeline">The set of <see cref="HttpPipelinePolicy"/> to execute after next one.</param>

sdk/eventhub/Azure.Messaging.EventHubs/samples/Program.cs

@@ -259,7 +259,7 @@ private static IReadOnlyList<IEventHubsSample> LocateSamples() =>
         ///
         private class CommandLineArguments
         {
-            /// <summary>The sequence of characters that prefix a command-line argument./summary>
+            /// <summary>The sequence of characters that prefix a command-line argument.</summary>
             public const string ArgumentPrefix = "--";
 
             /// <summary>The connection string to the Azure Event Hubs namespace for samples.</summary>

sdk/eventhub/Azure.Messaging.EventHubs/src/Azure.Messaging.EventHubs.csproj

@@ -4,7 +4,6 @@
     <VersionPrefix>5.0.0</VersionPrefix>
     <PackageTags>Azure;Event Hubs;EventHubs;.NET;AMQP;IoT</PackageTags>
     <PackageReleaseNotes>https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs/CHANGELOG.md</PackageReleaseNotes>
-    <DocumentationFile>$(OutputPath)$(TargetFramework)\Azure.Messaging.EventHubs.xml</DocumentationFile>
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
     <EnableFxCopAnalyzers>false</EnableFxCopAnalyzers>
   </PropertyGroup>

sdk/keyvault/Azure.Security.KeyVault.Certificates/src/Azure.Security.KeyVault.Certificates.csproj

@@ -13,6 +13,9 @@
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
     <NoWarn>$(NoWarn);3021</NoWarn>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+
+    <!-- Disable warning for missing xml doc comments until we can add all the missing ones -->
+    <NoWarn>$(NoWarn);1591</NoWarn>
   </PropertyGroup>
 
   <!-- Import the Azure.Core project -->

sdk/keyvault/Azure.Security.KeyVault.Keys/src/Azure.Security.KeyVault.Keys.csproj

@@ -12,11 +12,14 @@
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
     <NoWarn>$(NoWarn);3021</NoWarn>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+
+    <!-- Disable warning for missing xml doc comments until we can add all the missing ones -->
+    <NoWarn>$(NoWarn);1591</NoWarn>
   </PropertyGroup>
-  
+
   <!-- Import the Azure.Core project -->
   <Import Project="$(MSBuildThisFileDirectory)..\..\..\core\Azure.Core\src\Azure.Core.props" />
-    
+
   <ItemGroup>
     <PackageReference Include="System.Memory" />
     <PackageReference Include="System.Text.Json" />
@@ -28,5 +31,5 @@
     <Compile Include="$(AzureCoreSharedSources)PageResponse.cs" />
     <Compile Include="$(AzureCoreSharedSources)PageResponseEnumerator.cs" />
   </ItemGroup>
-  
+
 </Project>

sdk/storage/Azure.Storage.Blobs/src/BlobBaseClient.cs

@@ -242,14 +242,14 @@ protected virtual BlobBaseClient WithSnapshotImpl(string snapshot)
             return new BlobBaseClient(builder.ToUri(), this.Pipeline);
         }
 
-        /// <summary>
-        /// Creates a clone of this instance that references a version ID rather than the base blob.
-        /// </summary>
-        /// /// <remarks>
-        /// Pass null or empty string to remove the verion ID returning a URL to the base blob.
-        /// </remarks>
-        /// <param name="versionId">The version ID to use on this blob. An empty string or null indicates to use the base blob.</param>
-        /// <returns>The new <see cref="BlobClient"/> instance referencing the verionId.</returns>
+        ///// <summary>
+        ///// Creates a clone of this instance that references a version ID rather than the base blob.
+        ///// </summary>
+        ///// /// <remarks>
+        ///// Pass null or empty string to remove the verion ID returning a URL to the base blob.
+        ///// </remarks>
+        ///// <param name="versionId">The version ID to use on this blob. An empty string or null indicates to use the base blob.</param>
+        ///// <returns>The new <see cref="BlobClient"/> instance referencing the verionId.</returns>
         //public virtual BlobBaseClient WithVersionId(string versionId) => this.WithVersionIdImpl(versionId);
 
         //protected virtual BlobBaseClient WithVersionIdImpl(string versionId)

sdk/storage/Azure.Storage.Blobs/src/BlobServiceClient.cs

@@ -233,8 +233,8 @@ public virtual IEnumerable<Response<ContainerItem>> GetContainers(
         /// <summary>
         /// The <see cref="GetContainersAsync"/> operation returns a
         /// single segment of containers in the storage account, starting
-        /// from the specified <paramref name="marker"/>.  Use an empty
-        /// <paramref name="marker"/> to start enumeration from the beginning
+        /// from the specified marker.  Use an empty
+        /// marker to start enumeration from the beginning
         /// and the <see cref="ContainersSegment.NextMarker"/> if it's not
         /// empty to make subsequent calls to <see cref="ListContainersSegmentAsync"/>
         /// to continue enumerating the containers segment by segment.
@@ -866,6 +866,7 @@ await this.GetUserDelegationKeyAsync(
         /// Optional <see cref="CancellationToken"/> to propagate
         /// notifications that the operation should be cancelled.
         /// </param>
+        /// <param name="async"/>
         /// <returns>
         /// A <see cref="Task{Response{BlobServiceStatistics}}"/> describing
         /// the service replication statistics.

sdk/storage/Azure.Storage.Blobs/src/BlobUriBuilder.cs

@@ -64,9 +64,9 @@ internal struct BlobUriBuilder : IEquatable<BlobUriBuilder>
         /// </summary>
         public string Snapshot;
 
-        /// <summary>
-        /// VersionId.  Empty string if not present in URI.
-        /// </summary>
+        ///// <summary>
+        ///// VersionId.  Empty string if not present in URI.
+        ///// </summary>
         //public string VersionId;
 
         /// <summary>
@@ -290,7 +290,7 @@ public override int GetHashCode()
         /// <summary>
         /// Check if two BlobUriBuilder instances are equal.
         /// </summary>
-        /// <param name="obj">The instance to compare to.</param>
+        /// <param name="other">The instance to compare to.</param>
         /// <returns>True if they're equal, false otherwise.</returns>
         public bool Equals(BlobUriBuilder other)
             => this.Scheme == other.Scheme

sdk/storage/Azure.Storage.Blobs/src/BlockBlobClient.cs

@@ -263,14 +263,14 @@ protected sealed override BlobBaseClient WithSnapshotImpl(string snapshot)
             return new BlockBlobClient(builder.ToUri(), this.Pipeline);
         }
 
-        /// <summary>
-        /// Creates a new BlockBlobURL object identical to the source but with the specified version ID.
-        /// </summary>
-        /// <remarks>
-        /// Pass null or empty string to remove the snapshot returning a URL to the base blob.
-        /// </remarks>
-        /// <param name="versionId">A string of the version identifier.</param>
-        /// <returns></returns>
+        ///// <summary>
+        ///// Creates a new BlockBlobURL object identical to the source but with the specified version ID.
+        ///// </summary>
+        ///// <remarks>
+        ///// Pass null or empty string to remove the snapshot returning a URL to the base blob.
+        ///// </remarks>
+        ///// <param name="versionId">A string of the version identifier.</param>
+        ///// <returns></returns>
         //public new BlockBlobClient WithVersionId(string versionId) => (BlockBlobUri)this.WithVersionIdImpl(versionId);
 
         //protected sealed override Blobclient WithVersionIdImpl(string versionId)
@@ -514,7 +514,7 @@ internal async Task<Response<BlobContentInfo>> UploadAsync(
         /// 
         /// For more information, see <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/put-block" />.
         /// </summary>
-        /// <param name="base64BlockID">
+        /// <param name="base64BlockId">
         /// A valid Base64 string value that identifies the block. Prior to
         /// encoding, the string must be less than or equal to 64 bytes in
         /// size.
@@ -579,7 +579,7 @@ public virtual Response<BlockInfo> StageBlock(
         /// 
         /// For more information, see <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/put-block" />.
         /// </summary>
-        /// <param name="base64BlockID">
+        /// <param name="base64BlockId">
         /// A valid Base64 string value that identifies the block. Prior to
         /// encoding, the string must be less than or equal to 64 bytes in
         /// size.
@@ -644,7 +644,7 @@ await this.StageBlockAsync(
         /// 
         /// For more information, see <see href="https://docs.microsoft.com/en-us/rest/api/storageservices/put-block" />.
         /// </summary>
-        /// <param name="base64BlockID">
+        /// <param name="base64BlockId">
         /// A valid Base64 string value that identifies the block. Prior to
         /// encoding, the string must be less than or equal to 64 bytes in
         /// size.
@@ -758,11 +758,11 @@ internal async Task<Response<BlockInfo>> StageBlockAsync(
         /// shared access signature. If the source blob is public, no
         /// authentication is required to perform the operation.
         /// </param>
-        /// <param name="base64BlockID">
+        /// <param name="base64BlockId">
         /// A valid Base64 string value that identifies the block. Prior to
         /// encoding, the string must be less than or equal to 64 bytes in
         /// size.  For a given blob, the length of the value specified for
-        /// the <paramref name="base64BlockID"/> parameter must be the same
+        /// the <paramref name="base64BlockId"/> parameter must be the same
         /// size for each block.  Note that the Base64 string must be
         /// URL-encoded.
         /// </param>
@@ -835,11 +835,11 @@ public virtual Response<BlockInfo> StageBlockFromUri(
         /// shared access signature. If the source blob is public, no
         /// authentication is required to perform the operation.
         /// </param>
-        /// <param name="base64BlockID">
+        /// <param name="base64BlockId">
         /// A valid Base64 string value that identifies the block. Prior to
         /// encoding, the string must be less than or equal to 64 bytes in
         /// size.  For a given blob, the length of the value specified for
-        /// the <paramref name="base64BlockID"/> parameter must be the same
+        /// the <paramref name="base64BlockId"/> parameter must be the same
         /// size for each block.  Note that the Base64 string must be
         /// URL-encoded.
         /// </param>
@@ -912,11 +912,11 @@ await this.StageBlockFromUriAsync(
         /// shared access signature. If the source blob is public, no
         /// authentication is required to perform the operation.
         /// </param>
-        /// <param name="base64BlockID">
+        /// <param name="base64BlockId">
         /// A valid Base64 string value that identifies the block. Prior to
         /// encoding, the string must be less than or equal to 64 bytes in
         /// size.  For a given blob, the length of the value specified for
-        /// the <paramref name="base64BlockID"/> parameter must be the same
+        /// the <paramref name="base64BlockId"/> parameter must be the same
         /// size for each block.  Note that the Base64 string must be
         /// URL-encoded.
         /// </param>
@@ -1025,7 +1025,7 @@ private async Task<Response<BlockInfo>> StageBlockFromUriAsync(
         /// 
         /// For more information, see  <see cref="https://docs.microsoft.com/rest/api/storageservices/put-block-list"/>
         /// </summary>
-        /// <param name="base64BlockIDs">
+        /// <param name="base64BlockIds">
         /// Specify the Uncommitted Base64 encoded block IDs to indicate that
         /// the blob service should search only the uncommitted block list for
         /// the named blocks.  If the block is not found in the uncommitted
@@ -1086,7 +1086,7 @@ public virtual Response<BlobContentInfo> CommitBlockList(
         /// 
         /// For more information, see  <see cref="https://docs.microsoft.com/rest/api/storageservices/put-block-list"/>
         /// </summary>
-        /// <param name="base64BlockIDs">
+        /// <param name="base64BlockIds">
         /// Specify the Uncommitted Base64 encoded block IDs to indicate that
         /// the blob service should search only the uncommitted block list for
         /// the named blocks.  If the block is not found in the uncommitted
@@ -1147,7 +1147,7 @@ await this.CommitBlockListAsync(
         /// 
         /// For more information, see  <see cref="https://docs.microsoft.com/rest/api/storageservices/put-block-list"/>
         /// </summary>
-        /// <param name="base64BlockIDs">
+        /// <param name="base64BlockIds">
         /// Specify the Uncommitted Base64 encoded block IDs to indicate that
         /// the blob service should search only the uncommitted block list for
         /// the named blocks.  If the block is not found in the uncommitted