From a81f17741cc136462578db25ae2770bbc9a4317a Mon Sep 17 00:00:00 2001
From: Christopher Scott <chriss@microsoft.com>
Date: Thu, 9 Jul 2020 15:16:11 -0500
Subject: [PATCH] Add some docs related to Update-Snippets.ps1 (#13310)

* Add some docs related to Update-Snippets.ps1

* example suggestion

Co-authored-by: Mariana Rios Flores <mariari@microsoft.com>

* add example links

* pr comments

Co-authored-by: Mariana Rios Flores <mariari@microsoft.com>
---
 CONTRIBUTING.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ce552b03282a..f8a603242070 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -151,6 +151,55 @@ Running the script for a project in `sdk\tables` would look like this:
 eng\scripts\Export-API.ps1 tables
 ```
 
+## Updating Sample Snippets
+If the specific client library has sample snippets in markdown format, they were most likely created with help of the `eng\scripts\Update-Snippets.ps1` script.
+Any changes made to the snippet markdown should be done via updating the corresponding C# snippet code and subsequently running the script.
+
+Running the script for a project, for example in `sdk\keyvault`, would look like this: 
+```
+eng\scripts\Update-Snippets.ps1 keyvault
+```
+
+When run, the code regions in the format below (where `<snippetName>` is the name of the snippet):
+```c#
+#region Snippet:<snippetName>
+//some sample code
+string snippet = "some snippet code";
+
+// Lines prefixed with the below comment format will be ignored by the snippet updater.
+/*@@*/ string ignored = "this code will not appear in the snippet markdown";
+
+// Lines prefixed with the below comment format will appear in the snippet markdown, but will remain comments in the C#` code.
+// Note: these comments should only be used for non-critical code as it will not be compiled or refactored as the code changes.
+//@@ snippet = "value that would never pass a test but looks good in a sample!";
+
+#endregion
+```
+ will be mapped to any markdown file with a corresponding code region in the format below where the snippet names match: 
+
+**\`\`\`C# Snippet:\<snippetName>**
+
+**\`\`\`**
+
+See the following example of a [snippet C# file](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/search/Azure.Search.Documents/tests/Samples/HelloWorld.cs) and a [snippet markdown file](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/search/Azure.Search.Documents/samples/Sample01a_HelloWorld.md). 
+Note that snippet names need to be globally unique under a given service directory.
+
+Snippets also can be integrated into XML doc comments. For example:
+```c#
+/// <summary>
+/// Some Property.
+/// </summary>
+/// <example>
+/// This is an example of using a snippet in XML docs.
+/// <code snippet="Snippet:<snippetName>">
+/// // some sample code.
+/// string snippet = "some snippet code";
+/// </code>
+public string SomeProperty { get; set; }
+```
+
+For general information about samples, see the [Samples Guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-samples)
+
 ## API Compatibility Verification
 
 .NET is using the [ApiCompat tool](https://github.com/dotnet/arcade/tree/master/src/Microsoft.DotNet.ApiCompat) to enforce API compatibility between versions. Builds of GA'ed libraries will fail locally and in CI if there are breaking changes.