Display entitlement key in symbol reference (#1018)

References to property lists display the key name.

When referencing a symbol in a topics section, if the symbol is a property that contains a key and a custom title, display the key name under the abstract.

rdar://129540266

Author: sofiaromorales

Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift

@@ -363,7 +363,16 @@ public class DocumentationContentRenderer {
         let isRequired = (node?.semantic as? Symbol)?.isRequired ?? false
 
         let estimatedTime = (node?.semantic as? Timed)?.durationMinutes.flatMap(formatEstimatedDuration(minutes:))
-
+        
+        // Add key information for property lists.
+        let propertyListKeyNames = node?.symbol?.plistDetails.map {
+            TopicRenderReference.PropertyListKeyNames(
+                titleStyle: ($0.customTitle != nil) ? .useDisplayName : .useRawKey,
+                rawKey: $0.rawKey,
+                displayName: $0.customTitle
+            )
+        }
+        
         var renderReference = TopicRenderReference(
             identifier: .init(referenceURL),
             titleVariants: VariantCollection<String>(from: titleVariants) ?? .init(defaultValue: ""),
@@ -372,7 +381,8 @@ public class DocumentationContentRenderer {
             kind: kind,
             required: isRequired,
             role: referenceRole,
-            estimatedTime: estimatedTime
+            estimatedTime: estimatedTime,
+            propertyListKeyNames: propertyListKeyNames
         )
 
         renderReference.images = node?.metadata?.pageImages.compactMap { pageImage -> TopicImage? in

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

@@ -270,7 +270,7 @@ public struct TopicRenderReference: RenderReference, VariantContainer, Equatable
         let propertyListTitleStyle = try values.decodeIfPresent(PropertyListTitleStyle.self, forKey: .propertyListTitleStyle)
         let propertyListRawKey = try values.decodeIfPresent(String.self, forKey: .propertyListRawKey)
         let propertyListDisplayName = try values.decodeIfPresent(String.self, forKey: .propertyListDisplayName)
-        if propertyListRawKey != nil || propertyListRawKey != nil || propertyListDisplayName != nil {
+        if propertyListRawKey != nil || propertyListTitleStyle != nil || propertyListDisplayName != nil {
             propertyListKeyNames = PropertyListKeyNames(
                 titleStyle: propertyListTitleStyle,
                 rawKey: propertyListRawKey,

Tests/SwiftDocCTests/Rendering/RESTSymbolsTests.swift

@@ -11,6 +11,8 @@
 import Foundation
 import XCTest
 @testable import SwiftDocC
+import SwiftDocCTestUtilities
+import SymbolKit
 
 fileprivate extension [RenderBlockContent] {
     var firstParagraphText: String? {
@@ -309,4 +311,48 @@ class RESTSymbolsTests: XCTestCase {
 
         AssertRoundtrip(for: object)
     }
+    
+    func testReferenceOfEntitlementWithKeyName() throws {
+        
+        func createDocumentationTopicRenderReferenceForSymbol(keyCustomName: String?) throws -> TopicRenderReference.PropertyListKeyNames {
+            let exampleDocumentation = Folder(name: "unit-test.docc", content: [
+                JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
+                    moduleName: "ModuleName",
+                    symbols: [
+                        SymbolGraph.Symbol(
+                            identifier: .init(precise: "symbol-id", interfaceLanguage: "swift"),
+                            names: .init(title: "Symbol Name", navigator: nil, subHeading: nil, prose: nil),
+                            pathComponents: ["Symbol Name"],
+                            docComment: nil,
+                            accessLevel: .public,
+                            kind: .init(parsedIdentifier: .typeProperty, displayName: "Type Property"),
+                            mixins: [SymbolGraph.Symbol.PlistDetails.mixinKey:SymbolGraph.Symbol.PlistDetails(rawKey: "plist-key-symbolname", customTitle: keyCustomName)]
+                        )
+                    ]
+                ))
+            ])
+            let (_, bundle, context) = try loadBundle(from: (try createTempFolder(content: [exampleDocumentation])))
+            let moduleReference = ResolvedTopicReference(bundleIdentifier: bundle.identifier, path: "/documentation/ModuleName", sourceLanguage: .swift)
+            let moduleSymbol = try XCTUnwrap((try context.entity(with: moduleReference)).semantic as? Symbol)
+            var translator = RenderNodeTranslator(context: context, bundle: bundle, identifier: moduleReference)
+            let renderNode = translator.visit(moduleSymbol) as! RenderNode
+            return try XCTUnwrap((renderNode.references["doc://unit-test/documentation/ModuleName/Symbol_Name"] as? TopicRenderReference)?.propertyListKeyNames)
+        }
+        
+        // The symbol has a custom title.
+        var propertyListKeyNames = try createDocumentationTopicRenderReferenceForSymbol(keyCustomName: "Symbol Custom Title")
+        // Check that the reference contains the key symbol name.
+        XCTAssertEqual(propertyListKeyNames.titleStyle, .useDisplayName)
+        XCTAssertEqual(propertyListKeyNames.rawKey, "plist-key-symbolname")
+        XCTAssertEqual(propertyListKeyNames.displayName, "Symbol Custom Title")
+        
+        // The symbol does not have a custom title.
+        propertyListKeyNames = try createDocumentationTopicRenderReferenceForSymbol(keyCustomName: nil)
+        // Check that the reference does not contain the key symbol name.
+        XCTAssertEqual(propertyListKeyNames.titleStyle, .useRawKey)
+        XCTAssertEqual(propertyListKeyNames.rawKey, "plist-key-symbolname")
+        XCTAssertNil(propertyListKeyNames.displayName)
+    }
+    
+    
 }