[docs] Add basic documentation on using Snippets to DocC documentation

Sources/SwiftDocC/Semantics/Snippets/Snippet.swift

@@ -12,8 +12,25 @@ import Foundation
 public import Markdown
 import SymbolKit
 
+/// Embeds a code example from the project's code snippets.
+///
+/// ```markdown
+/// @Snippet(path: "my-package/Snippets/example-snippet", slice: "setup")
+/// ```
+///
+/// Place the `Snippet` directive to embed a code example from the project's snippet directory.
+/// The path that references the snippet is identified with three parts:
+///
+/// 1. The package name as defined in `Package.swift`
+///
+/// 2. The directory path to the snippet file, starting with "Snippets".
+///
+/// 3. The name of your snippet file without the `.swift` extension
+///
+/// If the snippet had slices annotated within it, an individual slice of the snippet can be referenced with the `slice` option.
+/// Without the option defined, the directive embeds the entire snippet.
 public final class Snippet: Semantic, AutomaticDirectiveConvertible {
-    public static let introducedVersion = "5.6"
+    public static let introducedVersion = "5.7"
     public let originalMarkup: BlockDirective
 
     /// The path components of a symbol link that would be used to resolve a reference to a snippet,
@@ -30,8 +47,6 @@ public final class Snippet: Semantic, AutomaticDirectiveConvertible {
         "slice" : \Snippet._slice,
     ]
 
-    static var hiddenFromDocumentation = true
-
     @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")
     init(originalMarkup: BlockDirective) {
         self.originalMarkup = originalMarkup

Sources/docc/DocCDocumentation.docc/DocC Documentation.md

@@ -25,6 +25,7 @@ DocC syntax — called _documentation markup_ — is a custom variant of Markdow
 - <doc:writing-symbol-documentation-in-your-source-files>
 - <doc:adding-supplemental-content-to-a-documentation-catalog>
 - <doc:linking-to-symbols-and-other-content>
+- <doc:adding-code-snippets-to-your-content>
 - <doc:documenting-api-with-different-language-representations>
 
 ### Structure and Formatting

Sources/docc/DocCDocumentation.docc/DocC.symbols.json

@@ -5246,6 +5246,213 @@
         "Small"
       ]
     },
+    {
+      "accessLevel" : "public",
+      "availability" : [
+        {
+          "domain" : "Swift-DocC",
+          "introduced" : {
+            "major" : 5,
+            "minor" : 7,
+            "patch" : 0
+          }
+        }
+      ],
+      "declarationFragments" : [
+        {
+          "kind" : "typeIdentifier",
+          "spelling" : "@"
+        },
+        {
+          "kind" : "typeIdentifier",
+          "spelling" : "Snippet"
+        },
+        {
+          "kind" : "text",
+          "spelling" : "("
+        },
+        {
+          "kind" : "identifier",
+          "spelling" : "path"
+        },
+        {
+          "kind" : "text",
+          "spelling" : ": "
+        },
+        {
+          "kind" : "typeIdentifier",
+          "spelling" : "String"
+        },
+        {
+          "kind" : "text",
+          "spelling" : ", "
+        },
+        {
+          "kind" : "identifier",
+          "spelling" : "slice"
+        },
+        {
+          "kind" : "text",
+          "spelling" : ": "
+        },
+        {
+          "kind" : "typeIdentifier",
+          "spelling" : "String"
+        },
+        {
+          "kind" : "text",
+          "spelling" : "?"
+        },
+        {
+          "kind" : "text",
+          "spelling" : ")"
+        }
+      ],
+      "docComment" : {
+        "lines" : [
+          {
+            "text" : "Embeds a code example from the project's code snippets."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "```markdown"
+          },
+          {
+            "text" : "@Snippet(path: \"my-package\/Snippets\/example-snippet\", slice: \"setup\")"
+          },
+          {
+            "text" : "```"
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "Place the `Snippet` directive to embed a code example from the project's snippet directory."
+          },
+          {
+            "text" : "The path that references the snippet is identified with three parts:"
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "1. The package name as defined in `Package.swift`"
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "2. The directory path to the snippet file, starting with \"Snippets\"."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "3. The name of your snippet file without the `.swift` extension"
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "If the snippet had slices annotated within it, an individual slice of the snippet can be referenced with the `slice` option."
+          },
+          {
+            "text" : "Without the option defined, the directive embeds the entire snippet."
+          },
+          {
+            "text" : "- Parameters:"
+          },
+          {
+            "text" : "  - path: The path components of a symbol link that would be used to resolve a reference to a snippet,"
+          },
+          {
+            "text" : "     only occurring as a block directive argument."
+          },
+          {
+            "text" : "     **(required)**"
+          },
+          {
+            "text" : "  - slice: An optional named range to limit the lines shown."
+          },
+          {
+            "text" : "     **(optional)**"
+          }
+        ]
+      },
+      "identifier" : {
+        "interfaceLanguage" : "swift",
+        "precise" : "__docc_universal_symbol_reference_$Snippet"
+      },
+      "kind" : {
+        "displayName" : "Directive",
+        "identifier" : "class"
+      },
+      "names" : {
+        "navigator" : [
+          {
+            "kind" : "attribute",
+            "spelling" : "@"
+          },
+          {
+            "kind" : "identifier",
+            "preciseIdentifier" : "__docc_universal_symbol_reference_$Snippet",
+            "spelling" : "Snippet"
+          }
+        ],
+        "subHeading" : [
+          {
+            "kind" : "identifier",
+            "spelling" : "@"
+          },
+          {
+            "kind" : "identifier",
+            "spelling" : "Snippet"
+          },
+          {
+            "kind" : "text",
+            "spelling" : "("
+          },
+          {
+            "kind" : "identifier",
+            "spelling" : "path"
+          },
+          {
+            "kind" : "text",
+            "spelling" : ": "
+          },
+          {
+            "kind" : "typeIdentifier",
+            "spelling" : "String"
+          },
+          {
+            "kind" : "text",
+            "spelling" : ", "
+          },
+          {
+            "kind" : "identifier",
+            "spelling" : "slice"
+          },
+          {
+            "kind" : "text",
+            "spelling" : ": "
+          },
+          {
+            "kind" : "typeIdentifier",
+            "spelling" : "String"
+          },
+          {
+            "kind" : "text",
+            "spelling" : ")"
+          }
+        ],
+        "title" : "Snippet"
+      },
+      "pathComponents" : [
+        "Snippet"
+      ]
+    },
     {
       "accessLevel" : "public",
       "availability" : [