Skip to content

Commit 92ec42a

Browse files
committed
Support legacy - seealso: callout asides
There’s a lot of existing Swift documentation content that uses the legacy `- seealso:` style aside: ``` - SeeAlso: This other content. ``` While Swift-DocC has always supported a number of these legacy asides like: ``` - Experiment: Lorem ipsum. - Tip: Lorem ipsum <!-- etc... --> ``` it doesn’t currently support `SeeAlso` which causes breakage when migrating existing Swift doc comments over to Swift-DocC. This resolves the issue. rdar://55141543
1 parent 8d19295 commit 92ec42a

File tree

3 files changed

+35
-7
lines changed

3 files changed

+35
-7
lines changed

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -295,11 +295,9 @@ public enum RenderBlockContent: Equatable {
295295

296296
/// A type the describes an aside style.
297297
public struct AsideStyle: Codable, Equatable {
298-
private static let specialDisplayNames: [String: String] = [
299-
"nonmutatingvariant": "Non-Mutating Variant",
300-
"mutatingvariant": "Mutating Variant",
301-
"todo": "To Do",
302-
]
298+
private static let knownDisplayNames: [String: String] = Dictionary(
299+
uniqueKeysWithValues: Markdown.Aside.Kind.allCases.map { ($0.rawValue.lowercased(), $0.displayName) }
300+
)
303301

304302
/// Returns a Boolean value indicating whether two aside styles are equal.
305303
///
@@ -317,7 +315,7 @@ public enum RenderBlockContent: Equatable {
317315

318316
/// The heading text to use when rendering this style of aside.
319317
public var displayName: String {
320-
if let value = Self.specialDisplayNames[rawValue.lowercased()] {
318+
if let value = Self.knownDisplayNames[rawValue.lowercased()] {
321319
return value
322320
} else if rawValue.contains(where: \.isUppercase) {
323321
// If any character is upper-cased, assume the content has
@@ -363,7 +361,7 @@ public enum RenderBlockContent: Equatable {
363361
/// Creates an aside style with the specified display name.
364362
/// - Parameter displayName: The heading text to use when rendering this style of aside.
365363
public init(displayName: String) {
366-
self.rawValue = Self.specialDisplayNames.first(where: { $0.value == displayName })?.key ?? displayName
364+
self.rawValue = Self.knownDisplayNames.first(where: { $0.value == displayName })?.key ?? displayName
367365
}
368366

369367
/// Encodes the aside style into the specified encoder.

Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2454,6 +2454,8 @@ Document
24542454
.aside(.init(style: .init(rawValue: "Since"), content: [.paragraph(.init(inlineContent: [.text("The beginning of time.")]))])),
24552455
.aside(.init(style: .init(rawValue: "Todo"), content: [.paragraph(.init(inlineContent: [.text("This needs work.")]))])),
24562456
.aside(.init(style: .init(rawValue: "Version"), content: [.paragraph(.init(inlineContent: [.text("3.1.4")]))])),
2457+
.aside(.init(style: .init(rawValue: "SeeAlso"), content: [.paragraph(.init(inlineContent: [.text("This other thing.")]))])),
2458+
.aside(.init(style: .init(rawValue: "SeeAlso"), content: [.paragraph(.init(inlineContent: [.text("And this other thing.")]))])),
24572459
.aside(.init(style: .init(rawValue: "Throws"), content: [.paragraph(.init(inlineContent: [.text("A serious error.")]))])),
24582460
]
24592461

@@ -2996,6 +2998,10 @@ Document
29962998
"content": [{"type":"paragraph", "inlineContent":[{"type":"text", "text":"This needs work."}]}]},
29972999
{"type":"aside", "style":"note", "name":"Version",
29983000
"content": [{"type":"paragraph", "inlineContent":[{"type":"text", "text":"3.1.4"}]}]},
3001+
{"type":"aside", "style":"note", "name":"See Also",
3002+
"content": [{"type":"paragraph", "inlineContent":[{"type":"text", "text":"This other thing."}]}]},
3003+
{"type":"aside", "style":"note", "name":"See Also",
3004+
"content": [{"type":"paragraph", "inlineContent":[{"type":"text", "text":"And this other thing."}]}]},
29993005
{"type":"aside", "style":"note", "name":"Throws",
30003006
"content": [{"type":"paragraph", "inlineContent":[{"type":"text", "text":"A serious error."}]}]}
30013007
]

Tests/SwiftDocCTests/Test Resources/Asides.symbols.json

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,18 @@
202202
{
203203
"text": ""
204204
},
205+
{
206+
"text": "> seealso: This other thing."
207+
},
208+
{
209+
"text": ""
210+
},
211+
{
212+
"text": "> SeeAlso: And this other thing."
213+
},
214+
{
215+
"text": ""
216+
},
205217
{
206218
"text": "> Throws: A serious error."
207219
}
@@ -421,6 +433,18 @@
421433
{
422434
"text": ""
423435
},
436+
{
437+
"text": "- SeeAlso: This other thing."
438+
},
439+
{
440+
"text": ""
441+
},
442+
{
443+
"text": "- seealso: And this other thing."
444+
},
445+
{
446+
"text": ""
447+
},
424448
{
425449
"text": "- Throws: A serious error."
426450
}

0 commit comments

Comments
 (0)