Emit multi-language symbol data

Emits multi-language symbol data to render JSON.

rdar://82967644

Author: franklinsch

Sources/SwiftDocC/Infrastructure/Communication/Foundation/AnyCodable.swift

@@ -22,7 +22,11 @@ public struct AnyCodable: Codable, CustomDebugStringConvertible {
 
     public init(from decoder: Decoder) throws {
         let container = try decoder.singleValueContainer()
-        value = try container.decode(JSON.self)
+        if container.decodeNil() {
+            value = JSON.null
+        } else {
+            value = try container.decode(JSON.self)
+        }
     }
 
     public func encode(to encoder: Encoder) throws {

Sources/SwiftDocC/Model/Identifier.swift

@@ -87,7 +87,14 @@ public struct ResolvedTopicReference: Hashable, Codable, Equatable, CustomString
     }
 
     /// The source language for which this topic is relevant.
-    public var sourceLanguage: SourceLanguage
+    public var sourceLanguage: SourceLanguage {
+        // Return Swift by default to maintain backwards-compatibility.
+        get { sourceLanguages.contains(.swift) ? .swift : sourceLanguages.first! }
+        set { sourceLanguages.insert(newValue) }
+    }
+    
+    /// The source languages for which this topic is relevant.
+    public var sourceLanguages: Set<SourceLanguage>
 
     /// The reference cache key
     var cacheKey: String {
@@ -108,7 +115,7 @@ public struct ResolvedTopicReference: Hashable, Codable, Equatable, CustomString
         self.bundleIdentifier = bundleIdentifier
         self.path = urlReadablePath(path)
         self.fragment = fragment.map { urlReadableFragment($0) }
-        self.sourceLanguage = sourceLanguage
+        self.sourceLanguages = [sourceLanguage]
         updateURL()
 
         // Cache the reference
@@ -235,7 +242,21 @@ public struct ResolvedTopicReference: Hashable, Codable, Equatable, CustomString
     public func encode(to encoder: Encoder) throws {
         var container = encoder.container(keyedBy: CodingKeys.self)
         try container.encode(url.absoluteString, forKey: .url)
-        try container.encode(sourceLanguage.id, forKey: .interfaceLanguage)
+        
+        let sourceLanguageIDVariants = SymbolDataVariants<String>(
+            values: Dictionary<SymbolDataVariantsTrait, String>(
+                uniqueKeysWithValues: sourceLanguages.map { language in
+                    (SymbolDataVariantsTrait(interfaceLanguage: language.id), language.id)
+                }
+            )
+        )
+        
+        try container.encodeVariantCollection(
+            // Force-unwrapping because resolved topic references should have at least one source language.
+            VariantCollection<String>(from: sourceLanguageIDVariants)!,
+            forKey: .interfaceLanguage,
+            encoder: encoder
+        )
     }
 
     public var description: String {

Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift

@@ -10,6 +10,7 @@
 
 import Foundation
 import SymbolKit
+import Markdown
 
 public struct RenderReferenceDependencies {
     var topicReferences = [ResolvedTopicReference]()
@@ -57,25 +58,44 @@ public class DocumentationContentRenderer {
     }
 
     /// For symbol nodes, returns the fragments mixin if any.
-    func subHeadingFragments(for node: DocumentationNode) -> [DeclarationRenderSection.Token]? {
-        guard let symbol = (node.semantic as? Symbol),
-            var fragments = symbol.subHeading?
+    func subHeadingFragments(for node: DocumentationNode) -> VariantCollection<[DeclarationRenderSection.Token]?> {
+        guard let symbol = (node.semantic as? Symbol) else {
+            return .init(defaultValue: nil)
+        }
+        
+        return VariantCollection<[DeclarationRenderSection.Token]?>(
+            from: symbol.subHeadingVariants,
+            symbol.titleVariants,
+            symbol.kindVariants
+        ) { _, subHeading, title, kind in
+            var fragments = subHeading
                 .map({ fragment -> DeclarationRenderSection.Token in
                     return DeclarationRenderSection.Token(fragment: fragment, identifier: nil)
-                }) else { return nil }
-        if fragments.last?.text == "\n" { fragments.removeLast() }
-        return Swift.subHeading(for: fragments, symbolTitle: symbol.title, symbolKind: symbol.kind.identifier)
+                })
+            if fragments.last?.text == "\n" { fragments.removeLast() }
+            
+            // TODO: Return an Objective-C subheading for Objective-C symbols (rdar://84195588)
+            return Swift.subHeading(for: fragments, symbolTitle: title, symbolKind: kind.identifier)
+        } ?? .init(defaultValue: nil)
     }
 
     /// For symbol nodes, returns the navigator title if any.
-    func navigatorFragments(for node: DocumentationNode) -> [DeclarationRenderSection.Token]? {
-        guard let symbol = (node.semantic as? Symbol),
-            var fragments = symbol.navigator?
-                .map({ fragment -> DeclarationRenderSection.Token in
-                    return DeclarationRenderSection.Token(fragment: fragment, identifier: nil)
-                }) else { return nil }
-        if fragments.last?.text == "\n" { fragments.removeLast() }
-        return Swift.navigatorTitle(for: fragments, symbolTitle: symbol.title)
+    func navigatorFragments(for node: DocumentationNode) -> VariantCollection<[DeclarationRenderSection.Token]?> {
+        guard let symbol = (node.semantic as? Symbol) else {
+            return .init(defaultValue: nil)
+        }
+        
+        return VariantCollection<[DeclarationRenderSection.Token]?>(
+            from: symbol.navigatorVariants
+        ) { _, navigator in
+            var fragments = navigator.map { fragment -> DeclarationRenderSection.Token in
+                return DeclarationRenderSection.Token(fragment: fragment, identifier: nil)
+            }
+            if fragments.last?.text == "\n" { fragments.removeLast() }
+            
+            // TODO: Return an Objective-C navigator title for Objective-C symbols (rdar://84195588)
+            return Swift.navigatorTitle(for: fragments, symbolTitle: symbol.title)
+        } ?? .init(defaultValue: nil)
     }
 
     /// Returns the given amount of minutes as a string, for example: "1hr 10min".
@@ -223,21 +243,29 @@ public class DocumentationContentRenderer {
     func renderReference(for reference: ResolvedTopicReference, with overridingDocumentationNode: DocumentationNode? = nil, dependencies: inout RenderReferenceDependencies) -> TopicRenderReference {
         let resolver = LinkTitleResolver(context: documentationContext, source: reference.url)
 
-        let title: String
+        let titleVariants: SymbolDataVariants<String>
         let kind: RenderNode.Kind
         var referenceRole: String?
         let node = try? overridingDocumentationNode ?? documentationContext.entity(with: reference)
+        
         if let node = node, let resolvedTitle = resolver.title(for: node) {
-            title = resolvedTitle
+            titleVariants = resolvedTitle
         } else if let anchorSection = documentationContext.nodeAnchorSections[reference] {
             // No need to continue, return a section topic reference
-            return TopicRenderReference(identifier: RenderReferenceIdentifier(reference.absoluteString), title: anchorSection.title, abstract: [], url: urlGenerator.presentationURLForReference(reference, requireRelativeURL: true).absoluteString, kind: .section, estimatedTime: nil)
+            return TopicRenderReference(
+                identifier: RenderReferenceIdentifier(reference.absoluteString),
+                title: anchorSection.title,
+                abstract: [],
+                url: urlGenerator.presentationURLForReference(reference, requireRelativeURL: true).absoluteString,
+                kind: .section,
+                estimatedTime: nil
+            )
         } else if let topicGraphOnlyNode = documentationContext.topicGraph.nodeWithReference(reference) {
             // Some nodes are artificially inserted into the topic graph,
             // try resolving that way as a fallback after looking up `documentationCache`.
-            title = topicGraphOnlyNode.title
+            titleVariants = .init(defaultVariantValue: topicGraphOnlyNode.title)
         } else {
-            title = reference.absoluteString
+            titleVariants = .init(defaultVariantValue: reference.absoluteString)
         }
 
         switch node?.kind {
@@ -273,7 +301,7 @@ public class DocumentationContentRenderer {
         let presentationURL = urlGenerator.presentationURLForReference(reference, requireRelativeURL: true)
 
         var contentCompiler = RenderContentCompiler(context: documentationContext, bundle: bundle, identifier: reference)
-        let abstractContent: [RenderInlineContent]
+        let abstractContent: VariantCollection<[RenderInlineContent]>
 
         var abstractedNode = node
         if kind == .section {
@@ -282,12 +310,28 @@ public class DocumentationContentRenderer {
             abstractedNode = try? documentationContext.entity(with: containerReference)
         }
 
-        if let abstract = (abstractedNode?.semantic as? Abstracted)?.abstract ?? abstractedNode.map({ DocumentationMarkup(markup: $0.markup, parseUpToSection: .abstract) })?.abstractSection?.paragraph,
-            let renderedContent = contentCompiler.visit(abstract).first,
-            case let .paragraph(inlines)? = renderedContent as? RenderBlockContent {
-            abstractContent = inlines
+        func extractAbstract(from paragraph: Paragraph?) -> [RenderInlineContent] {
+            if let abstract = paragraph
+                ?? abstractedNode.map({
+                    DocumentationMarkup(markup: $0.markup, parseUpToSection: .abstract)
+                })?.abstractSection?.paragraph,
+                let renderedContent = contentCompiler.visit(abstract).first,
+                case let .paragraph(inlines)? = renderedContent as? RenderBlockContent
+            {
+                return inlines
+            } else {
+                return []
+            }
+        }
+        
+        if let symbol = (abstractedNode?.semantic as? Symbol) {
+            abstractContent = VariantCollection<[RenderInlineContent]>(
+                from: symbol.abstractVariants
+            ) { _, abstract in
+                extractAbstract(from: abstract)
+            } ?? .init(defaultValue: [])
         } else {
-            abstractContent = []
+            abstractContent = .init(defaultValue: extractAbstract(from: (abstractedNode?.semantic as? Abstracted)?.abstract))
         }
 
         // Collect the reference dependencies.
@@ -300,8 +344,8 @@ public class DocumentationContentRenderer {
 
         var renderReference = TopicRenderReference(
             identifier: .init(referenceURL),
-            titleVariants: .init(defaultValue: title),
-            abstract: abstractContent,
+            titleVariants: VariantCollection<String>(from: titleVariants) ?? .init(defaultValue: ""),
+            abstractVariants: abstractContent,
             url: presentationURL.absoluteString,
             kind: kind,
             required: isRequired,
@@ -310,9 +354,9 @@ public class DocumentationContentRenderer {
         )
 
         // Store the symbol's display name if present in the render reference
-        renderReference.fragments = node.flatMap(subHeadingFragments)
+        renderReference.fragmentsVariants = node.flatMap(subHeadingFragments) ?? .init(defaultValue: [])
         // Store the symbol's navigator title if present in the render reference
-        renderReference.navigatorTitle = node.flatMap(navigatorFragments)
+        renderReference.navigatorTitleVariants = node.flatMap(navigatorFragments) ?? .init(defaultValue: [])
 
         // Omit the navigator title if it's identical to the fragments
         if renderReference.navigatorTitle == renderReference.fragments {

Sources/SwiftDocC/Model/Rendering/LinkTitleResolver.swift

@@ -25,35 +25,39 @@ struct LinkTitleResolver {
     /// Depending on the page type, semantic parsing may be necessary to determine the title of the page.
     ///
     /// - Parameter page: The page for which to resolve the title.
-    /// - Returns: The link title for this page, or `nil` if the page doesn't exist in the context.
-    func title(for page: DocumentationNode) -> String? {
+    /// - Returns: The variants of the link title for this page, or `nil` if the page doesn't exist in the context.
+    func title(for page: DocumentationNode) -> SymbolDataVariants<String>? {
         if let bundle = context.bundle(identifier: page.reference.bundleIdentifier),
            let directive = page.markup.child(at: 0) as? BlockDirective {
 
             var problems = [Problem]()
             switch directive.name {
             case Tutorial.directiveName:
                 if let tutorial = Tutorial(from: directive, source: source, for: bundle, in: context, problems: &problems) {
-                    return tutorial.intro.title
+                    return .init(defaultVariantValue: tutorial.intro.title)
                 }
             case Technology.directiveName:
                 if let overview = Technology(from: directive, source: source, for: bundle, in: context, problems: &problems) {
-                    return overview.name
+                    return .init(defaultVariantValue: overview.name)
                 }
             default: break
             }
         }
 
-        if let symbol = page.symbol {
-            return symbol.names.title
+        if case let .conceptual(name) = page.name {
+            return .init(defaultVariantValue: name)
         }
-
-        if let article = page.semantic as? Article, let title = article.title?.plainText {
-            return title
+        
+        if let symbol = (page.semantic as? Symbol) {
+            return symbol.titleVariants
         }
 
-        if case let .conceptual(name) = page.name {
-            return name
+        if let symbol = page.symbol {
+            return .init(defaultVariantValue: symbol.names.title)
+        }
+        
+        if let article = page.semantic as? Article, let title = article.title?.plainText {
+            return .init(defaultVariantValue: title)
         }
 
         return nil