From a3bd0beb8baead281e3929b15b4b3d3ed6873e94 Mon Sep 17 00:00:00 2001 From: Christopher Scott Date: Mon, 23 Nov 2020 10:47:46 -0600 Subject: [PATCH] Integrate InheritDoc into the build (#17123) # Summary Adds a reference to [InheritDoc](https://www.nuget.org/packages/SauceControl.InheritDoc/) to replace all `/// ` 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 `` 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 ``` **After** ```xml Gets an ID representing the operation that can be used to poll for the status of the long-running operation. Final result of the long-running operation. This property can be accessed only after the operation completes successfully (HasValue is true). Returns true if the long-running operation completed. Returns true if the long-running operation completed successfully and has produced final result (accessible by Value property). The last HTTP response received from the server. The last response returned from the server during the lifecycle of this instance. An instance of Operation sends requests to a server in UpdateStatusAsync, UpdateStatus, and other methods. Responses from these requests can be accessed using GetRawResponse. ``` --- eng/Directory.Build.Data.props | 7 +++++++ eng/Directory.Build.Data.targets | 12 ++++++++++++ eng/Packages.Data.props | 9 +++++++++ .../src/KeyVaultPermission.cs | 2 +- .../src/KeyVaultRoleAssignment.cs | 2 +- .../src/KeyVaultRoleAssignmentProperties.cs | 2 +- .../KeyVaultRoleAssignmentPropertiesWithScope.cs | 2 +- .../src/KeyVaultRoleDefinition.cs | 2 +- .../src/TableEntity.Dictionary.cs | 14 +++++++------- 9 files changed, 40 insertions(+), 12 deletions(-) diff --git a/eng/Directory.Build.Data.props b/eng/Directory.Build.Data.props index 1ef1a2ac1386..3f11af10192f 100644 --- a/eng/Directory.Build.Data.props +++ b/eng/Directory.Build.Data.props @@ -52,6 +52,7 @@ $(AZURE_DEV_UPDATESOURCESONBUILD) pwsh cobertura + true @@ -68,6 +69,12 @@ + + + $(NoWarn);IDT001 + + + $(RepoEngPath)\CodeAnalysis.ruleset diff --git a/eng/Directory.Build.Data.targets b/eng/Directory.Build.Data.targets index 60c77a97f474..315dcc293121 100644 --- a/eng/Directory.Build.Data.targets +++ b/eng/Directory.Build.Data.targets @@ -200,6 +200,18 @@ + + + + + + + + + + + + $(MSBuildThisFileDirectory)ApiListing.exclude-attributes.txt diff --git a/eng/Packages.Data.props b/eng/Packages.Data.props index 7cfaef09ef1b..2a7bf2ae527c 100644 --- a/eng/Packages.Data.props +++ b/eng/Packages.Data.props @@ -196,4 +196,13 @@ + + + + + + + + + diff --git a/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultPermission.cs b/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultPermission.cs index e552e8939a2d..52efe0459c1e 100644 --- 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 { - /// + /// Role definition permissions. [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 index fc22bc34ca04..0a9aeaf568d8 100644 --- 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 { - /// > + /// Role Assignments. [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 index f652c2e54158..dcfe1ca158aa 100644 --- 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 { - /// > + /// [CodeGenModel("RoleAssignmentProperties")] internal partial class KeyVaultRoleAssignmentProperties { } diff --git a/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultRoleAssignmentPropertiesWithScope.cs b/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultRoleAssignmentPropertiesWithScope.cs index 5bbc28949539..1cba7478ebd7 100644 --- a/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultRoleAssignmentPropertiesWithScope.cs +++ b/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultRoleAssignmentPropertiesWithScope.cs @@ -5,7 +5,7 @@ namespace Azure.Security.KeyVault.Administration { - /// > + /// Role assignment properties with scope. [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 index 008a63504e7b..1263f18db38c 100644 --- 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 { - /// + /// A Key Vault role definition. [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 index 36b6109e7652..3fe85d0ab77d 100644 --- 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] /// public ICollection Keys => _properties.Keys; - /// + /// ICollection IDictionary.Values => _properties.Values; /// public int Count => _properties.Count; - /// + /// bool ICollection>.IsReadOnly => _properties.IsReadOnly; /// @@ -47,19 +47,19 @@ public object this[string key] /// public bool TryGetValue(string key, out object value) => _properties.TryGetValue(key, out value); - /// + /// void ICollection>.Add(KeyValuePair item) => SetValue(item.Key, item.Value); /// - public void Clear()=> _properties.Clear(); + public void Clear() => _properties.Clear(); - /// + /// bool ICollection>.Contains(KeyValuePair item) => _properties.Contains(item); - /// + /// void ICollection>.CopyTo(KeyValuePair[] array, int arrayIndex) => _properties.CopyTo(array, arrayIndex); - /// + /// bool ICollection>.Remove(KeyValuePair item) => _properties.Remove(item); ///