Integrate InheritDoc into the build (#17123)

# Summary Adds a reference to [InheritDoc](https://www.nuget.org/packages/SauceControl.InheritDoc/) to replace all `/// <inheritdoc/>` comments with the actual comment content in the documentation xml produced by the build. This is a development-only dependency; it will not be deployed with or referenced by the libraries. Note this produces a lot of warnings for `<inheritdoc />` comments that need to be further refined with a `cref="somBaseType"` attribute. Some examples of this are included in this PR. Example for `Azure.Security.KeyVault.Administration.xml`: **Before** ```xml <member name="P:Azure.Security.KeyVault.Administration.RestoreOperation.Id"> <inheritdoc/> </member> <member name="P:Azure.Security.KeyVault.Administration.RestoreOperation.Value"> <inheritdoc/> </member> <member name="P:Azure.Security.KeyVault.Administration.RestoreOperation.HasCompleted"> <inheritdoc/> </member> <member name="P:Azure.Security.KeyVault.Administration.RestoreOperation.HasValue"> <inheritdoc/> </member> <member name="M:Azure.Security.KeyVault.Administration.RestoreOperation.GetRawResponse"> <inheritdoc/> </member> ``` **After** ```xml <member name="P:Azure.Security.KeyVault.Administration.RestoreOperation.Id"> <summary> Gets an ID representing the operation that can be used to poll for the status of the long-running operation. </summary> </member> <member name="P:Azure.Security.KeyVault.Administration.RestoreOperation.Value"> <summary> Final result of the long-running operation. </summary><remarks> This property can be accessed only after the operation completes successfully (HasValue is true). </remarks> </member> <member name="P:Azure.Security.KeyVault.Administration.RestoreOperation.HasCompleted"> <summary> Returns true if the long-running operation completed. </summary> </member> <member name="P:Azure.Security.KeyVault.Administration.RestoreOperation.HasValue"> <summary> Returns true if the long-running operation completed successfully and has produced final result (accessible by Value property). </summary> </member> <member name="M:Azure.Security.KeyVault.Administration.RestoreOperation.GetRawResponse"> <summary> The last HTTP response received from the server. </summary><remarks> The last response returned from the server during the lifecycle of this instance. An instance of Operation<typeparamref name="T" /> sends requests to a server in UpdateStatusAsync, UpdateStatus, and other methods. Responses from these requests can be accessed using GetRawResponse. </remarks> </member> ```
Azure · Nov 23, 2020 · a3bd0be · a3bd0be
1 parent 4165398
commit a3bd0be
Show file tree

Hide file tree

Showing 9 changed files with 40 additions and 12 deletions.
diff --git a/eng/Directory.Build.Data.props b/eng/Directory.Build.Data.props
@@ -52,6 +52,7 @@
     <UpdateSourceOnBuild Condition="'$(UpdateSourceOnBuild)' == ''">$(AZURE_DEV_UPDATESOURCESONBUILD)</UpdateSourceOnBuild>
     <PowerShellExe Condition="'$(PowerShellExe)' == ''">pwsh</PowerShellExe>
     <CoverletOutputFormat Condition="'$(CoverletOutputFormat)' == '' and '$(CollectCoverage)' == 'true'">cobertura</CoverletOutputFormat>
+    <InheritDocEnabled>true</InheritDocEnabled>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(IsShippingClientLibrary)' == 'true' and '$(TF_BUILD)' == 'true'">
@@ -68,6 +69,12 @@
     </NoWarn>
   </PropertyGroup>
 
+  <PropertyGroup Condition="'$(InheritDocEnabled)' != 'false' and '$(TargetFramework)'=='netstandard2.0'">
+    <NoWarn>
+      $(NoWarn);IDT001<!-- InheritDoc related to malformed XML in netstandard.xml -->
+    </NoWarn>
+  </PropertyGroup>
+
   <!-- CodeAnalysis RuleSet -->
   <PropertyGroup Condition="'$(IsClientLibrary)' == 'true'">
     <CodeAnalysisRuleSet>$(RepoEngPath)\CodeAnalysis.ruleset</CodeAnalysisRuleSet>

diff --git a/eng/Directory.Build.Data.targets b/eng/Directory.Build.Data.targets
@@ -200,6 +200,18 @@
     <Error Condition="'@(PreviewPackageReferences)' != ''" Text="When the project has a release version it shouldn't reference any pre-release libraries. Found the following pre-release references: @(PreviewPackageReferences, ', ')" />
   </Target>
 
+  <!-- InheritDoc-->
+  <ItemGroup Condition="'$(InheritDocEnabled)' != 'false'">
+    <PackageReference Include="SauceControl.InheritDoc" PrivateAssets="all" />
+  </ItemGroup>
+
+  <!-- Fixup netstandard2.malformed docs issue https://github.com/saucecontrol/InheritDoc#bad-netstandard-docs -->
+  <ItemGroup Condition="'$(InheritDocEnabled)' != 'false' and '$(TargetFramework)'=='netstandard2.0'">
+    <PackageDownload Include="NETStandard.Library.Ref" />
+    <InheritDocReference Include="$(NugetPackageRoot)\netstandard.library.ref\2.1.0\ref\netstandard2.1\netstandard.xml" />
+  </ItemGroup>
+
+<!-- Additional PackageReferences should be placed above this PropertyGroup -->
   <PropertyGroup>
     <ApiCompatExcludeAttributeList>$(MSBuildThisFileDirectory)ApiListing.exclude-attributes.txt</ApiCompatExcludeAttributeList>
   </PropertyGroup>

diff --git a/eng/Packages.Data.props b/eng/Packages.Data.props
@@ -196,4 +196,13 @@
     <PackageReference Update="System.Reflection.Emit" Version="4.7.0" />
   </ItemGroup>
 
+  <!-- InheritDoc-->
+  <ItemGroup>
+    <PackageReference Update="SauceControl.InheritDoc" Version="1.1.1" />
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(TargetFramework)'=='netstandard2.0'">
+    <PackageDownload Update="NETStandard.Library.Ref" Version="[2.1.0]" />
+  </ItemGroup>
+
 </Project>
diff --git a/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultPermission.cs b/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultPermission.cs
@@ -6,7 +6,7 @@
 
 namespace Azure.Security.KeyVault.Administration
 {
-    /// <inheritdoc/>
+    /// <summary> Role definition permissions. </summary>
     [CodeGenModel("Permission", Usage = new[] { "input", "output" })]
     public partial class KeyVaultPermission
     {

diff --git a/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultRoleAssignment.cs b/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultRoleAssignment.cs
@@ -5,7 +5,7 @@
 
 namespace Azure.Security.KeyVault.Administration
 {
-    /// <inheritdoc/>>
+    /// <summary> Role Assignments. </summary>
     [CodeGenModel("RoleAssignment")]
     public partial class KeyVaultRoleAssignment
     {

diff --git a/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultRoleAssignmentProperties.cs b/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultRoleAssignmentProperties.cs
@@ -5,7 +5,7 @@
 
 namespace Azure.Security.KeyVault.Administration
 {
-    /// <inheritdoc/>>
+    /// <inheritdoc/>
     [CodeGenModel("RoleAssignmentProperties")]
     internal partial class KeyVaultRoleAssignmentProperties
     { }

diff --git a/...t/Azure.Security.KeyVault.Administration/src/KeyVaultRoleAssignmentPropertiesWithScope.cs b/...t/Azure.Security.KeyVault.Administration/src/KeyVaultRoleAssignmentPropertiesWithScope.cs
@@ -5,7 +5,7 @@
 
 namespace Azure.Security.KeyVault.Administration
 {
-    /// <inheritdoc/>>
+    /// <summary> Role assignment properties with scope. </summary>
     [CodeGenModel("RoleAssignmentPropertiesWithScope")]
     public partial class KeyVaultRoleAssignmentPropertiesWithScope
     { }

diff --git a/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultRoleDefinition.cs b/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultRoleDefinition.cs
@@ -5,7 +5,7 @@
 
 namespace Azure.Security.KeyVault.Administration
 {
-    /// <inheritdoc/>
+    /// <summary> A Key Vault role definition. </summary>
     [CodeGenModel("RoleDefinition", Usage = new[]{"input", "output"})]
     public partial class KeyVaultRoleDefinition
     { }

diff --git a/sdk/tables/Azure.Data.Tables/src/TableEntity.Dictionary.cs b/sdk/tables/Azure.Data.Tables/src/TableEntity.Dictionary.cs
@@ -26,13 +26,13 @@ public object this[string key]
         /// <inheritdoc />
         public ICollection<string> Keys => _properties.Keys;
 
-        /// <inheritdoc />
+        /// <inheritdoc cref="IDictionary{TKey, TValue}.Values" />
         ICollection<object> IDictionary<string, object>.Values => _properties.Values;
 
         /// <inheritdoc />
         public int Count => _properties.Count;
 
-        /// <inheritdoc />
+        /// <inheritdoc cref="ICollection{T}.IsReadOnly" />
         bool ICollection<KeyValuePair<string, object>>.IsReadOnly => _properties.IsReadOnly;
 
         /// <inheritdoc />
@@ -47,19 +47,19 @@ public object this[string key]
         /// <inheritdoc />
         public bool TryGetValue(string key, out object value) => _properties.TryGetValue(key, out value);
 
-        /// <inheritdoc />
+        /// <inheritdoc cref="ICollection{T}.Add(T)" />
         void ICollection<KeyValuePair<string, object>>.Add(KeyValuePair<string, object> item) => SetValue(item.Key, item.Value);
 
         /// <inheritdoc />
-        public void Clear()=> _properties.Clear();
+        public void Clear() => _properties.Clear();
 
-        /// <inheritdoc />
+        /// <inheritdoc cref="ICollection{T}.Contains(T)"/>
         bool ICollection<KeyValuePair<string, object>>.Contains(KeyValuePair<string, object> item) => _properties.Contains(item);
 
-        /// <inheritdoc />
+        /// <inheritdoc cref="ICollection{T}.CopyTo(T[], int)" />
         void ICollection<KeyValuePair<string, object>>.CopyTo(KeyValuePair<string, object>[] array, int arrayIndex) => _properties.CopyTo(array, arrayIndex);
 
-        /// <inheritdoc />
+        /// <inheritdoc cref="ICollection{T}.Remove(T)" />
         bool ICollection<KeyValuePair<string, object>>.Remove(KeyValuePair<string, object> item) => _properties.Remove(item);
 
         /// <inheritdoc />