Fix several documentation bugs (#8861)

* - Fix #7227: Add CONTRIBUTING.md
- Fix #8473: Add service level README
- Fix #8651: Update docstrings

* Update README.md

* Address PR comments

* Add service-level readme to the list of known issues

* Use relative paths

eng/.docsettings.yml

@@ -65,6 +65,7 @@ known_content_issues:
   - ['sdk/servicebus/Microsoft.Azure.ServiceBus/README.md','#5499']
   - ['sdk/eventhub/Microsoft.Azure.EventHubs/README.md','#5499']
   - ['sdk/alertsmanagement/Microsoft.Azure.Management.AlertsManagement/README.md','#5499']
+  - ['sdk/appconfiguration/README.md','azure-sdk-tools/issues/42']
   - ['sdk/appconfiguration/Azure.Data.AppConfiguration/tests/Readme.md','#5499']
   - ['sdk/appconfiguration/Azure.Data.AppConfiguration/samples/README.md','#5499']
   - ['sdk/core/Azure.Core/README.md','#5499']

sdk/appconfiguration/Azure.Data.AppConfiguration/README.md

@@ -212,20 +212,23 @@ Several App Configuration client library samples are available to you in this Gi
 
 ## Contributing
 
-This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
+See the [App Configuration CONTRIBUTING.md][azconfig_contrib] for details on building, testing, and contributing to this library.
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].
 
 When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
 
-This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
+This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][code_of_conduct_faq] or contact [opencode@microsoft.com][email_opencode] with any additional questions or comments.
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Fappconfiguration%2FAzure.Data.AppConfiguration%2FREADME.png)
 
 <!-- LINKS -->
 [azconfig_docs]: https://docs.microsoft.com/azure/azure-app-configuration/
+[azconfig_contrib]: ../CONTRIBUTING.md
 [azconfig_setting_concepts]: https://docs.microsoft.com/en-us/azure/azure-app-configuration/concept-key-value
 [azconfig_asof_snapshot]: https://docs.microsoft.com/en-us/azure/azure-app-configuration/concept-point-time-snapshot
-[source_root]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/appconfiguration/Azure.Data.AppConfiguration
-[source_samples]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/appconfiguration/Azure.Data.AppConfiguration/samples
+[source_root]: ./
+[source_samples]: ./samples
 [reference_docs]: https://azure.github.io/azure-sdk-for-net/appconfiguration.html
 [azconfig_rest]: https://github.com/Azure/AppConfiguration#rest-api-reference
 [azure_cli]: https://docs.microsoft.com/cli/azure
@@ -235,5 +238,9 @@ This project has adopted the Microsoft Open Source Code of Conduct. For more inf
 [label_concept]: https://docs.microsoft.com/en-us/azure/azure-app-configuration/concept-key-value#label-keys
 [nuget]: https://www.nuget.org/
 [package]: https://www.nuget.org/packages/Azure.ApplicationModel.Configuration/
-[samples_readme]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/appconfiguration/Azure.Data.AppConfiguration/samples/README.md
+[samples_readme]: ./samples/README.md
 [moq]: https://github.com/Moq/moq4/
