Enable parameter and return value validation by default (#882)

* Enable parameter and return value validation by default

rdar://125835874

* Remove various links to symbols that no longer exist

* Fix warnings about undocumented parameters

* Add article about documenting multi-source-language APIs

* Fix additional warnings about undocumented parameters

* Refine the synthesized content phrasing for ObjC API with errors

rdar://125835874

* Clarify documentation about documenting return values.

* Update example error documentation

* Rename feature flag to remove "experimental"

* Remove redundant test setup

* Fix test that documented parameters that the symbol didn't have

* Fix test that was expecting the wrong number of diagnostics

* Add license comment to new documentation article

Author: d-ronnqvist

Sources/SwiftDocC/Benchmark/Benchmark.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
@@ -94,38 +94,48 @@ private extension Benchmark {
 }
 
 /// Logs a one-off metric value.
-/// - Parameter event: The metric to add to the log.
-public func benchmark<E>(add event: @autoclosure () -> E, benchmarkLog log: Benchmark = .main) where E: BenchmarkMetric {
+/// - Parameters:
+///   - metric: The one-off metric
+///   - log: The log to add the metric to.
+public func benchmark<E>(add metric: @autoclosure () -> E, benchmarkLog log: Benchmark = .main) where E: BenchmarkMetric {
     guard log.shouldLogMetricType(E.self) else { return }
 
-    log.metrics.append(event())
+    log.metrics.append(metric())
 }
 
-/// Starts the given metric.
-/// - Parameter event: The metric to start.
-public func benchmark<E>(begin event: @autoclosure () -> E, benchmarkLog log: Benchmark = .main) -> E? where E: BenchmarkBlockMetric {
+/// Begins the given metric.
+/// - Parameters:
+///   - metric: The metric to begin measuring.
+///   - log: The log that may filter out the metric.
+public func benchmark<E>(begin metric: @autoclosure () -> E, benchmarkLog log: Benchmark = .main) -> E? where E: BenchmarkBlockMetric {
     guard log.shouldLogMetricType(E.self) else { return nil }
 
-    let event = event()
-    event.begin()
-    return event
+    let metric = metric()
+    metric.begin()
+    return metric
 }
 
 /// Ends the given metric and adds it to the log.
-/// - Parameter event: The metric to end and log.
-public func benchmark<E>(end event: @autoclosure () -> E?, benchmarkLog log: Benchmark = .main) where E: BenchmarkBlockMetric {
-    guard log.shouldLogMetricType(E.self), let event = event() else { return }
+/// - Parameters:
+///   - metric: The metric to end and log.
+///   - log: The log to add the metric to.
+public func benchmark<E>(end metric: @autoclosure () -> E?, benchmarkLog log: Benchmark = .main) where E: BenchmarkBlockMetric {
+    guard log.shouldLogMetricType(E.self), let metric = metric() else { return }
 
-    event.end()
-    log.metrics.append(event)
+    metric.end()
+    log.metrics.append(metric)
 }
 
-/// Ends the given metric and adds it to the log.
-/// - Parameter event: The metric to end and log.
 @discardableResult
-public func benchmark<E, Result>(wrap event: @autoclosure () -> E, benchmarkLog log: Benchmark = .main, body: () throws -> Result) rethrows -> Result where E: BenchmarkBlockMetric {
+/// Measures a metric around the given closure.
+/// - Parameters:
+///   - metric: The metric to measure and log.
+///   - log: The log to add the metric to.
+///   - body: The closure around which to measure the metric.
+/// - Returns: The return value from the closure.
+public func benchmark<E, Result>(wrap metric: @autoclosure () -> E, benchmarkLog log: Benchmark = .main, body: () throws -> Result) rethrows -> Result where E: BenchmarkBlockMetric {
     if log.shouldLogMetricType(E.self) {
-        let event = event()
+        let event = metric()
         event.begin()
         let result = try body()
         event.end()

Sources/SwiftDocC/Checker/Checkers/MissingAbstract.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
@@ -23,7 +23,6 @@ public struct MissingAbstract: Checker {
 
     /// Creates a new checker that detects documents without abstracts.
     ///
-    /// - Parameter document: The documentation node that the checker checks.
     /// - Parameter sourceFile: The URL to the documentation file that the checker checks.
     public init(sourceFile: URL?) {
         self.sourceFile = sourceFile

Sources/SwiftDocC/Converter/DocumentationContextConverter.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
@@ -37,6 +37,7 @@ public class DocumentationContextConverter {
     /// Whether the documentation converter should include access level information for symbols.
     let shouldEmitSymbolAccessLevels: Bool
 
+    /// A list of symbol IDs that have version of their documentation page with more content that a renderer can link to.
     let symbolIdentifiersWithExpandedDocumentation: [String]?
 
     /// The remote source control repository where the documented module's source is hosted.
@@ -56,7 +57,9 @@ public class DocumentationContextConverter {
     ///     Before passing `true` please confirm that your use case doesn't include public
     ///     distribution of any created render nodes as there are filesystem privacy and security
     ///     concerns with distributing this data.
+    ///   - emitSymbolAccessLevels: Whether the documentation converter should include access level information for symbols.
     ///   - sourceRepository: The source repository where the documentation's sources are hosted.
+    ///   - symbolIdentifiersWithExpandedDocumentation: A list of symbol IDs that have version of their documentation page with more content that a renderer can link to.
     public init(
         bundle: DocumentationBundle,
         context: DocumentationContext,

Sources/SwiftDocC/DocumentationService/Models/Services/Convert/ConvertRequest.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
@@ -98,6 +98,8 @@ public struct ConvertRequest: Codable {
     /// Creates a request to convert in-memory documentation.
     /// - Parameters:
     ///   - bundleInfo: Information about the bundle to convert.
+    ///   - featureFlags: Feature flags to enable when performing this convert request.
+    ///   - externalIDsToConvert: The external IDs of the symbols to convert.
     ///   - documentPathsToConvert: The paths of the documentation nodes to convert.
     ///   - includeRenderReferenceStore: Whether the conversion's render reference store should be included in the
     ///   response.

Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2022 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
@@ -553,16 +553,16 @@ extension NavigatorIndex {
         /// for any custom icons used in this navigator index.
         var iconReferences = [String : ImageReference]()
 
-        /**
-         Initialize a `Builder` with the given data provider and output URL.
-         - Parameters:
-            - renderNodeProvider: The `RenderNode` provider to use.
-            - outputURL: The URL to which the data should be written.
-            - bundleIdentifier: The identifier of the bundle the index is built for.
-            - sortRootChildren: Indicates if the root's children must be sorted by name.
-            - groupByLanguage: Indicates if the tree needs to group the entries by language.
-            - usePageTitle: Use the page title instead of the navigator title as the entry title.
-         */
+        
+        /// Create a new a builder with the given data provider and output URL.
+        /// - Parameters:
+        ///    - renderNodeProvider: The `RenderNode` provider to use.
+        ///    - outputURL: The location where the builder will write the the built navigator index.
+        ///    - bundleIdentifier: The bundle identifier of the documentation that the builder builds a navigator index for.
+        ///    - sortRootChildrenByName: Configure the builder to sort root's children by name.
+        ///    - groupByLanguage: Configure the builder to group the entries by language.
+        ///    - writePathsOnDisk: Configure the builder to write each navigator item's path components to the location.
+        ///    - usePageTitle: Configure the builder to use the "page title" instead of the "navigator title" as the title for each entry.
         public init(renderNodeProvider: RenderNodeProvider? = nil, outputURL: URL, bundleIdentifier: String, sortRootChildrenByName: Bool = false, groupByLanguage: Bool = false, writePathsOnDisk: Bool = true, usePageTitle: Bool = false) {
             self.renderNodeProvider = renderNodeProvider
             self.outputURL = outputURL

Sources/SwiftDocC/Indexing/Navigator/NavigatorItem.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
@@ -42,10 +42,10 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
     public let availabilityID: UInt64
 
     /// The path information of the item (might be a URL as well).
-    internal var path: String = ""
+    var path: String = ""
 
     /// If available, a hashed USR of this entry and its language information.
-    internal var usrIdentifier: String? = nil
+    var usrIdentifier: String? = nil
 
     var icon: RenderReferenceIdentifier? = nil
 
@@ -59,6 +59,7 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
         - platformMask: The mask indicating for which platform the page is available.
         - availabilityID:  The identifier of the availability information of the page.
         - path: The path to load the content.
+        - icon: A reference to a custom image for this navigator item.
      */
     init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, path: String, icon: RenderReferenceIdentifier? = nil) {
         self.pageType = pageType
@@ -79,6 +80,7 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
         - title: The user facing page title.
         - platformMask: The mask indicating for which platform the page is available.
         - availabilityID:  The identifier of the availability information of the page.
+        - icon: A reference to a custom image for this navigator item.
      */
     public init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, icon: RenderReferenceIdentifier? = nil) {
         self.pageType = pageType

Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift

@@ -128,7 +128,7 @@ extension RenderIndex {
         /// Allows renderers to use a specific design treatment for render index nodes that mark the node as in beta.
         public let isBeta: Bool
 
-        /// Reference to the image that should be used to represent this node.
+        /// A reference to a custom image for this node.
         public let icon: RenderReferenceIdentifier?
 
         enum CodingKeys: String, CodingKey {
@@ -197,10 +197,11 @@ extension RenderIndex {
         ///   - path: The relative path to the page represented by this node.
         ///   - type: The type of this node.
         ///   - children: The children of this node.
-        ///   - isDeprecated : If the current node has been marked as deprecated.
+        ///   - isDeprecated: If the current node has been marked as deprecated.
         ///   - isExternal: If the current node belongs to an external
         ///     documentation archive.
         ///   - isBeta: If the current node is in beta.
+        ///   - icon: A reference to a custom image for this node.
         public init(
             title: String,
             path: String?,

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

@@ -187,6 +187,7 @@ public struct DataAsset: Codable, Equatable {
     /// - Parameters:
     ///   - url: The location of the variant.
     ///   - traitCollection: The trait collection associated with the variant.
+    ///   - metadata: Metadata specific to this variant of the asset.
     public mutating func register(_ url: URL, with traitCollection: DataTraitCollection, metadata: Metadata = Metadata()) {
         variants[traitCollection] = url
         self.metadata[url] = metadata

Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift

@@ -104,7 +104,6 @@ public struct CoverageDataEntry: CustomStringConvertible, Codable {
     }
 
     /// Outputs a short table summarizing the coverage statistics for a list of data entries.
-    /// - Parameter coverageInfo: An array of entries to summarize.
     public static func generateSummary(
         of coverageInfo: [CoverageDataEntry],
         shouldGenerateBrief: Bool,

Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticConsoleWriter.swift

@@ -24,8 +24,8 @@ public final class DiagnosticConsoleWriter: DiagnosticFormattingConsumer {
     /// Creates a new instance of this class with the provided output stream.
     /// - Parameters:
     ///   - stream: The output stream to which this instance will write.
-    ///   - formattingOptions: The formatting options for the diagnostics.
-    ///   - baseUrl: A url to be used as a base url when formatting diagnostic source path.
+    ///   - options: The formatting options for the diagnostics.
+    ///   - baseURL: A url to be used as a base url when formatting diagnostic source path.
     ///   - highlight: Whether or not to highlight the default diagnostic formatting output.
     public convenience init(
         _ stream: TextOutputStream = LogHandle.standardError,