Remove API that's been deprecated for more than a full minor release (#684)

* Remove API that's been deprecated since initial release

* Briefly describe process for deprecating and removing API

* Add comments to deprecated API to indicate when it can be removed

* Remove API that was deprecated before the 5.6 release

* Remove API that was deprecated before the 5.7 release

* Rephrase contribution into to be more flexible and to signal removal timeline in deprecation message.

* Move symbol removal information into deprecation message.

* Add removal info to deprecated convert flags

* Remove additional API that was deprecated during the 5.6 release.

* Remove API that was deprecated during the 5.8 release.

* Update additional deprecation attributes with when it will be removed

* Remove additional API that was deprecated during the 5.7 release.

Author: d-ronnqvist

CONTRIBUTING.md

@@ -168,6 +168,26 @@ If you do not have commit access, please ask one of the code owners to trigger t
 For more details on Swift-DocC's continuous integration, see the
 [Continous Integration](#continuous-integration) section below.
 
+### Introducing source breaking changes
+
+We try to avoid source breaking changes, for example:
+
+- removing or renaming public API
+- adding protocol requirements to public API
+- renaming Render JSON keys or adding new required Render JSON keys
+
+That said, sometimes there are good reasons to make these changes. In those cases we make an effort to offer
+a backwards compatible transition by deprecating the old API, alongside the new API, and keeping the deprecated
+API for at least one full minor release. For example, if we deprecate an API sometime after the 5.5 release we
+keep the deprecated API for the remainder of the upcoming release (5.6) and the entirety of the next release (5.7).   
+
+To indicate to API consumers how long the deprecated API will be available, include the version when we'll remove
+that API in the deprecation message. For example:
+
+```swift
+@available(*, deprecated, message: "Use 'UpdatedSymbolName' instead. This deprecated API will be removed after 5.7 is released")
+```
+
 ## Testing Swift-DocC
 
 Swift-DocC is committed to maintaining a high level of code quality.

Sources/SwiftDocC/Converter/DocumentationNodeConverter.swift

@@ -30,19 +30,6 @@ public struct DocumentationNodeConverter {
         self.context = context
     }
 
-    /// Converts a documentation node to a render node.
-    ///
-    /// - Parameters:
-    ///   - node: The documentation node to convert.
-    ///   - source: The source file from which the documentation node's content originated.
-    ///   - bundle: The bundle that contains the content from which the documentation node originated.
-    /// - Returns: The render node representation of the documentation node.
-    @available(*, deprecated, message: "Please use convert(_:at:) instead.")
-    public func convert(_ node: DocumentationNode, at source: URL?, from bundle: DocumentationBundle) throws -> RenderNode {
-        var translator = RenderNodeTranslator(context: context, bundle: bundle, identifier: node.reference, source: source)
-        return translator.visit(node.semantic) as! RenderNode
-    }
-    
     /// Converts a documentation node to a render node.
     ///
     /// Convert a documentation node into a render node to get a self-contained, persistable representation of a given topic's data, so you can write it to disk, send it over a network, or otherwise process it.
@@ -55,7 +42,3 @@ public struct DocumentationNodeConverter {
         return translator.visit(node.semantic) as! RenderNode
     }
 }
-
-/// A converter that coverts documentation nodes to render nodes.
-@available(*, deprecated, message: "Please use DocumentationNodeConverter instead.")
-public typealias Converter = DocumentationNodeConverter

Sources/SwiftDocC/Converter/Rewriter/RenderNodeTransforming.swift

@@ -31,7 +31,3 @@ extension RenderNodeTransforming {
         return RenderNodeTransformationComposition(first: self, second: otherTransformation)
     }
 }
-
-/// A type that modifies a render node.
-@available(*, deprecated, message: "Please use RenderNodeTransforming instead.")
-public typealias RenderNodeTransformation = RenderNodeTransforming

Sources/SwiftDocC/DocumentationService/Models/Services/Convert/ConvertRequest.swift

