From cad2184e1c1e89a98a2cc6c64778e23657d53dff Mon Sep 17 00:00:00 2001
From: Chet Husk <baronfel@users.noreply.github.com>
Date: Wed, 8 Sep 2021 10:02:09 -0500
Subject: [PATCH] Document the `id` attribute for `example` nodes

---
 tooling/FST-1031-xmldoc-extensions.md | 44 +++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/tooling/FST-1031-xmldoc-extensions.md b/tooling/FST-1031-xmldoc-extensions.md
index 3f5579a5..1e46e738 100644
--- a/tooling/FST-1031-xmldoc-extensions.md
+++ b/tooling/FST-1031-xmldoc-extensions.md
@@ -171,6 +171,50 @@ with a language identifier, but this practice is widespread in popular community
 This attribute often allows for language-specific highlighting or other user experience benefits and so we recommend adding it
 whenever possible.
 
+For example:
+
+```fsharp
+namespace MyLibrary.Core
+
+    open System
+
+    type MyType() = 
+       ///<summary>This member represents the value of P, a nearly-unknowable thing!</summary>
+       ///<example>
+       /// This example shows how to use P to accomplish great things
+       /// <code lang="fsharp">
+       /// let Q = P + 1 // the value of Q is now 1 greater than P, which is amazing
+       /// </code>
+       ///</example>
+       member x.P = 1
+```
+    
+
+## `<example id="<custom id>">`
+
+The `example` XML documentation element is not specified to accept an `id` attribute for purposes of uniquely identifying an
+example, but doing so allows tooling to deep-link to a specific example and so should be encouraged. `id` attributes _should_
+be url-safe by default, and _should_ be unique across a library.
+
+For example:
+
+
+```fsharp
+namespace MyLibrary.Core
+
+    open System
+
+    type MyType() = 
+       ///<summary>This member represents the value of P, a nearly-unknowable thing!</summary>
+       ///<example id="using-p">
+       /// This example shows how to use P to accomplish great things
+       /// <code lang="fsharp">
+       /// let Q = P + 1 // the value of Q is now 1 greater than P, which is amazing
+       /// </code>
+       ///</example>
+       member x.P = 1
+```
+
 ## A note on Cross-references 
 
 Note that F# cross-references using the `<see cref="...">` tag for types, modules, extension members and so on all