[Hold] Enable hierarchy-based link resolver implementation by default (#498)

* Enable the hierarchy based link resolver implementation by default

rdar://98692937

* Remove redundant symbol link disambiguation

* Correct outdated symbol links

* Remove symbol curation for non-existing symbols

Author: d-ronnqvist

Sources/SwiftDocC/Coverage/DocumentationCoverageOptions.swift

@@ -149,7 +149,7 @@ extension DocumentationCoverageOptions.KindFilterOptions {
         self.init(rawValue: mask)
     }
 
-    /// Represents a single kind option. ``DocumentationCoverageOptions/KindFilterOptions-swift.struct``
+    /// Represents a single kind option. ``DocumentationCoverageOptions/KindFilterOptions``
     /// cannot enforce the restriction that it only represents one
     /// option when necessary so this type is preferred in when representing individual kinds that can be represented.
     public enum BitFlagRepresentation: CaseIterable {

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

@@ -16,7 +16,7 @@ public struct ConvertRequest: Codable {
     /// Information about the documentation bundle to convert.
     ///
     /// ## See Also
-    /// - ``DocumentationBundle/Info-swift.struct``
+    /// - ``DocumentationBundle/Info``
     public var bundleInfo: DocumentationBundle.Info
 
     /// Feature flags to enable when performing this convert request.

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

@@ -21,8 +21,16 @@ enum LinkResolutionMigrationConfiguration {
 
     /// Whether or not the context should the a ``PathHierarchyBasedLinkResolver`` to resolve links.
     static var shouldUseHierarchyBasedLinkResolver: Bool = {
-        return UserDefaults.standard.bool(forKey: "DocCUseHierarchyBasedLinkResolver")
-            || ProcessInfo.processInfo.environment["DOCC_USE_HIERARCHY_BASED_LINK_RESOLVER"] == "YES"
+        let defaultsKey = "DocCUseHierarchyBasedLinkResolver"
+        let environmentKey = "DOCC_USE_HIERARCHY_BASED_LINK_RESOLVER"
+        
+        if UserDefaults.standard.object(forKey: defaultsKey) != nil {
+            return UserDefaults.standard.bool(forKey: defaultsKey)
+        }
+        if let environmentValue = ProcessInfo.processInfo.environment[environmentKey] {
+            return environmentValue == "NO"
+        }
+        return true
     }()
 
     /// Whether or not the context should report differences between the disambiguated paths created by ``PathHierarchyBasedLinkResolver`` and ``DocumentationCacheBasedLinkResolver``.

Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift

@@ -69,7 +69,7 @@ import SymbolKit
 ///
 /// Various information from the summary is used depending on what content references the summarized element. For example:
 ///  - In a paragraph of text, a link to this element will use the ``title`` as the link text and style the tile in code font if the ``kind`` is a type of symbol.
-///  - In a task group, the the ``title`` and ``abstract-swift.property`` is displayed together to give more context about this element and the element may be marked as deprecated
+///  - In a task group, the the ``title`` and ``abstract`` is displayed together to give more context about this element and the element may be marked as deprecated
 ///    based on the values of its  ``platforms`` and other metadata about the current versions of the platforms.
 ///
 /// The summary may include content that vary based on the source language. The content that is different in another source language is specified in a ``Variant``. Any property on the variant that is `nil` has the same value as the summarized element's value. 
@@ -150,7 +150,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
 
     /// References used in the content of the summarized element.
     ///
-    /// This includes the element's ``topicImages`` or references from the element's ``abstract-swift.property``.
+    /// This includes the element's ``topicImages`` or references from the element's ``abstract``.
     /// This also includes any references for all variants' content.
     public var references: [RenderReference]?
 

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

@@ -30,9 +30,9 @@ import Markdown
 /// [ Paragraph ...    ]
 /// ```
 ///
-/// `RenderBlockContent` contains traditional elements like ``paragraph(inlineContent:)`` and
-/// ``heading(level:text:anchor:)`` but also other documentation-specific elements like
-/// ``step(content:caption:media:code:runtimePreview:)`` and ``endpointExample(summary:request:response:)``.
+/// `RenderBlockContent` contains traditional elements like ``paragraph(_:)`` and
+/// ``heading(_:)`` but also other documentation-specific elements like
+/// ``step(_:)`` and ``endpointExample(_:)``.
 ///
 /// Block elements can be nested, for example, an aside note contains one or more paragraphs of text.
 public enum RenderBlockContent: Equatable {

Sources/SwiftDocC/Model/Rendering/RenderNode.swift

@@ -47,7 +47,7 @@ import Foundation
 /// ### General
 ///
 /// - ``schemaVersion``
-/// - ``kind-swift.property``
+/// - ``kind``
 /// - ``sections``
 /// - ``references``
 /// - ``hierarchy``

Sources/SwiftDocC/Semantics/Metadata/CallToAction.swift

@@ -78,7 +78,7 @@ public final class CallToAction: Semantic, AutomaticDirectiveConvertible {
     ]
 
     /// The computed label for this Call to Action, whether provided directly via ``label`` or
-    /// indirectly via ``purpose-swift.property``.
+    /// indirectly via ``purpose``.
     public var buttonLabel: String {
         if let label = label {
             return label

Sources/SwiftDocC/Semantics/Metadata/DisplayName.swift

@@ -15,9 +15,9 @@ import Markdown
 ///
 /// The ``name`` property will override the symbol's default display name.
 ///
-/// When the ``style-swift.property`` property is ``Style-swift.enum/conceptual``, the symbol's name is rendered as "conceptual"—same as article names or tutorial names —where applicable. The default style is ``Style-swift.enum/conceptual``.
+/// When the ``style`` property is ``Style/conceptual``, the symbol's name is rendered as "conceptual"—same as article names or tutorial names —where applicable. The default style is ``Style/conceptual``.
 ///
-/// When the ``style-swift.property`` property is ``Style-swift.enum/symbol``, the symbol's name is rendered as "symbol"—same as article names or tutorial names —where applicable. The default style is ``Style-swift.enum/conceptual``.
+/// When the ``style`` property is ``Style/symbol``, the symbol's name is rendered as "symbol"—same as article names or tutorial names —where applicable. The default style is ``Style/conceptual``.
 ///
 /// This directive is only valid within a ``Metadata`` directive:
 /// ```
@@ -34,7 +34,7 @@ public final class DisplayName: Semantic, AutomaticDirectiveConvertible {
 
     /// The style of the display name for this symbol.
     ///
-    /// Defaults to ``Style-swift.enum/conceptual``.
+    /// Defaults to ``Style/conceptual``.
     @DirectiveArgumentWrapped
     public var style: Style = .conceptual
 

Sources/SwiftDocC/Semantics/Metadata/DocumentationExtension.swift

@@ -13,11 +13,11 @@ import Markdown
 
 /// A directive that controls how the documentation-extension file merges with or overrides the in-source documentation.
 ///
-/// When the ``behavior-swift.property`` property is ``Behavior-swift.enum/append``, the content from the documentation-extension file is added after the content from
+/// When the ``behavior`` property is ``Behavior/append``, the content from the documentation-extension file is added after the content from
 /// the in-source documentation for that symbol.
-/// If a documentation-extension file doesn't have a `DocumentationExtension` directive, then it has the ``Behavior-swift.enum/append`` behavior.
+/// If a documentation-extension file doesn't have a `DocumentationExtension` directive, then it has the ``Behavior/append`` behavior.
 ///
-/// When the ``behavior-swift.property`` property is ``Behavior-swift.enum/override``, the content from the documentation-extension file completely replaces the content
+/// When the ``behavior`` property is ``Behavior/override``, the content from the documentation-extension file completely replaces the content
 /// from the in-source documentation for that symbol
 ///
 /// This directive is only valid within a ``Metadata`` directive:

Sources/SwiftDocC/Semantics/Symbol/PlatformName.swift

@@ -104,7 +104,7 @@ public struct PlatformName: Codable, Hashable, Equatable {
 
     /// Creates a new platform name from the given metadata availability attribute platform.
     ///
-    /// Returns `nil` if the given platform was ``Metadata/Availability/Platform-swift.enum/any``.
+    /// Returns `nil` if the given platform was ``Metadata/Availability/Platform/any``.
     init?(metadataPlatform platform: Metadata.Availability.Platform) {
         // Note: This is still an optional initializer to prevent source breakage when
         // `Availability.Platform` re-introduces the `.any` case