From b1622a0a0b747740839511b1387289bcf1c64b19 Mon Sep 17 00:00:00 2001
From: Ethan Kusters <ekusters@apple.com>
Date: Mon, 9 Jan 2023 17:42:46 -0800
Subject: [PATCH] Adds the `seeAlso` aside
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

“See Also” is a common kind of aside that folks parsing markdown
may wish to consider.

For Swift-DocC specifically, there is a lot of pre-DocC Swift
documentation content that uses this style of callout:

```
- SeeAlso:
```

In order to gracefully transition this content over to Swift-DocC
style asides, we should add support for them.
---
 .../Markdown/Interpretive Nodes/Aside.swift   | 31 ++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/Sources/Markdown/Interpretive Nodes/Aside.swift b/Sources/Markdown/Interpretive Nodes/Aside.swift
index ce829dac..675cbfa1 100644
--- a/Sources/Markdown/Interpretive Nodes/Aside.swift	
+++ b/Sources/Markdown/Interpretive Nodes/Aside.swift	
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -92,6 +92,9 @@ public struct Aside {
         /// A "throws" aside.
         public static let `throws` = Kind(rawValue: "Throws")!
         
+        /// A "seeAlso" aside.
+        public static let seeAlso = Kind(rawValue: "SeeAlso")!
+        
         /// A collection of preconfigured aside kinds.
         public static var allCases: [Aside.Kind] {
             [
@@ -118,9 +121,35 @@ public struct Aside {
                 todo,
                 version,
                 `throws`,
+                seeAlso,
             ]
         }
         
+        /// The heading text to use when rendering this kind of aside.
+        ///
+        /// For multi-word asides this value may differ from the aside's ``rawValue``.
+        /// For example, the ``seeAlso`` aside's `rawValue` is `"SeeAlso"` but its
+        /// `displayName` is `"See Also"`.
+        /// Likewise, ``nonMutatingVariant``'s `rawValue` is
+        /// `"NonMutatingVariant"` and its `displayName` is `"Non-Mutating Variant"`.
+        ///
+        /// For simpler, single-word asides like ``bug``, the `displayName` and `rawValue` will
+        /// be the same.
+        public var displayName: String {
+            switch self {
+            case .seeAlso:
+                return "See Also"
+            case .nonMutatingVariant:
+                return "Non-Mutating Variant"
+            case .mutatingVariant:
+                return "Mutating Variant"
+            case .todo:
+                return "To Do"
+            default:
+                return rawValue
+            }
+        }
+        
         /// The underlying raw string value.
         public var rawValue: String