Rename TitleStyle to PropertyListTitleStyle to clarify its purpose (#919)

* Rename `TitleStyle` to `PropertyListTitleStyle` to clarify its purpose

rdar://126292460

* Avoid referring to deprecated "IDE title" in updated documentation

Author: d-ronnqvist

Sources/SwiftDocC/Indexing/RenderSection+TextIndexing.swift

@@ -328,15 +328,15 @@ extension AttributesRenderSection {
 
 extension PlistDetailsRenderSection {
     public var headings: [String] {
-        if let ideTitle = details.ideTitle {
-            return [details.name, ideTitle]
+        if let displayName = details.displayName {
+            return [details.rawKey, displayName]
         } else {
-            return [details.name]
+            return [details.rawKey]
         }
     }
 
     public func rawIndexableTextContent(references: [String : RenderReference]) -> String {
-        return [details.name, details.ideTitle ?? ""].joined(separator: " ")
+        return [details.rawKey, details.displayName ?? ""].joined(separator: " ")
     }
 }
 

Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift

@@ -157,7 +157,6 @@ public class OutOfProcessReferenceResolver: ExternalDocumentationSource, GlobalE
             fragments: resolvedInformation.declarationFragments?.declarationFragments.map { DeclarationRenderSection.Token(fragment: $0, identifier: nil) },
             isBeta: (resolvedInformation.platforms ?? []).contains(where: { $0.isBeta == true }),
             isDeprecated: (resolvedInformation.platforms ?? []).contains(where: { $0.deprecated != nil }),
-            titleStyle: resolvedInformation.kind.isSymbol ? .symbol : .title,
             images: resolvedInformation.topicImages ?? []
         )
         for variant in resolvedInformation.variants ?? [] {

Sources/SwiftDocC/Infrastructure/Link Resolution/ExternalPathHierarchyResolver.swift

@@ -218,9 +218,7 @@ private extension LinkDestinationSummary {
             isBeta: platforms?.contains(where: { $0.isBeta == true }) ?? false,
             isDeprecated: platforms?.contains(where: { $0.unconditionallyDeprecated == true }) ?? false,
             defaultImplementationCount: nil,
-            titleStyle: self.kind.isSymbol ? .symbol : .title,
-            name: title,
-            ideTitle: nil,
+            propertyListKeyNames: nil,
             tags: nil,
             images: topicImages ?? []
         )

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

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-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
@@ -10,55 +10,58 @@
 
 import Foundation
 
-/// A title style for a property list key or an entitlement key.
+/// A style for how to render links to a property list key or an entitlement key.
+public enum PropertyListTitleStyle: String, Codable, Equatable {
+    /// Render links to the property list key using the raw key, for example "com.apple.enableDataAccess".
+    ///
+    /// ## See Also
+    /// - ``TopicRenderReference/PropertyListKeyNames/rawKey``
+    case useRawKey = "symbol"
+    /// Render links to the property list key using the display name, for example "Enables Data Access".
+    ///
+    /// ## See Also
+    /// - ``TopicRenderReference/PropertyListKeyNames/displayName``
+    case useDisplayName = "title"
+}
+
+@available(*, deprecated, renamed: "PropertyListTitleStyle", message: "Use 'PropertyListTitleStyle' instead. This deprecated API will be removed after 6.1 is released")
 public enum TitleStyle: String, Codable, Equatable {
-    // Render links to the symbol using the "raw" name, for example, "com.apple.enableDataAccess".
+    @available(*, deprecated, renamed: "PropertyListTitleStyle.useRawKey", message: "Use 'PropertyListTitleStyle.useRawKey' instead. This deprecated API will be removed after 6.1 is released")
     case symbol
-    // Render links to the symbol using a special "IDE title" name, for example, "Enables Data Access".
+    @available(*, deprecated, renamed: "PropertyListTitleStyle.useDisplayName", message: "Use 'PropertyListTitleStyle.useDisplayName' instead. This deprecated API will be removed after 6.1 is released")
     case title
 }
 
 /// A section that contains details about a property list key.
 struct PlistDetailsRenderSection: RenderSection, Equatable {
-    public var kind: RenderSectionKind = .plistDetails
+    var kind: RenderSectionKind = .plistDetails
     /// A title for the section.
-    public var title = "Details"
+    var title = "Details"
 
     /// Details for a property list key.
     struct Details: Codable, Equatable {
         /// The name of the key.
-        let name: String
+        let rawKey: String
         /// A list of types acceptable for this key's value.
         let value: [TypeDetails]
         /// A list of platforms to which this key applies.
         let platforms: [String]
         /// An optional, human-friendly name of the key.
-        let ideTitle: String?
+        let displayName: String?
         /// A title rendering style.
-        let titleStyle: TitleStyle
+        let titleStyle: PropertyListTitleStyle
+        
+        enum CodingKeys: String, CodingKey {
+            case rawKey = "name"
+            case value
+            case platforms
+            case displayName = "ideTitle"
+            case titleStyle
+        }
     }
 
     /// The details of the property key.
-    public let details: Details
-    
-    // MARK: - Codable
-    
-    /// The list of keys you use to encode or decode this details section.
-    public enum CodingKeys: String, CodingKey {
-        case kind, title, details
-    }
-    
-    public init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        details = try container.decode(Details.self, forKey: .details)
-    }
-    
-    public func encode(to encoder: Encoder) throws {
-        var container = encoder.container(keyedBy: CodingKeys.self)
-        try container.encode(kind, forKey: .kind)
-        try container.encode(title, forKey: .title)
-        try container.encode(details, forKey: .details)
-    }
+    let details: Details
 }
 
 // Diffable conformance

Sources/SwiftDocC/Model/Rendering/Symbol/PlistDetailsRenderSection.swift

@@ -49,9 +49,7 @@ class ExternalReferenceResolverTests: XCTestCase {
                     role: role,
                     fragments: resolvedEntityDeclarationFragments?.declarationFragments.map { fragment in
                         return DeclarationRenderSection.Token(fragment: fragment, identifier: nil)
-                    },
-                    estimatedTime: nil,
-                    titleStyle: resolvedEntityKind.isSymbol ? .symbol : .title
+                    }
                 ),
                 renderReferenceDependencies: RenderReferenceDependencies(),
                 sourceLanguages: [resolvedEntityLanguage]

Tests/SwiftDocCTests/Infrastructure/ExternalReferenceResolverTests.swift

@@ -105,7 +105,6 @@ class TestMultiResultExternalReferenceResolver: ExternalDocumentationSource {
                 fragments: entityInfo.declarationFragments?.declarationFragments.map { fragment in
                     return DeclarationRenderSection.Token(fragment: fragment, identifier: nil)
                 },
-                titleStyle: entityInfo.kind.isSymbol ? .symbol : .title,
                 images: entityInfo.topicImages?.map(\.0) ?? []
             ),
             renderReferenceDependencies: dependencies,

Tests/SwiftDocCTests/Infrastructure/TestExternalReferenceResolvers.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-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
@@ -33,9 +33,9 @@ class PlistSymbolTests: XCTestCase {
             return
         }
 
-        XCTAssertEqual(section.details.name, "com.apple.developer.networking.wifi")
-        XCTAssertEqual(section.details.ideTitle, "WiFi access")
-        XCTAssertEqual(section.details.titleStyle, .title)
+        XCTAssertEqual(section.details.rawKey, "com.apple.developer.networking.wifi")
+        XCTAssertEqual(section.details.displayName, "WiFi access")
+        XCTAssertEqual(section.details.titleStyle, .useDisplayName)
         guard section.details.value.count == 2 else {
             XCTFail("Invalid number of value types found")
             return
@@ -113,9 +113,9 @@ class PlistSymbolTests: XCTestCase {
             XCTFail("Did not find doc://org.swift.docc.example/plist/dataaccess reference")
             return
         }
-        XCTAssertEqual(reference.titleStyle, .title)
-        XCTAssertEqual(reference.name, "com.apple.enabledataaccess")
-        XCTAssertEqual(reference.ideTitle, "Enable Data Access")
+        XCTAssertEqual(reference.propertyListKeyNames?.titleStyle, .useDisplayName)
+        XCTAssertEqual(reference.propertyListKeyNames?.rawKey, "com.apple.enabledataaccess")
+        XCTAssertEqual(reference.propertyListKeyNames?.displayName, "Enable Data Access")
 
         // Test navigator information
         XCTAssertEqual(symbol.navigatorPageType(), .propertyListKey)
@@ -143,8 +143,8 @@ class PlistSymbolTests: XCTestCase {
             return
         }
 
-        XCTAssertEqual(section.details.name, "com.apple.developer.networking.wifi")
-        XCTAssertNil(section.details.ideTitle)
+        XCTAssertEqual(section.details.rawKey, "com.apple.developer.networking.wifi")
+        XCTAssertNil(section.details.displayName)
 
         AssertRoundtrip(for: symbol)
     }

Tests/SwiftDocCTests/Rendering/PlistSymbolTests.swift

@@ -314,6 +314,14 @@ class OutOfProcessReferenceResolverTests: XCTestCase {
            XCTFail("Unexpected fragments variant patch")
         }
 
+        XCTAssertNil(entity.topicRenderReference.conformance)
+        XCTAssertNil(entity.topicRenderReference.estimatedTime)
+        XCTAssertNil(entity.topicRenderReference.defaultImplementationCount)
+        XCTAssertFalse(entity.topicRenderReference.isBeta)
+        XCTAssertFalse(entity.topicRenderReference.isDeprecated)
+        XCTAssertNil(entity.topicRenderReference.propertyListKeyNames)
+        XCTAssertNil(entity.topicRenderReference.tags)
+        
         XCTAssertEqual(entity.topicRenderReference.images.count, 1)
         let topicImage = try XCTUnwrap(entity.topicRenderReference.images.first)
         XCTAssertEqual(topicImage.type, .card)