Add support for variant overrides in Render JSON (#11)

Adds infrastructure support for adding language-specific overrides in Render
JSON. Also, adds support specifying language variants for
`RenderMetadata.title` and `TopicRenderReference.title`.

rdar://82919099

Author: franklinsch

Sources/SwiftDocC/Converter/RenderNode+Coding.swift

@@ -16,39 +16,71 @@ import Foundation
 let jsonFormattingKey = "DOCC_JSON_PRETTYPRINT"
 public let shouldPrettyPrintOutputJSON = NSString(string: ProcessInfo.processInfo.environment[jsonFormattingKey] ?? "NO").boolValue
 
-public extension CodingUserInfoKey {
-    // A user info key to store topic reference cache in `JSONEncoder`.
-    static let renderReferenceCache = CodingUserInfoKey(rawValue: "renderReferenceCache")!
+extension CodingUserInfoKey {
+    /// A user info key to indicate that Render JSON references should not be encoded.
+    static let skipsEncodingReferences = CodingUserInfoKey(rawValue: "skipsEncodingReferences")!
+    
+    /// A user info key that encapsulates variant overrides.
+    ///
+    /// This key is used by encoders to accumulate language-specific variants of documentation in a ``VariantOverrides`` value.
+    static let variantOverrides = CodingUserInfoKey(rawValue: "variantOverrides")!
+}
+
+extension Encoder {
+    /// The variant overrides accumulated as part of the encoding process.
+    var userInfoVariantOverrides: VariantOverrides? {
+        userInfo[.variantOverrides] as? VariantOverrides
+    }
 }
 
 /// A namespace for encoders for render node JSON.
-enum RenderJSONEncoder {
+public enum RenderJSONEncoder {
     /// Creates a new JSON encoder for render node values.
     ///
-    /// - Parameter prettyPrint: If `true`, the encoder formats its output to make it easy to read; if `false`, the output is compact.
+    /// Returns an encoder that's configured to encode ``RenderNode`` values.
+    ///
+    /// > Important: Don't reuse encoders returned by this function to encode multiple render nodes, as the encoder accumulates state during the encoding
+    /// process which should not be shared in other encoding units. Instead, call this API to create a new encoder for each render node you want to encode.
+    ///
+    /// - Parameters:
+    ///     - prettyPrint: If `true`, the encoder formats its output to make it easy to read; if `false`, the output is compact.
+    ///     - emitVariantOverrides: Whether the encoder should emit the top-level ``RenderNode/variantOverrides`` property that holds language-
+    ///     specific documentation data.
     /// - Returns: The new JSON encoder.
-    static func encoder(prettyPrint: Bool) -> JSONEncoder {
+    public static func makeEncoder(
+        prettyPrint: Bool = shouldPrettyPrintOutputJSON,
+        emitVariantOverrides: Bool = true
+    ) -> JSONEncoder {
         let encoder = JSONEncoder()
+        
         if prettyPrint {
             if #available(OSX 10.13, *) {
                 encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
             } else {
                 encoder.outputFormatting = [.prettyPrinted]
             }
         }
+        
+        if emitVariantOverrides {
+            encoder.userInfo[.variantOverrides] = VariantOverrides()
+        }
+        
         return encoder
     }
 }
 
+/// A namespace for decoders for render node JSON.
+public enum RenderJSONDecoder {
+    /// Creates a new JSON decoder for render node values.
+    ///
+    /// - Returns: The new JSON decoder.
+    public static func makeDecoder() -> JSONDecoder {
+        JSONDecoder()
+    }
+}
+
 // This API improves the encoding/decoding to or from JSON with better error messages.
 public extension RenderNode {
-    /// The default decoder for render node JSON.
-    static var defaultJSONDecoder = JSONDecoder()
-    /// The default encoder for render node JSON.
-    static var defaultJSONEncoder = RenderJSONEncoder.encoder(
-        prettyPrint: shouldPrettyPrintOutputJSON
-    )
-
     /// An error that describes failures that may occur while encoding or decoding a render node.
     enum CodingError: DescribedError {
         /// JSON data could not be decoded as a render node value.
@@ -79,7 +111,7 @@ public extension RenderNode {
     ///   - decoder: The object that decodes the JSON data.
     /// - Throws: A ``CodingError`` in case the decoder is unable to find a key or value in the data, the type of a decoded value is wrong, or the data is corrupted.
     /// - Returns: The decoded render node value.
-    static func decode(fromJSON data: Data, with decoder: JSONDecoder = RenderNode.defaultJSONDecoder) throws -> RenderNode {
+    static func decode(fromJSON data: Data, with decoder: JSONDecoder = RenderJSONDecoder.makeDecoder()) throws -> RenderNode {
         do {
             return try decoder.decode(RenderNode.self, from: data)
         } catch {
@@ -105,26 +137,33 @@ public extension RenderNode {
 
     /// Encodes a render node value as JSON data.
     ///
-    /// - Parameter encoder: The object that encodes the render node.
+    /// - Parameters:
+    ///     - encoder: The object that encodes the render node.
+    ///     - renderReferenceCache: A cache for encoded render reference data. When encoding a large number of render nodes, use the same cache instance
+    ///     to avoid encoding the same reference objects repeatedly.
     /// - Throws: A ``CodingError`` in case the encoder couldn't encode the render node.
     /// - Returns: The data for the encoded render node.
-    func encodeToJSON(with encoder: JSONEncoder = RenderNode.defaultJSONEncoder) throws -> Data {
+    func encodeToJSON(
+        with encoder: JSONEncoder = RenderJSONEncoder.makeEncoder(),
+        renderReferenceCache: Synchronized<[String: Data]>? = nil
+    ) throws -> Data {
         do {
             // If there is no topic reference cache, just encode the reference.
             // To skim a little off the duration we first do a quick check if the key is present at all.
-            guard encoder.userInfo.keys.contains(.renderReferenceCache) else {
+            guard let renderReferenceCache = renderReferenceCache else {
                 return try encoder.encode(self)
             }
 
-            // Encode the render node as usual. `RenderNode` will skip encoding the references itself
-            // because the `.renderReferenceCache` key is set.
+            // Since we're using a reference cache, skip encoding the references and encode them separately.
+            encoder.userInfo[.skipsEncodingReferences] = true
             var renderNodeData = try encoder.encode(self)
 
             // Add render references, using the encoder cache.
             TopicRenderReferenceEncoder.addRenderReferences(
                 to: &renderNodeData,
                 references: references,
-                encoder: encoder
+                encoder: encoder,
+                renderReferenceCache: renderReferenceCache
             )
 
             return renderNodeData

Sources/SwiftDocC/Converter/TopicRenderReferenceEncoder.swift

@@ -16,13 +16,14 @@ enum TopicRenderReferenceEncoder {
     ///   - renderNodeData: A render node encoded as JSON data.
     ///   - references: A list of render references.
     ///   - encoder: A `JSONEncoder` to use for the encoding.
-    static func addRenderReferences(to renderNodeData: inout Data,
+    ///   - renderReferenceCache: A cache for encoded render reference data. When encoding a large number of render nodes, use the same cache
+    ///   instance to avoid encoding the same reference objects repeatedly.
+    static func addRenderReferences(
+        to renderNodeData: inout Data,
         references: [String: RenderReference],
-        encoder: JSONEncoder) {
-        
-        guard let referenceCache = encoder.userInfo[.renderReferenceCache] as? Synchronized<[String: Data]> else {
-            fatalError("An unexpected value passed via the .renderReferenceCache key.")
-        }
+        encoder: JSONEncoder,
+        renderReferenceCache referenceCache: Synchronized<[String: Data]>
+    ) {
 
         guard !references.isEmpty else { return }
 

Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift

@@ -300,7 +300,16 @@ public class DocumentationContentRenderer {
 
         let estimatedTime = (node?.semantic as? Timed)?.durationMinutes.flatMap(formatEstimatedDuration(minutes:))
 
-        var renderReference = TopicRenderReference(identifier: .init(referenceURL), title: title, abstract: abstractContent, url: presentationURL.absoluteString, kind: kind, required: isRequired, role: referenceRole, estimatedTime: estimatedTime)
+        var renderReference = TopicRenderReference(
+            identifier: .init(referenceURL),
+            titleVariants: .init(defaultValue: title),
+            abstract: abstractContent,
+            url: presentationURL.absoluteString,
+            kind: kind,
+            required: isRequired,
+            role: referenceRole,
+            estimatedTime: estimatedTime
+        )
 
         // Store the symbol's display name if present in the render reference
         renderReference.fragments = node.flatMap(subHeadingFragments)

Sources/SwiftDocC/Model/Rendering/References/TopicRenderReference.swift

@@ -9,7 +9,7 @@
 */
 
 /// A reference to another page of documentation in the current context.
-public struct TopicRenderReference: RenderReference {
+public struct TopicRenderReference: RenderReference, VariantContainer {
     /// The type of this reference.
     ///
     /// This value is always `.topic`.
@@ -19,7 +19,14 @@ public struct TopicRenderReference: RenderReference {
     public var identifier: RenderReferenceIdentifier
 
     /// The title of the destination page.
-    public var title: String
+    public var title: String {
+        get { getVariantDefaultValue(keyPath: \.titleVariants) }
+        set { setVariantDefaultValue(newValue, keyPath: \.titleVariants) }
+    }
+    
+    /// The variants of the title.
+    public var titleVariants: VariantCollection<String>
+    
     /// The topic url for the destination page.
     public var url: String
     /// The abstract of the destination page.
@@ -98,9 +105,91 @@ public struct TopicRenderReference: RenderReference {
     ///   - name: Raw name of a symbol, e.g. "com.apple.enableDataAccess", or `nil` if the referenced page is not a symbol.
     ///   - ideTitle: The human friendly symbol name, or `nil` if the referenced page is not a symbol.
     ///   - tags: An optional list of string tags.
-    public init(identifier: RenderReferenceIdentifier, title: String, abstract: [RenderInlineContent], url: String, kind: RenderNode.Kind, required: Bool = false, role: String? = nil, fragments: [DeclarationRenderSection.Token]? = nil, navigatorTitle: [DeclarationRenderSection.Token]? = nil, estimatedTime: String?, conformance: ConformanceSection? = nil, isBeta: Bool = false, isDeprecated: Bool = false, defaultImplementationCount: Int? = nil, titleStyle: TitleStyle? = nil, name: String? = nil, ideTitle: String? = nil, tags: [RenderNode.Tag]? = nil) {
+    public init(
+        identifier: RenderReferenceIdentifier,
+        title: String,
+        abstract: [RenderInlineContent],
+        url: String,
+        kind: RenderNode.Kind,
+        required: Bool = false,
+        role: String? = nil,
+        fragments: [DeclarationRenderSection.Token]? = nil,
+        navigatorTitle: [DeclarationRenderSection.Token]? = nil,
+        estimatedTime: String?,
+        conformance: ConformanceSection? = nil,
+        isBeta: Bool = false,
+        isDeprecated: Bool = false,
+        defaultImplementationCount: Int? = nil,
+        titleStyle: TitleStyle? = nil,
+        name: String? = nil,
+        ideTitle: String? = nil,
+        tags: [RenderNode.Tag]? = nil
+    ) {
+        self.init(
+            identifier: identifier,
+            titleVariants: .init(defaultValue: title),
+            abstract: abstract,
+            url: url,
+            kind: kind,
+            required: required,
+            role: role,
+            fragments: fragments,
+            navigatorTitle: navigatorTitle,
+            estimatedTime: estimatedTime,
+            conformance: conformance,
+            isBeta: isBeta,
+            isDeprecated: isDeprecated,
+            defaultImplementationCount: defaultImplementationCount,
+            titleStyle: titleStyle,
+            name: name,
+            ideTitle: ideTitle,
+            tags: tags
+        )
+    }
+    
+    /// Creates a new topic reference with all its initial values.
+    ///
+    /// - Parameters:
+    ///   - identifier: The identifier of this reference.
+    ///   - titleVariants: The variants for the title of the destination page.
+    ///   - abstract: The abstract of the destination page.
+    ///   - url: The topic url of the destination page.
+    ///   - kind: The kind of page that's referenced.
+    ///   - required: Whether the reference is required in its parent context.
+    ///   - role: The additional "role" assigned to the symbol, if any.
+    ///   - fragments: The abbreviated declaration of the symbol to display in links, or `nil` if the referenced page is not a symbol.
+    ///   - navigatorTitle: The abbreviated declaration of the symbol to display in navigation, or `nil` if the referenced page is not a symbol.
+    ///   - estimatedTime: The estimated time to complete the topic.
+    ///   - conformance: Information about conditional conformance for the symbol, or `nil` if the referenced page is not a symbol.
+    ///   - isBeta: Whether this symbol is built for a beta platform, or `false` if the referenced page is not a symbol.
+    ///   - isDeprecated: Whether this symbol is deprecated, or `false` if the referenced page is not a symbol.
+    ///   - defaultImplementationCount: Number of default implementations for this symbol, or `nil` if the referenced page is not a symbol.
+    ///   - titleStyle: Information about which title to use in links to this page.
+    ///   - name: Raw name of a symbol, e.g. "com.apple.enableDataAccess", or `nil` if the referenced page is not a symbol.
+    ///   - ideTitle: The human friendly symbol name, or `nil` if the referenced page is not a symbol.
+    ///   - tags: An optional list of string tags.
+    public init(
+        identifier: RenderReferenceIdentifier,
+        titleVariants: VariantCollection<String>,
+        abstract: [RenderInlineContent],
+        url: String,
+        kind: RenderNode.Kind,
+        required: Bool = false,
+        role: String? = nil,
+        fragments: [DeclarationRenderSection.Token]? = nil,
+        navigatorTitle: [DeclarationRenderSection.Token]? = nil,
+        estimatedTime: String?,
+        conformance: ConformanceSection? = nil,
+        isBeta: Bool = false,
+        isDeprecated: Bool = false,
+        defaultImplementationCount: Int? = nil,
+        titleStyle: TitleStyle? = nil,
+        name: String? = nil,
+        ideTitle: String? = nil,
+        tags: [RenderNode.Tag]? = nil
+    ) {
         self.identifier = identifier
-        self.title = title
+        self.titleVariants = titleVariants
         self.abstract = abstract
         self.url = url
         self.kind = kind
@@ -120,14 +209,32 @@ public struct TopicRenderReference: RenderReference {
     }
 
     enum CodingKeys: String, CodingKey {
-        case type, identifier, title, url, abstract, kind, required, role, fragments, navigatorTitle, estimatedTime, conformance, beta, deprecated, defaultImplementations, titleStyle, name, ideTitle, tags
+        case type
+        case identifier
+        case titleVariants = "title"
+        case url
+        case abstract
+        case kind
+        case required
+        case role
+        case fragments
+        case navigatorTitle
+        case estimatedTime
+        case conformance
+        case beta
+        case deprecated
+        case defaultImplementations
+        case titleStyle
+        case name
+        case ideTitle
+        case tags
     }
 
     public init(from decoder: Decoder) throws {
         let values = try decoder.container(keyedBy: CodingKeys.self)
         type = try values.decode(RenderReferenceType.self, forKey: .type)
         identifier = try values.decode(RenderReferenceIdentifier.self, forKey: .identifier)
-        title = try values.decode(String.self, forKey: .title)
+        titleVariants = try values.decode(VariantCollection<String>.self, forKey: .titleVariants)
         url = try values.decode(String.self, forKey: .url)
         abstract = try values.decodeIfPresent([RenderInlineContent].self, forKey: .abstract) ?? []
         kind = try values.decodeIfPresent(RenderNode.Kind.self, forKey: .kind)
@@ -153,7 +260,7 @@ public struct TopicRenderReference: RenderReference {
 
         try container.encode(type, forKey: .type)
         try container.encode(identifier, forKey: .identifier)
-        try container.encode(title, forKey: .title)
+        try container.encode(titleVariants, forKey: .titleVariants)
         try container.encode(url, forKey: .url)
         try container.encode(abstract, forKey: .abstract)
         try container.encode(kind, forKey: .kind)

Sources/SwiftDocC/Model/Rendering/RenderNode.swift

@@ -28,6 +28,18 @@ import Foundation
 /// The render node schema constantly evolves to support new documentation features. To help clients maintain compatibility,
 /// we associate each schema with a version. See ``schemaVersion`` for more details.
 ///
+/// ### Variants
+///
+/// Different variants of a documentation page can be represented by a single render node using the ``variantOverrides`` property.
+/// This property holds overrides that clients should apply to the render JSON when processing documentation for specific programming languages. The overrides
+/// are organized by traits (e.g., language) and it's up to the client to determine which trait is most appropriate for them. For example, a client that wants to
+/// process the Objective-C version of documentation should apply the overrides associated with the `interfaceLanguage: objc` trait.
+///
+/// Use the ``RenderJSONEncoder/makeEncoder(prettyPrint:emitVariantOverrides:)`` API to instantiate a JSON encoder that's configured
+/// to accumulate variant overrides and emit them to the ``variantOverrides`` property.
+///
+/// The overrides are emitted in the [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) format.
+///
 /// ## Topics
 ///
 /// ### General
@@ -130,6 +142,15 @@ public struct RenderNode {
     /// List of variants of the same documentation node for various languages, etc.
     public var variants: [RenderNode.Variant]?
 
+    /// Language-specific overrides for documentation.
+    ///
+    /// This property holds overrides that clients should apply to the render JSON when processing documentation for specific languages. The overrides are
+    /// organized by traits (e.g., language) and it's up to the client to determine which trait is most appropriate for them. For example, a client that wants to
+    /// process the Objective-C version of documentation should apply the overrides associated with the `interfaceLanguage: objc` trait.
+    ///
+    /// The overrides are emitted in the [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) format.
+    public var variantOverrides: VariantOverrides?
+    
     /// Information about what API diffs are available for this symbol.
     public var diffAvailability: DiffAvailability?