Render 'Details' section with property list key information. (#987)

Add 'Details' section to document property list keys.

To better support the documentation of property list keys this adds the  a new section (Details) that renders the mixin information for the key 'plistDetails'. This is used to better  describe property list keys in a human-friendly way.

rdar://131373480

Author: sofiaromorales

Package.resolved

@@ -1363,6 +1363,7 @@ public struct RenderNodeTranslator: SemanticVisitor {
                     HTTPParametersSectionTranslator(parameterSource: .header),
                     HTTPBodySectionTranslator(),
                     HTTPResponsesSectionTranslator(),
+                    PlistDetailsSectionTranslator(),
                     DictionaryKeysSectionTranslator(),
                     AttributesSectionTranslator(),
                     ReturnsSectionTranslator(),

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -0,0 +1,43 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2024 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
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import SymbolKit
+
+/// Translates a symbol's details into a render nodes's details section.
+struct PlistDetailsSectionTranslator: RenderSectionTranslator, Decodable {
+    
+    func generatePlistDetailsRenderSection(_ symbol: Symbol, plistDetails: SymbolGraph.Symbol.PlistDetails) -> PlistDetailsRenderSection {
+        PlistDetailsRenderSection(
+            details: PlistDetailsRenderSection.Details(
+                rawKey: plistDetails.rawKey,
+                value: [TypeDetails(baseType: plistDetails.baseType, arrayMode: plistDetails.arrayMode)],
+                platforms: [],
+                displayName: plistDetails.customTitle,
+                // If the symbol uses the raw key as its title, display its human-friendly name  in the details section.
+                titleStyle: symbol.title == plistDetails.rawKey ? .useRawKey : .useDisplayName
+            )
+        )
+    }
+    
+    func translateSection(for symbol: Symbol, renderNode: inout RenderNode, renderNodeTranslator: inout RenderNodeTranslator) -> VariantCollection<CodableContentSection?>? {
+        guard let mixinVariant = symbol.mixinsVariants.allValues.first(where: { mixin in
+            mixin.variant.keys.contains(SymbolGraph.Symbol.PlistDetails.mixinKey)
+        }) else { return nil }
+        guard let plistDetails = symbol.mixinsVariants.allValues.mapFirst(where: { mixin in
+            mixin.variant[SymbolGraph.Symbol.PlistDetails.mixinKey] as? SymbolGraph.Symbol.PlistDetails
+        }) else {
+            return nil
+        }
+        let section = generatePlistDetailsRenderSection(symbol, plistDetails: plistDetails)
+        return VariantCollection(defaultValue: CodableContentSection(section))
+    }
+    
+}

Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/PlistDetailsSectionTranslator.swift

@@ -0,0 +1,108 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2024 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
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import XCTest
+@testable import SwiftDocC
+import SymbolKit
+import SwiftDocCTestUtilities
+
+class PlistDetailsRenderSectionTests: XCTestCase {
+
+    func testDecoding() throws {
+        
+        func getPlistDetailsSection(arrayMode: CustomStringConvertible, baseType: CustomStringConvertible, rawKey: CustomStringConvertible) throws -> PlistDetailsRenderSection {
+            let symbolJSON = """
+            {
+              "accessLevel" : "public",
+              "availability" : [],
+              "identifier" : {
+                "interfaceLanguage" : "plist",
+                "precise" : "plist:propertylistkey"
+              },
+              "kind" : {
+                "displayName" : "Property List Key",
+                "identifier" : "typealias"
+              },
+              "names" : {
+                "navigator" : [
+                  {
+                    "kind" : "identifier",
+                    "spelling" : "propertylistkey"
+                  }
+                ],
+                "title" : "propertylistkey"
+              },
+              "pathComponents" : [
+                "Information-Property-List",
+                "propertylistkey"
+              ],
+              "plistDetails" : {
+                "arrayMode" : \(arrayMode),
+                "baseType" : \(baseType),
+                "rawKey" : \(rawKey)
+              }
+            }
+            """
+            let symbolGraphString = makeSymbolGraphString(moduleName: "MyModule", symbols: symbolJSON)
+            let tempURL = try createTempFolder(content: [
+                Folder(name: "unit-test.docc", content: [
+                    TextFile(name: "MyModule.symbols.json", utf8Content: symbolGraphString)
+                ])
+            ])
+            let (_, bundle, context) = try loadBundle(from: tempURL)
+            let node = try XCTUnwrap(context.documentationCache["plist:propertylistkey"])
+            let converter = DocumentationNodeConverter(bundle: bundle, context: context)
+            let renderNode = try converter.convert(node)
+            return try XCTUnwrap(renderNode.primaryContentSections.mapFirst(where: { $0 as? PlistDetailsRenderSection }))
+        }
+        
+        // Assert that the Details section is correctly generated when passing valid values into the plistDetails JSON object.
+        XCTAssertEqual(
+            try getPlistDetailsSection(arrayMode: true, baseType: "\"string\"", rawKey: "\"property-list-key\""),
+            PlistDetailsRenderSection(
+               kind: .plistDetails,
+               details: PlistDetailsRenderSection.Details(
+                   rawKey: "property-list-key",
+                   value: [TypeDetails(baseType: "string", arrayMode: true)],
+                   platforms: [],
+                   displayName: nil,
+                   titleStyle: .useDisplayName
+               )
+           )
+       )
+        
+        XCTAssertEqual(
+            try getPlistDetailsSection(arrayMode: false, baseType: "\"string\"", rawKey: "\"property-list-key\""),
+            PlistDetailsRenderSection(
+               kind: .plistDetails,
+               details: PlistDetailsRenderSection.Details(
+                   rawKey: "property-list-key",
+                   value: [TypeDetails(baseType: "string", arrayMode: false)],
+                   platforms: [],
+                   displayName: nil,
+                   titleStyle: .useDisplayName
+               )
+           )
+       )
+        
+        // Assert that the Details section does not decode unsupported values.
+        do {
+            _ = try getPlistDetailsSection(arrayMode: true, baseType: true, rawKey: "\"property-list-key\"")
+        } catch {
+            XCTAssertTrue(error.localizedDescription.contains("isn’t in the correct format"))
+        }
+        do {
+            _ = try getPlistDetailsSection(arrayMode: true, baseType: "\"string\"", rawKey: 1)
+        } catch {
+            XCTAssertTrue(error.localizedDescription.contains("isn’t in the correct format"))
+        }
+    }
+}