@@ -57,48 +57,6 @@ public struct ConvertRequest: Codable {
     /// The file location of the bundle to convert, if any.
     public var bundleLocation: URL?
 
-    /// The display name of the documentation bundle to convert.
-    ///
-    /// ## See Also
-    /// - ``DocumentationBundle/displayName``
-    @available(*, deprecated, message: "Use 'bundleInfo.displayName' instead.")
-    public var displayName: String {
-        get {
-            return bundleInfo.displayName
-        }
-        set {
-            bundleInfo.displayName = newValue
-        }
-    }
-    
-    /// The identifier of the documentation bundle to convert.
-    ///
-    /// ## See Also
-    /// - ``DocumentationBundle/identifier``
-    @available(*, deprecated, message: "Use 'bundleInfo.identifier' instead.")
-    public var identifier: String {
-        get {
-            return bundleInfo.identifier
-        }
-        set {
-            bundleInfo.identifier = newValue
-        }
-    }
-    
-    /// The version of the documentation bundle to convert.
-    ///
-    /// ## See Also
-    /// - ``DocumentationBundle/version``
-    @available(*, deprecated, message: "Use 'bundleInfo.version' instead.")
-    public var version: String {
-        get {
-            return bundleInfo.version ?? "0.0.1"
-        }
-        set {
-            bundleInfo.version = newValue
-        }
-    }
-    
     /// The symbols graph data included in the documentation bundle to convert.
     ///
     /// ## See Also
@@ -137,57 +95,6 @@ public struct ConvertRequest: Codable {
     /// a "View More" link that navigates the user to the full version of the documentation page.
     public var symbolIdentifiersWithExpandedDocumentation: [String: ExpandedDocumentationRequirements]?
 
-    /// The default code listing language for the documentation bundle to convert.
-    ///
-    /// ## See Also
-    /// - ``DocumentationBundle/defaultCodeListingLanguage``
-    @available(*, deprecated, message: "Use 'bundleInfo.defaultCodeListingLanguage' instead.")
-    public var defaultCodeListingLanguage: String? {
-        get {
-            return bundleInfo.defaultCodeListingLanguage
-        }
-        set {
-            bundleInfo.defaultCodeListingLanguage = newValue
-        }
-    }
-    
-    @available(*, deprecated, message: "Use 'init(bundleInfo:externalIDsToConvert:...)' instead.")
-    public init(
-        externalIDsToConvert: [String]?,
-        documentPathsToConvert: [String]? = nil,
-        includeRenderReferenceStore: Bool? = nil,
-        bundleLocation: URL? = nil,
-        displayName: String,
-        identifier: String,
-        version: String,
-        symbolGraphs: [Data],
-        knownDisambiguatedSymbolPathComponents: [String: [String]]? = nil,
-        markupFiles: [Data],
-        miscResourceURLs: [URL],
-        defaultCodeListingLanguage: String?
-    ) {
-        self.externalIDsToConvert = externalIDsToConvert
-        self.documentPathsToConvert = documentPathsToConvert
-        self.includeRenderReferenceStore = includeRenderReferenceStore
-        self.bundleLocation = bundleLocation
-        self.symbolGraphs = symbolGraphs
-        self.knownDisambiguatedSymbolPathComponents = knownDisambiguatedSymbolPathComponents
-        self.markupFiles = markupFiles
-        self.tutorialFiles = []
-        self.miscResourceURLs = miscResourceURLs
-        self.featureFlags = FeatureFlags()
-        self.emitSymbolSourceFileURIs = true
-        
-        self.bundleInfo = DocumentationBundle.Info(
-            displayName: displayName,
-            identifier: identifier,
-            version: version,
-            defaultCodeListingLanguage: defaultCodeListingLanguage
-        )
-        
-        self.symbolIdentifiersWithExpandedDocumentation = nil
-    }
-    
     /// Creates a request to convert in-memory documentation.
     /// - Parameters:
     ///   - bundleInfo: Information about the bundle to convert.

Sources/SwiftDocC/Indexing/Navigator/AvailabilityIndex+Ext.swift

@@ -124,19 +124,6 @@ public struct InterfaceLanguage: Hashable, CustomStringConvertible, Codable, Equ
         self.mask = try values.decode(ID.self, forKey: .mask)
     }
 
-    /**
-     Initialize a platform with the given display name and id.
-     Id is an integer used to shift bits and generate a mask for fast processing.
-     
-     - Parameters:
-        - name: The name of the platform used also for display. Note: case sensitive.
-        - id: The ID of the platform.
-     */
-    @available(*, deprecated, renamed: "init(_:id:mask:)")
-    public init(_ name: String, id: Int) {
-        self.init(name, id: name, mask: id)
-    }
-    
     /// Create an interface language with the given display name, id, and integer mask.
     ///
     /// - Parameters:

Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift

@@ -65,7 +65,7 @@ public class NavigatorIndex {
         /// Missing bundle identifier.
         case missingBundleIdentifier
 
-        @available(*, deprecated, renamed: "missingBundleIdentifier")
+        @available(*, deprecated, renamed: "missingBundleIdentifier", message: "Use 'missingBundleIdentifier' instead. This deprecated API will be removed after 5.11 is released")
         case missingBundleIndentifier
 
         /// A RenderNode has no title and won't be indexed.
@@ -233,41 +233,6 @@ public class NavigatorIndex {
         self.pathHasher = pathHasher
         self.navigatorTree = navigatorTree
     }
-    /**
-     Initialize an `NavigatorIndex` from a given path.
-     
-     - Parameters:
-        - url: The URL pointing to the path from which the index should be read.
-        - bundleIdentifier: The name of the bundle the index is referring to.
-        - readNavigatorTree: Indicates if the init needs to read the navigator tree from the disk, if false, then `readNavigatorTree` needs to be called later. Default: `true`.
-        - presentationIdentifier: Indicates if the index has an identifier useful for presentation contexts.
-     
-     - Throws: A `NavigatorIndex.Error` describing the nature of the problem.
-     
-     - Note: The index powered by LMDB opens in `readOnly` mode to avoid performing a filesystem lock which fails without writing permissions. As this initializer opens a built index, write permission is not expected.
-     */
-    @available(*, deprecated, message: "Use NavigatorIndex.readNavigatorIndex instead")
-    public convenience init(url: URL, bundleIdentifier: String? = nil, readNavigatorTree: Bool = true, presentationIdentifier: String? = nil) throws {
-        let navigator = try NavigatorIndex.readNavigatorIndex(
-            url: url,
-            bundleIdentifier: bundleIdentifier,
-            readNavigatorTree: readNavigatorTree,
-            presentationIdentifier: presentationIdentifier
-        )
-        
-        self.init(
-            url: navigator.url,
-            presentationIdentifier: navigator.presentationIdentifier,
-            bundleIdentifier: navigator.bundleIdentifier,
-            environment: navigator.environment!,
-            database: navigator.database!,
-            availability: navigator.availability!,
-            information: navigator.information!,
-            availabilityIndex: navigator.availabilityIndex,
-            pathHasher: navigator.pathHasher,
-            navigatorTree: navigator.navigatorTree
-        )
-    }
 
     /**
      Initialize an `NavigatorIndex` from a given path with an empty tree.
@@ -344,50 +309,6 @@ public class NavigatorIndex {
         case languageGroup = 127
         case container = 254
         case groupMarker = 255 // UInt8.max
-        
-        @available(*, deprecated, message: "Please use instanceProperty.")
-        public static let property = PageType.instanceProperty
-        
-        @available(*, deprecated, message: "Please use tutorial.")
-        public static let project = PageType.tutorial
-        
-        /// Initialize a page type from a `roleHeading` returning the Symbol type.
-        /// - Note: This initializer works only for symbol pages.
-        @available(*, deprecated, message: "Please use init(role:) or init(symbolKind:)")
-        init(roleHeading: String) {
-            switch roleHeading.lowercased() {
-            case "framework": self = .framework
-            case "class": self = .class
-            case "structure": self = .structure
-            case "protocol": self = .protocol
-            case "enumeration": self = .enumeration
-            case "function": self = .function
-            case "extension": self = .extension
-            case "local variable": self = .localVariable
-            case "global variable": self = .globalVariable
-            case "type alias": self = .typeAlias
-            case "associated type": self = .associatedType
-            case "operator": self = .operator
-            case "macro": self = .macro
-            case "union": self = .union
-            case "enumeration case": self = .enumerationCase
-            case "initializer", "init": self = .initializer
-            case "instance method": self = .instanceMethod
-            case "instance property": self = .instanceProperty
-            case "instance variable": self = .instanceVariable
-            case "subscript": self = .subscript
-            case "type method": self = .typeMethod
-            case "type property": self = .typeProperty
-            case "property": self = .instanceProperty
-            case "sample code": self = .sampleCode
-            case "build setting": self = .buildSetting
-            case "property list key": self = .propertyListKey
-            case "property list key reference": self = .propertyListKeyReference
-            case "web service endpoint": self = .httpRequest
-            case "dictionary symbol": self = .dictionarySymbol
-            default:self = .symbol // Generic Symbol.
-            }
-        }
 
         /// Initialize a page type from a `role` and a `symbolKind` returning the Symbol type.
         init(symbolKind: String) {

Sources/SwiftDocC/Indexing/Navigator/NavigatorTree.swift

@@ -61,18 +61,6 @@ public class NavigatorTree {
     /// The root node of the tree.
     public private(set) var root: Node
 
-    /// A map holding the mapping from topicIdentifier to the node.
-    /// - Note: This has been deprecated as the mapping is expensive to build and the path for creating
-    ///         a `ResolvedTopicReference` is not served by the navigator item anymore.
-    @available(*, deprecated)
-    public private(set) var identifierToNode: [ResolvedTopicReference: Node] = [:]
-    
-    /// A map holding the mapping from node to the topicIdentifier.
-    /// - Note: This has been deprecated as the mapping is expensive to build and the path for creating
-    ///         a `ResolvedTopicReference` is not served by the navigator item anymore.
-    @available(*, deprecated)
-    public private(set) var nodeToIdentifier: [Node: ResolvedTopicReference] = [:]
-    
     /// A map holding the mapping from  the numeric identifier to the node.
     public private(set) var numericIdentifierToNode: [UInt32: Node] = [:]
 
@@ -432,17 +420,6 @@ public class NavigatorTree {
 
         /// Storage for additional information in the nodes.
         public var attributes: [String: Any] = [:]
-        
-        /// A value that can be used for disambiguation purposes in presentation contexts.
-        @available(*, deprecated, message: "Use presentationIdentifier instead.")
-        public var presentationDisambiguator: String? {
-            get {
-                return presentationIdentifier
-            }
-            set {
-                presentationIdentifier = newValue
-            }
-        }
 
         /**
          Initialize a node with the given `NavigatorItem`.

Sources/SwiftDocC/Infrastructure/Bundle Assets/DataAssetManager.swift

@@ -205,12 +205,6 @@ public struct DataAsset: Codable, Equatable {
         self.metadata[url] = metadata
     }
 
-    /// Returns the data that is registered to the data asset that best matches the given trait collection.
-    @available(*, deprecated, renamed: "data(bestMatching:)")
-    public func data(with traitCollection: DataTraitCollection) -> BundleData {
-        return data(bestMatching: traitCollection)
-    }
-    
     /// Returns the data that is registered to the data asset that best matches the given trait collection.
     ///
     /// If no variant with the exact given trait collection is found, the variant that has the largest trait collection overlap with the

Sources/SwiftDocC/Infrastructure/Diagnostics/Diagnostic.swift

@@ -12,10 +12,6 @@ import Foundation
 import Markdown
 import SymbolKit
 
-// Keeping this around for backwards compatibility with older clients (rdar://73049176)
-@available(*, deprecated, message: "This typealias will be removed in the future. Use Diagnostic instead.")
-public typealias BasicDiagnostic = Diagnostic
-
 /// A diagnostic explains a problem or issue that needs the end-user's attention.
 public struct Diagnostic {
     /// The origin of the diagnostic, such as a file or process.
@@ -37,15 +33,15 @@ public struct Diagnostic {
     /// A brief summary that describe the problem or issue.
     public var summary: String
 
-    @available(*, deprecated, renamed: "summary")
+    @available(*, deprecated, renamed: "summary", message: "Use 'summary' instead. This deprecated API will be removed after 5.10 is released")
     public var localizedSummary: String {
         return summary
     }
 
     /// Additional details that explain the problem or issue to the end-user in plain language.
     public var explanation: String?
 
-    @available(*, deprecated, renamed: "explanation")
+    @available(*, deprecated, renamed: "explanation", message: "Use 'explanation' instead. This deprecated API will be removed after 5.10 is released")
     public var localizedExplanation: String? {
         return explanation
     }
@@ -89,14 +85,14 @@ public extension Diagnostic {
 
 // MARK: Deprecated
 
-@available(*, deprecated, message: "Use 'DiagnosticConsoleWriter.formattedDescription(for:options:)' instead.")
+@available(*, deprecated, message: "Use 'DiagnosticConsoleWriter.formattedDescription(for:options:)' instead. This deprecated API will be removed after 5.10 is released")
 extension Diagnostic: DescribedError {
-    @available(*, deprecated, message: "Use 'DiagnosticConsoleWriter.formattedDescription(for:options:)' instead.")
+    @available(*, deprecated, message: "Use 'DiagnosticConsoleWriter.formattedDescription(for:options:)' instead. This deprecated API will be removed after 5.10 is released")
     var localizedDescription: String {
         return DiagnosticConsoleWriter.formattedDescription(for: self)
     }
 
-    @available(*, deprecated, message: "Use 'DiagnosticConsoleWriter.formattedDescription(for:options:)' instead.")
+    @available(*, deprecated, message: "Use 'DiagnosticConsoleWriter.formattedDescription(for:options:)' instead. This deprecated API will be removed after 5.10 is released")
     public var errorDescription: String {
         return DiagnosticConsoleWriter.formattedDescription(for: self)
     }