+[cla]: https://cla.microsoft.com
+[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
+[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq/
+[email_opencode]: mailto:opencode@microsoft.com

sdk/appconfiguration/Azure.Data.AppConfiguration/samples/README.md

@@ -66,8 +66,8 @@ In this sample, we give a simple example illustrating how the [Moq](moq) library
 
 [azure_sub]: https://azure.microsoft.com/free/
 [configuration_store]: https://docs.microsoft.com/azure/azure-app-configuration/quickstart-dotnet-core-app#create-an-app-configuration-store
-[root_readme]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/appconfiguration/Azure.Data.AppConfiguration/README.md
+[root_readme]: ../README.md
 [conditional_request_mdn]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests
 [conditional_request_guideline]: https://azure.github.io/azure-sdk/general_design.html#conditional-requests
 [moq]: https://github.com/Moq/moq4/
-[mock_tests]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/appconfiguration/Azure.Data.AppConfiguration/tests/ConfigurationMockTests.cs
+[mock_tests]: ../tests/ConfigurationMockTests.cs

sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient.cs

@@ -392,9 +392,12 @@ public virtual Response DeleteConfigurationSetting(string key, string label = de
             return DeleteConfigurationSetting(key, label, default, cancellationToken);
         }
 
+        /// <summary>
+        /// Delete a <see cref="ConfigurationSetting"/> from the configuration store.
+        /// </summary>
         /// <param name="setting">The <see cref="ConfigurationSetting"/> to delete.</param>
         /// <param name="onlyIfUnchanged">If set to true and the configuration setting exists in the configuration store, delete the setting
-        /// if the passed-in <see cref="ConfigurationSetting"/> is the same version as the one in the configuration store.  The setting versions
+        /// if the passed-in <see cref="ConfigurationSetting"/> is the same version as the one in the configuration store. The setting versions
         /// are the same if their ETag fields match.  If the two settings are different versions, this method will throw an exception to indicate
         /// that the setting in the configuration store was modified since it was last obtained by the client.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
@@ -414,9 +417,12 @@ public virtual async Task<Response> DeleteConfigurationSettingAsync(Configuratio
             return await DeleteConfigurationSettingAsync(setting.Key, setting.Label, requestOptions, cancellationToken).ConfigureAwait(false);
         }
 
+        /// <summary>
+        /// Delete a <see cref="ConfigurationSetting"/> from the configuration store.
+        /// </summary>
         /// <param name="setting">The <see cref="ConfigurationSetting"/> to delete.</param>
         /// <param name="onlyIfUnchanged">If set to true and the configuration setting exists in the configuration store, delete the setting
-        /// if the passed-in <see cref="ConfigurationSetting"/> is the same version as the one in the configuration store.  The setting versions
+        /// if the passed-in <see cref="ConfigurationSetting"/> is the same version as the one in the configuration store. The setting versions
         /// are the same if their ETag fields match.  If the two settings are different versions, this method will throw an exception to indicate
         /// that the setting in the configuration store was modified since it was last obtained by the client.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
@@ -652,7 +658,7 @@ private Response<ConfigurationSetting> GetConfigurationSetting(string key, strin
         }
 
         /// <summary>
-        /// Retrieves one or more <see cref="ConfigurationSetting"/> that satisfy the options set in the <see cref="SettingSelector"/>.
+        /// Retrieves one or more <see cref="ConfigurationSetting"/> entities that match the options specified in the passed-in <see cref="SettingSelector"/>.
         /// </summary>
         /// <param name="selector">Options used to select a set of <see cref="ConfigurationSetting"/> entities from the configuration store.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
@@ -664,7 +670,7 @@ public virtual AsyncPageable<ConfigurationSetting> GetConfigurationSettingsAsync
         }
 
         /// <summary>
-        /// Retrieves one or more <see cref="ConfigurationSetting"/> that satisfies the options of the <see cref="SettingSelector"/>
+        /// Retrieves one or more <see cref="ConfigurationSetting"/> entities that match the options specified in the passed-in <see cref="SettingSelector"/>.
         /// </summary>
         /// <param name="selector">Set of options for selecting <see cref="ConfigurationSetting"/> from the configuration store.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
@@ -699,7 +705,7 @@ public virtual Pageable<ConfigurationSetting> GetRevisions(string key, string la
         }
 
         /// <summary>
-        /// Retrieves the different revisions of a specific <see cref="ConfigurationSetting"/> that satisfies the options of the <see cref="SettingSelector"/>
+        /// Retrieves the different revisions of a specific <see cref="ConfigurationSetting"/> that satisfy the options of the <see cref="SettingSelector"/>.
         /// </summary>
         /// <param name="selector">Set of options for selecting <see cref="ConfigurationSetting"/> from the configuration store.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
@@ -710,7 +716,7 @@ public virtual AsyncPageable<ConfigurationSetting> GetRevisionsAsync(SettingSele
         }
 
         /// <summary>
-        /// Retrieves the different revisions of a specific <see cref="ConfigurationSetting"/> that satisfies the options of the <see cref="SettingSelector"/>
+        /// Retrieves the different revisions of a specific <see cref="ConfigurationSetting"/> that satisfy the options of the <see cref="SettingSelector"/>.
         /// </summary>
         /// <param name="selector">Set of options for selecting <see cref="ConfigurationSetting"/> from the configuration store.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>

sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClientBuilderExtensions.cs

@@ -7,12 +7,12 @@
 namespace Microsoft.Extensions.Azure
 {
     /// <summary>
-    /// Extension methods to add <see cref="ConfigurationClient"/> client to clients builder
+    /// Extension methods to add <see cref="ConfigurationClient"/> client to clients builder.
     /// </summary>
     public static class ConfigurationClientBuilderExtensions
     {
         /// <summary>
-        /// Registers a <see cref="ConfigurationClient"/> instance with the provided <paramref name="connectionString"/>
+        /// Registers a <see cref="ConfigurationClient"/> instance with the provided <paramref name="connectionString"/>.
         /// </summary>
         public static IAzureClientBuilder<ConfigurationClient, ConfigurationClientOptions> AddConfigurationClient<TBuilder>(this TBuilder builder, string connectionString)
             where TBuilder : IAzureClientFactoryBuilder

sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClientOptions.cs

@@ -8,7 +8,7 @@
 namespace Azure.Data.AppConfiguration
 {
     /// <summary>
-    /// Options that allow to configure the management of the request sent to the service
+    /// Options that allow users to configure the requests sent to the App Configuration service.
     /// </summary>
     public class ConfigurationClientOptions : ClientOptions
     {

sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient_private.cs

@@ -193,7 +193,7 @@ private void BuildUriForRevisions(RequestUriBuilder builder, SettingSelector sel
         public override bool Equals(object obj) => base.Equals(obj);
 
         /// <summary>
-        /// Get a hash code for the ConfigurationSetting
+        /// Get a hash code for the ConfigurationSetting.
         /// </summary>
         [EditorBrowsable(EditorBrowsableState.Never)]
         public override int GetHashCode() => base.GetHashCode();

sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationModelFactory.cs

@@ -6,7 +6,7 @@
 namespace Azure.Data.AppConfiguration
 {
     /// <summary>
-    /// Configuration Setting model factory that enables mocking for the App Configuration client library
+    /// Configuration Setting model factory that enables mocking for the App Configuration client library.
     /// </summary>
     public static class ConfigurationModelFactory
     {

sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationSetting.cs

@@ -92,7 +92,7 @@ public IDictionary<string, string> Tags
         public override bool Equals(object obj) => base.Equals(obj);
 
         /// <summary>
-        /// Get a hash code for the ConfigurationSetting
+        /// Get a hash code for the ConfigurationSetting.
         /// </summary>
         [EditorBrowsable(EditorBrowsableState.Never)]
         public override int GetHashCode() => base.GetHashCode();

sdk/appconfiguration/Azure.Data.AppConfiguration/src/SettingSelector.cs

@@ -58,7 +58,7 @@ public SettingSelector() : this(Any, Any) { }
         /// the passed-in keys and labels.
         /// </summary>
         /// <param name="key">A key or key filter indicating which <see cref="ConfigurationSetting"/> entities to select.</param>
-        /// <param name="label">A label or label filter indicating which <see cref="ConfigurationSetting"/> entities to select</param>
+        /// <param name="label">A label or label filter indicating which <see cref="ConfigurationSetting"/> entities to select.</param>
         public SettingSelector(string key, string label = default)
         {
             Keys = new List<string>
@@ -80,7 +80,7 @@ public SettingSelector(string key, string label = default)
         public override bool Equals(object obj) => base.Equals(obj);
 
         /// <summary>
-        /// Get a hash code for the SettingSelector
+        /// Get a hash code for the SettingSelector.
         /// </summary>
         [EditorBrowsable(EditorBrowsableState.Never)]
         public override int GetHashCode() => base.GetHashCode();

sdk/appconfiguration/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+Thank you for your interest in contributing to the Azure App Configuration client library. As an open source effort, we're excited to welcome feedback and contributions from the community. A great first step in sharing your thoughts and understanding where help is needed would be to take a look at the [open issues][open_issues].
+
+Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
+
+## Code of conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][code_of_conduct_faq] or contact [opencode@microsoft.com][email_opencode] with any additional questions or comments.
+
+## Getting started
+
+Before working on a contribution, it would be beneficial to familiarize yourself with the process and guidelines used for the Azure SDKs so that your submission is consistent with the project standards and is ready to be accepted with fewer changes requested. In particular, it is recommended to review:
+
+ - [Azure SDK README][sdk_readme], to learn more about the overall project and processes used.
+ - [Azure SDK Design Guidelines][sdk_design_guidelines], to understand the general guidelines for the Azure SDK across all languages and platforms.
+ - [Azure SDK Contributing Guide][sdk_contributing], for information about how to onboard and contribute to the overall Azure SDK ecosystem.
+
+## Azure SDK Design Guidelines for .NET
+
+These libraries follow the [Azure SDK Design Guidelines for .NET][sdk_design_guidelines_dotnet] and share a number of core features such as HTTP retries, logging, transport protocols, authentication protocols, etc., so that once you learn how to use these features in one client library, you will know how to use them in other client libraries. You can learn about these shared features in the [Azure.Core README][sdk_dotnet_code_readme].
+
+## Public API changes  
+
+To update [`Azure.Data.AppConfiguration.netstandard2.0.cs`][azconfig_api] after making changes to the public API, execute [`./eng/Export-API.ps1`][azconfig_export_api]. 
+
+## Testing
+
+### Frameworks
+
+We use [nUnit 3][nunit] as our testing framework.
+
+[Azure.Core's testing framework][core_tests] is copied into our projects' `/TestFramework` folders by the build _(Please be sure to run all of the unit tests in `../../core/Azure.Core/Azure.Core.All.sln` if you make any changes here)_.
+
+### Sync/Async testing
+
+We expose all of our APIs with both sync and async variants. To avoid writing each of our tests twice, we automatically rewrite our async API calls into their sync equivalents. Simply write your tests using only async APIs and call `InstrumentClient` on any of our client objects. The test framework will wrap the client with a proxy that forwards everything to the sync overloads. Please note that a number of our helpers will automatically instrument clients they provide you. Visual Studio's test runner will show `*TestClass(True)` for the async variants and `*TestClass(False)` for the sync variants.
+
+### Recorded tests
+
+Our testing framework supports recording service requests made during a unit test so they can be replayed later. You can set the `AZURE_TEST_MODE` environment variable to `Playback` to run previously recorded tests, `Record` to record or re-record tests, and `Live` to run tests against the live service.
+
+Properly supporting recorded tests does require a few extra considerations. All random values should be obtained via `this.Recording.Random` since we use the same seed on test playback to ensure our client code generates the same "random" values each time. You can't share any state between tests or rely on ordering because you don't know the order they'll be recorded or replayed. Any sensitive values are redacted via the [`ConfigurationRecordedTestSanitizer`][tests_sanitized].
+
+### Running tests
+
+The easiest way to run the tests is via Visual Studio's unit test runner.
+
+You can also run tests via the command line using `dotnet test`, but that will run tests for all supported platforms simultaneously and intermingle their output. You can run the tests for just one platform with `dotnet test -f netcoreapp2.1` or `dotnet test -f net461`.
+
+The recorded tests are run automatically on every pull request. Live tests are run nightly. Contributors with write access can ask Azure DevOps to run the live tests against a pull request by commenting `/azp run net - appconfiguration - tests` in the PR.
+
+### Samples
+
+Our samples are structured as unit tests so we can easily verify they're up to date and working correctly. These tests aren't recorded and make minimal use of test infrastructure to keep them easy to read.
+
+## Development history
+
+For additional insight and context, the development, release, and issue history for the Azure Event Hubs client library is available in read-only form, in its previous location, the [Azure App Configuration .NET repository]().
+
+<!-- LINKS -->
+[azconfig_root]: ../../sdk/appconfiguration
+[azconfig_api]: ./Azure.Data.AppConfiguration/api/Azure.Data.AppConfiguration.netstandard2.0.cs
+[azconfig_export_api]: ../../eng/Export-API.ps1
+[cla]: https://cla.microsoft.com
+[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
+[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq/
+[core_tests]: ../../sdk/core/Azure.Core/tests/TestFramework
+[nunit]: https://github.com/nunit/docs/wiki
+[open_issues]: https://github.com/Azure/azure-sdk-for-net/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3AClient+label%3AAzConfig
+[sdk_readme]: https://github.com/Azure/azure-sdk
+[sdk_contributing]: ./CONTRIBUTING.md
+[sdk_design_guidelines]: https://azure.github.io/azure-sdk/general_introduction.html
+[sdk_design_guidelines_dotnet]: https://azure.github.io/azure-sdk/dotnet_introduction.html
+[sdk_dotnet_code_readme]: ../../sdk/core/Azure.Core/README.md
+[tests_sanitized]: ./Azure.Data.AppConfiguration/tests/ConfigurationRecordedTestSanitizer.cs
+[email_opencode]: mailto:opencode@microsoft.com