From 0f9c922ded365a25977f83234cf60482b05d4f02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 3 Apr 2024 10:22:51 +0200 Subject: [PATCH 01/13] Enable parameter and return value validation by default rdar://125835874 --- Sources/SwiftDocC/Utility/FeatureFlags.swift | 2 +- .../ConvertAction+CommandInitialization.swift | 2 +- .../ArgumentParsing/Subcommands/Convert.swift | 21 +++++++++++++++---- .../ConvertSubcommandTests.swift | 20 +++++++++++++++++- 4 files changed, 38 insertions(+), 7 deletions(-) diff --git a/Sources/SwiftDocC/Utility/FeatureFlags.swift b/Sources/SwiftDocC/Utility/FeatureFlags.swift index 553e9a20b4..4d0ef87f95 100644 --- a/Sources/SwiftDocC/Utility/FeatureFlags.swift +++ b/Sources/SwiftDocC/Utility/FeatureFlags.swift @@ -28,7 +28,7 @@ public struct FeatureFlags: Codable { public var isExperimentalMentionedInEnabled = false /// Whether or not experimental support validating parameters and return value documentation is enabled. - public var isExperimentalParametersAndReturnsValidationEnabled = false + public var isExperimentalParametersAndReturnsValidationEnabled = true /// Creates a set of feature flags with the given values. /// diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift index fce6f56f42..9cc086ea6a 100644 --- a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift +++ b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift @@ -24,7 +24,7 @@ extension ConvertAction { FeatureFlags.current.isExperimentalLinkHierarchySerializationEnabled = convert.enableExperimentalLinkHierarchySerialization FeatureFlags.current.isExperimentalOverloadedSymbolPresentationEnabled = convert.enableExperimentalOverloadedSymbolPresentation FeatureFlags.current.isExperimentalMentionedInEnabled = convert.enableExperimentalMentionedIn - FeatureFlags.current.isExperimentalParametersAndReturnsValidationEnabled = convert.enableExperimentalParametersAndReturnsValidation + FeatureFlags.current.isExperimentalParametersAndReturnsValidationEnabled = convert.enableParametersAndReturnsValidation // If the user-provided a URL for an external link resolver, attempt to // initialize an `OutOfProcessReferenceResolver` with the provided URL. diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift index 1bd8c77dff..e04b1e4137 100644 --- a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift +++ b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.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 @@ -539,11 +539,17 @@ extension Docc { var enableExperimentalMentionedIn = false @Flag( - name: .customLong("enable-experimental-parameters-and-returns-validation"), + name: .customLong("parameters-and-returns-validation"), + inversion: .prefixedEnableDisable, help: ArgumentHelp("Validate parameter and return value documentation", discussion: """ Validates and filters symbols' parameter and return value documentation based on the symbol's function signature in each language representation. """) ) + var enableParametersAndReturnsValidation = true + + // This flag only exist to allow developers to pass the previous '--enable-experimental-...' flag without errors. + @Flag(name: .customLong("enable-experimental-parameters-and-returns-validation"), help: .hidden) + @available(*, deprecated, message: "This deprecated API will be removed after 6.0 is released") var enableExperimentalParametersAndReturnsValidation = false @Flag(help: "Write additional metadata files to the output directory.") @@ -566,6 +572,7 @@ extension Docc { Convert.warnAboutDeprecatedOptionIfNeeded("enable-experimental-objective-c-support", message: "This flag has no effect. Objective-C support is enabled by default.") Convert.warnAboutDeprecatedOptionIfNeeded("enable-experimental-json-index", message: "This flag has no effect. The JSON render is emitted by default.") Convert.warnAboutDeprecatedOptionIfNeeded("experimental-parse-doxygen-commands", message: "This flag has no effect. Doxygen support is enabled by default.") + Convert.warnAboutDeprecatedOptionIfNeeded("enable-experimental-parameters-and-returns-validation", message: "This flag has no effect. Parameter and return value validation is enabled by default.") Convert.warnAboutDeprecatedOptionIfNeeded("index", message: "Use '--emit-lmdb-index' indead.") emitLMDBIndex = emitLMDBIndex || index } @@ -634,9 +641,15 @@ extension Docc { } /// A user-provided value that is true if the user enables experimental validation for parameters and return value documentation. + public var enableParametersAndReturnsValidation: Bool { + get { featureFlags.enableParametersAndReturnsValidation } + set { featureFlags.enableParametersAndReturnsValidation = newValue } + } + + @available(*, deprecated, renamed: "enableParametersAndReturnsValidation", message: "Use 'enableParametersAndReturnsValidation' instead. This deprecated API will be removed after 6.0 is released") public var enableExperimentalParametersAndReturnsValidation: Bool { - get { featureFlags.enableExperimentalParametersAndReturnsValidation } - set { featureFlags.enableExperimentalParametersAndReturnsValidation = newValue } + get { enableParametersAndReturnsValidation } + set { enableParametersAndReturnsValidation = newValue } } /// A user-provided value that is true if additional metadata files should be produced. diff --git a/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift b/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift index a025a43ae7..5216f8b236 100644 --- a/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift +++ b/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.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 @@ -600,4 +600,22 @@ class ConvertSubcommandTests: XCTestCase { XCTFail("Failed to run docc convert without arguments.") } } + + func testParameterValidationFeatureFlag() throws { + // The feature is enabled when no flag is passed. + let noFlagConvert = try Docc.Convert.parse([]) + XCTAssertEqual(noFlagConvert.enableParametersAndReturnsValidation, true) + + // It's allowed to pass the previous "--enable-experimental-..." flag. + let oldFlagConvert = try Docc.Convert.parse(["--enable-experimental-parameters-and-returns-validation"]) + XCTAssertEqual(oldFlagConvert.enableParametersAndReturnsValidation, true) + + // It's allowed to pass the redundant "--enable-..." flag. + let enabledFlagConvert = try Docc.Convert.parse(["--enable-parameters-and-returns-validation"]) + XCTAssertEqual(enabledFlagConvert.enableParametersAndReturnsValidation, true) + + // Passing the "--disable-..." flag turns of the feature. + let disabledFlagConvert = try Docc.Convert.parse(["--disable-parameters-and-returns-validation"]) + XCTAssertEqual(disabledFlagConvert.enableParametersAndReturnsValidation, false) + } } From 1f829702b20aef75122ddf77ced611ed681adc03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 3 Apr 2024 10:32:44 +0200 Subject: [PATCH 02/13] Remove various links to symbols that no longer exist --- Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift | 4 +--- Sources/SwiftDocC/Model/Rendering/RenderNode.swift | 4 ++-- Sources/SwiftDocC/Semantics/Symbol/Symbol.swift | 1 - Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Communication.md | 3 +-- .../SwiftDocC/SwiftDocC.docc/SwiftDocC/LinkResolution.md | 2 +- .../SwiftDocC.docc/SwiftDocC/PersistingDocumentation.md | 6 +++--- Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Utilities.md | 3 +-- 7 files changed, 9 insertions(+), 14 deletions(-) diff --git a/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift b/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift index d39b2199c8..45a94d7fc4 100644 --- a/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift +++ b/Sources/SwiftDocC/Infrastructure/DocumentationBundle.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,8 +23,6 @@ import Foundation - ``displayName`` - ``identifier`` - ``version`` - - ``defaultCodeListingLanguage`` - - ``defaultAvailability`` */ public struct DocumentationBundle { public enum PropertyListError: DescribedError { diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNode.swift b/Sources/SwiftDocC/Model/Rendering/RenderNode.swift index e2d37419ec..c3ef2d5515 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderNode.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderNode.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 @@ -35,7 +35,7 @@ import Foundation /// are organized by traits (e.g., language) and it's up to the client to determine which trait is most appropriate for them. For example, a client that wants to /// process the Objective-C version of documentation should apply the overrides associated with the `interfaceLanguage: objc` trait. /// -/// Use the ``RenderJSONEncoder/makeEncoder(prettyPrint:emitVariantOverrides:)`` API to instantiate a JSON encoder that's configured +/// Use the ``RenderJSONEncoder/makeEncoder(prettyPrint:emitVariantOverrides:assetPrefixComponent:)`` API to instantiate a JSON encoder that's configured /// to accumulate variant overrides and emit them to the ``variantOverrides`` property. /// /// The overrides are emitted in the [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) format. diff --git a/Sources/SwiftDocC/Semantics/Symbol/Symbol.swift b/Sources/SwiftDocC/Semantics/Symbol/Symbol.swift index e1fd4984d7..e4d99b8294 100644 --- a/Sources/SwiftDocC/Semantics/Symbol/Symbol.swift +++ b/Sources/SwiftDocC/Semantics/Symbol/Symbol.swift @@ -30,7 +30,6 @@ import SymbolKit /// - ``platformNameVariants`` /// - ``moduleReference`` /// - ``extendedModuleVariants`` -/// - ``bystanderModuleNames`` /// - ``isRequiredVariants`` /// - ``externalIDVariants`` /// - ``accessLevelVariants`` diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Communication.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Communication.md index 7dcd4cca68..9b7e3d80bf 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Communication.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Communication.md @@ -10,7 +10,6 @@ Offer native integration of DocC in your IDE. - ``CommunicationBridge`` - ``CommunicationBridgeError`` - ``DocumentationSchemeHandler`` -- ``TopicReferenceSchemeHandler`` - ``Message`` - ``MessageType`` - ``CodeColors`` @@ -24,4 +23,4 @@ Offer native integration of DocC in your IDE. - ``FileSystemServerProvider`` - ``MemoryFileServerProvider`` - + diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/LinkResolution.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/LinkResolution.md index 374fab85dc..ebfab23d6e 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/LinkResolution.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/LinkResolution.md @@ -72,6 +72,6 @@ extension B { If a ``DocumentationContext`` is configured with one or more ``DocumentationContext/externalDocumentationSources`` it is capable of resolving links general documentation links via that ``ExternalDocumentationSource``. Links to external documentation sources need to be written with a bundle ID in the URI to identify which external resolver should handle the request. -If the other documentation source represents DocC content for another module or project, it is preferred to use ``LinkResolver/dependencyArchives`` instead. This provides richer diagnostics with solutions and supports symbol links to external symbols. +If the other documentation source represents DocC content for another module or project, it is preferred to use `LinkResolver/dependencyArchives` instead. This provides richer diagnostics with solutions and supports symbol links to external symbols. diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/PersistingDocumentation.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/PersistingDocumentation.md index a78198694e..39b900b152 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/PersistingDocumentation.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/PersistingDocumentation.md @@ -6,7 +6,7 @@ Save compiled documentation to disk. Once the in-memory documentation model is finalized each of its graph nodes can be converted to a rendering node and persisted on disk or elsewhere via the `Codable` protocol. -The ``Converter`` type converts documentation nodes to rendering nodes: +The ``DocumentationNodeConverter`` type converts documentation nodes to rendering nodes: ```swift let converter = DocumentationNodeConverter(bundle: myBundle, context: myContext) @@ -28,7 +28,7 @@ The precise path inside the output folder where resulting JSON file is saved is ### Node Persistence -- ``Converter`` +- ``DocumentationNodeConverter`` - ``LinkDestinationSummary`` ### Render Node Rewriter @@ -40,4 +40,4 @@ The precise path inside the output folder where resulting JSON file is saved is - ``RenderNodeTransformationContext`` - ``RenderNodeTransformer`` - + diff --git a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Utilities.md b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Utilities.md index 13daa58665..8b95540cbe 100644 --- a/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Utilities.md +++ b/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Utilities.md @@ -5,7 +5,6 @@ ### Errors - ``DescribedError`` -- ``ErrorWithProblems`` ### Language @@ -21,4 +20,4 @@ - ``Checksum`` - ``FeatureFlags`` - + From d7cc5829477e3742e31fce1249f9471f691c5e36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 3 Apr 2024 11:45:42 +0200 Subject: [PATCH 03/13] Fix warnings about undocumented parameters --- Sources/SwiftDocC/Benchmark/Benchmark.swift | 48 +++++++++------ .../Bundle Assets/DataAssetManager.swift | 1 + .../Infrastructure/CoverageDataEntry.swift | 1 - .../Infrastructure/DocumentationContext.swift | 3 +- .../Workspace/DocumentationWorkspace.swift | 10 ++- .../Rendering/Variants/JSONPatchApplier.swift | 21 ++++--- .../Variants/JSONPatchOperation.swift | 6 +- .../SwiftDocC/Semantics/Symbol/Symbol.swift | 2 +- Sources/SwiftDocC/Servers/FileServer.swift | 61 +++++++++---------- 9 files changed, 82 insertions(+), 71 deletions(-) diff --git a/Sources/SwiftDocC/Benchmark/Benchmark.swift b/Sources/SwiftDocC/Benchmark/Benchmark.swift index 665733ddd4..1acef9742f 100644 --- a/Sources/SwiftDocC/Benchmark/Benchmark.swift +++ b/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(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(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(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(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(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(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(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(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() diff --git a/Sources/SwiftDocC/Infrastructure/Bundle Assets/DataAssetManager.swift b/Sources/SwiftDocC/Infrastructure/Bundle Assets/DataAssetManager.swift index 9baf7c5e9a..e6f3c40eab 100644 --- a/Sources/SwiftDocC/Infrastructure/Bundle Assets/DataAssetManager.swift +++ b/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 diff --git a/Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift b/Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift index 1d47ce2e39..d17988a5d3 100644 --- a/Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift +++ b/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, diff --git a/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift b/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift index 8ae9b7cab3..ebc1af63d1 100644 --- a/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift +++ b/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift @@ -2726,7 +2726,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate { - Parameters: - reference: An unresolved (or resolved) reference. - parent: The *resolved* reference that serves as an enclosing search context, especially the parent reference's bundle identifier. - - fromSymbolLink: If `true` will try to resolve relative links *only* in documentation symbol locations in the hierarchy. If `false` it will try to resolve relative links as tutorials, articles, symbols, etc. + - isCurrentlyResolvingSymbolLink: If `true` will try to resolve relative links *only* in documentation symbol locations in the hierarchy. If `false` it will try to resolve relative links as tutorials, articles, symbols, etc. - Returns: Either the successfully resolved reference for the topic or error information about why the reference couldn't resolve. */ public func resolve(_ reference: TopicReference, in parent: ResolvedTopicReference, fromSymbolLink isCurrentlyResolvingSymbolLink: Bool = false) -> TopicReferenceResolutionResult { @@ -2756,6 +2756,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate { /// - Parameters: /// - name: The name of the asset. /// - parent: The topic where the asset is referenced. + /// - type: A restriction for what type of asset to resolve. /// - Returns: The data that's associated with an image asset if it was found, otherwise `nil`. public func resolveAsset(named name: String, in parent: ResolvedTopicReference, withType type: AssetType? = nil) -> DataAsset? { let bundleIdentifier = parent.bundleIdentifier diff --git a/Sources/SwiftDocC/Infrastructure/Workspace/DocumentationWorkspace.swift b/Sources/SwiftDocC/Infrastructure/Workspace/DocumentationWorkspace.swift index 6d3a0107bb..f53ce292b6 100644 --- a/Sources/SwiftDocC/Infrastructure/Workspace/DocumentationWorkspace.swift +++ b/Sources/SwiftDocC/Infrastructure/Workspace/DocumentationWorkspace.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 @@ -111,7 +111,9 @@ public class DocumentationWorkspace: DocumentationContextDataProvider { /// /// Adding a data provider also adds the documentation bundles that it provides, and notifies the ``delegate`` of the added bundles. /// - /// - Parameter provider: The workspace data provider to add to the workspace. + /// - Parameters: + /// - provider: The workspace data provider to add to the workspace. + /// - options: The options that the data provider uses to discover documentation bundles that it provides to the delegate. public func registerProvider(_ provider: DocumentationWorkspaceDataProvider, options: BundleDiscoveryOptions = .init()) throws { // We must add the provider before adding the bundle so that the delegate // may start making requests immediately. @@ -128,7 +130,9 @@ public class DocumentationWorkspace: DocumentationContextDataProvider { /// /// Removing a data provider also removes all its provided documentation bundles and notifies the ``delegate`` of the removed bundles. /// - /// - Parameter provider: The workspace data provider to remove from the workspace. + /// - Parameters: + /// - provider: The workspace data provider to remove from the workspace. + /// - options: The options that the data provider uses to discover documentation bundles that it removes from the delegate. public func unregisterProvider(_ provider: DocumentationWorkspaceDataProvider, options: BundleDiscoveryOptions = .init()) throws { for bundle in try provider.bundles(options: options) { bundles[bundle.identifier] = nil diff --git a/Sources/SwiftDocC/Model/Rendering/Variants/JSONPatchApplier.swift b/Sources/SwiftDocC/Model/Rendering/Variants/JSONPatchApplier.swift index 839359ce51..089c66c102 100644 --- a/Sources/SwiftDocC/Model/Rendering/Variants/JSONPatchApplier.swift +++ b/Sources/SwiftDocC/Model/Rendering/Variants/JSONPatchApplier.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 @@ -207,21 +207,22 @@ public struct JSONPatchApplier { return .array(array) } - /// An error that occured during the application of a JSON patch. + /// An error that occurred during the application of a JSON patch. public enum Error: DescribedError { /// An error indicating that the pointer of a patch operation is invalid for a JSON object. /// /// - Parameters: - /// - component: The component that's causing the pointer to be invalid in the JSON object. - /// - availableKeys: The keys available in the JSON object. + /// - component: The component that's causing the pointer to be invalid in the JSON object. + /// - availableKeys: The keys available in the JSON object. case invalidObjectPointer(JSONPointer, component: String, availableKeys: [String]) /// An error indicating that the pointer of a patch operation is invalid for a JSON object. /// /// - Parameters: - /// - component: The component that's causing the pointer to be invalid in the JSON object. - /// - availableObjectKeys: The keys available in the JSON object. + /// - pointer: A pointer to the invalid object the JSON document. + /// - component: The component that's causing the pointer to be invalid in the JSON object. + /// - availableObjectKeys: The keys available in the JSON object. public static func invalidObjectPointer( _ pointer: JSONPointer, component: String, @@ -233,15 +234,15 @@ public struct JSONPatchApplier { /// An error indicating that the pointer of a patch operation is invalid for a JSON array. /// /// - Parameters: - /// - index: The index component that's causing the pointer to be invalid in the JSON array. - /// - arrayCount: The size of the JSON array. + /// - index: The index component that's causing the pointer to be invalid in the JSON array. + /// - arrayCount: The size of the JSON array. case invalidArrayPointer(JSONPointer, index: String, arrayCount: Int) /// An error indicating that the pointer of a patch operation is invalid for a JSON value. /// /// - Parameters: - /// - component: The component that's causing the pointer to be invalid, since the JSON element is a non-traversable value. - /// - jsonValue: The string-encoded description of the JSON value. + /// - component: The component that's causing the pointer to be invalid, since the JSON element is a non-traversable value. + /// - jsonValue: The string-encoded description of the JSON value. case invalidValuePointer(JSONPointer, component: String, jsonValue: String) /// An error indicating that a patch operation is invalid. diff --git a/Sources/SwiftDocC/Model/Rendering/Variants/JSONPatchOperation.swift b/Sources/SwiftDocC/Model/Rendering/Variants/JSONPatchOperation.swift index aef285174d..109e46bfd2 100644 --- a/Sources/SwiftDocC/Model/Rendering/Variants/JSONPatchOperation.swift +++ b/Sources/SwiftDocC/Model/Rendering/Variants/JSONPatchOperation.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 @@ -105,8 +105,8 @@ public enum JSONPatchOperation: Codable { /// A replacement operation. /// /// - Parameters: - /// - pointer: The pointer to the value to replace. - /// - encodedValue: The value to use in the replacement. + /// - pointer: The pointer to the value to replace. + /// - encodableValue: The value to use in the replacement. public static func replace(pointer: JSONPointer, encodableValue: Encodable) -> JSONPatchOperation { .replace(pointer: pointer, value: AnyCodable(encodableValue)) } diff --git a/Sources/SwiftDocC/Semantics/Symbol/Symbol.swift b/Sources/SwiftDocC/Semantics/Symbol/Symbol.swift index e4d99b8294..831275c06e 100644 --- a/Sources/SwiftDocC/Semantics/Symbol/Symbol.swift +++ b/Sources/SwiftDocC/Semantics/Symbol/Symbol.swift @@ -381,7 +381,7 @@ public final class Symbol: Semantic, Abstracted, Redirected, AutomaticTaskGroups /// - Parameters: /// - extendedModule: The name of the extended module. /// - extendedSymbolKind: The kind of the extended symbol. - /// - constraint: The new generic constraints to add. + /// - newConstraint: The new generic constraints to add. public func addSwiftExtensionConstraint( extendedModule: String, extendedSymbolKind: SymbolGraph.Symbol.KindIdentifier? = nil, diff --git a/Sources/SwiftDocC/Servers/FileServer.swift b/Sources/SwiftDocC/Servers/FileServer.swift index 183f8ad0ac..90e79fb6ab 100644 --- a/Sources/SwiftDocC/Servers/FileServer.swift +++ b/Sources/SwiftDocC/Servers/FileServer.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 @@ -202,14 +202,13 @@ public class MemoryFileServerProvider: FileServerProvider { public init() {} - /** - Add a file to match a specific path. - Paths can be either a file, like "/js/file.js" or a path "/user/1". - - - parameter path: The path to link the data. - - parameter data: The actual data. - - returns: A Boolean value indicating if the insertion has succeeded. - */ + + /// Add a file to the file server. + /// + /// - Parameters: + /// - path: The path to the file. + /// - data: The data for that file. + /// - Returns: `true` if the file was added successfully. @discardableResult public func addFile(path: String, data: Data) -> Bool { guard !path.isEmpty else { return false } @@ -221,12 +220,10 @@ public class MemoryFileServerProvider: FileServerProvider { return true } - /** - Retrieve the data linked to a given path based on the `baseURL`. - - - parameter path: The path. - - returns: The data matching the url, if possible. - */ + /// Retrieve the data that the server serves for the given path. + /// + /// - Parameter path: The path to a file served by the server. + /// - Returns: The data for that file, if server by the server. Otherwise, `nil`. public func data(for path: String) -> Data? { var trimmed = path.trimmingCharacters(in: slashCharSet) #if os(Windows) @@ -235,23 +232,23 @@ public class MemoryFileServerProvider: FileServerProvider { return files[trimmed] } - /** - Retrieve the data linked to a given path based on the `baseURL`. - - - parameter path: The path. - - returns: The data matching the url, if possible. - */ - public func addFiles(inFolder path: String, inSubPath subPath: String = "", recursive: Bool = true) { + /// Adds files from the `source` directory to the `destination` directory in the file server. + /// + /// - Parameters: + /// - source: The source directory to add files from. + /// - destination: The destination directory in the file server to add the files to. + /// - recursive: Whether or not to recursively add files from the source directory. + public func addFiles(inFolder source: String, inSubPath destination: String = "", recursive: Bool = true) { var isDirectory: ObjCBool = false - guard FileManager.default.fileExists(atPath: path, isDirectory: &isDirectory) else { return } + guard FileManager.default.fileExists(atPath: source, isDirectory: &isDirectory) else { return } guard isDirectory.boolValue else { return } - let trimmedSubPath = subPath.trimmingCharacters(in: slashCharSet) - let enumerator = FileManager.default.enumerator(atPath: path)! + let trimmedSubPath = destination.trimmingCharacters(in: slashCharSet) + let enumerator = FileManager.default.enumerator(atPath: source)! for file in enumerator { guard let file = file as? String else { fatalError("Enumerator returned an unexpected type.") } - guard let data = try? Data(contentsOf: URL(fileURLWithPath: path).appendingPathComponent(file)) else { continue } + guard let data = try? Data(contentsOf: URL(fileURLWithPath: source).appendingPathComponent(file)) else { continue } if recursive == false && file.contains("/") { continue } // skip if subfolder and recursive is disabled addFile(path: "/\(trimmedSubPath)/\(file)", data: data) } @@ -262,13 +259,11 @@ public class MemoryFileServerProvider: FileServerProvider { files.removeAll() } - /** - Removes all files served matching a give subpath. - - - parameter path: The path used to match the files. - */ - public func removeAllFiles(in subPath: String) { - var trimmed = subPath.trimmingCharacters(in: slashCharSet) + /// Removes all files served by the server matching a given subpath. + /// + /// - Parameter directory: The path to a directory to remove + public func removeAllFiles(in directory: String) { + var trimmed = directory.trimmingCharacters(in: slashCharSet) #if os(Windows) trimmed = trimmed.appending(#"\"#) #else From 8f69c7aeb667a7e276670b59ef97b1879d754743 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Fri, 5 Apr 2024 14:42:35 +0200 Subject: [PATCH 04/13] Add article about documenting multi-source-language APIs --- ...with-different-language-representations.md | 61 +++++++++++++++++++ .../linking-to-symbols-and-other-content.md | 7 +-- 2 files changed, 64 insertions(+), 4 deletions(-) create mode 100644 Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md diff --git a/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md b/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md new file mode 100644 index 0000000000..879d18f1af --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md @@ -0,0 +1,61 @@ +# Documenting API with Different Language Representations + +Create documentation for API that's callable from more than one source language. + +## Overview + +When a symbol has representations in more than one source language, DocC adds a source language toggle to the symbol's page so that the reader can select which language's representation of the symbol to view. + +The documentation you write for the symbol---both in-source, alongside its declaration, and in a documentation extension file---is displayed in all language versions of that symbol's page. + +### Linking to Symbols with Different Language Representations + +You can use either source language's spelling of the symbol path to refer to the symbol in a symbol link. +For example, consider a `Sloth` class with `@objc` attributes: + +```swift +@objc(TLASloth) public class Sloth: NSObject { + @objc public init(name: String, color: Color, power: Power) { + self.name = name + self.color = color + self.power = power + } +} +``` + +Both ` ``Sloth/init(name:color:power:)`` ` and ` ``TLASloth/initWithName:color:power:`` ` refer to the same Sloth initializer. + +Regardless of which source language's spelling you use in the symbol link, DocC matches the on-page link text to the symbol name in the source language version of the page that the reader selected. If the symbol doesn't have a representation in the source language that the reader selected, the link text will use the symbol name in the language that declared the symbol. + +For more information about linking to symbols, see . + +### Document Language Specific Parameters and Return Values + +When a symbol has different parameters or return values in different source language representations, DocC hides the documentation for the parameters or return values that don't apply to the source language version of the page that the reader selected. For example, consider an Objective-C method with an `error` parameter and a `BOOL` return value that correspond to a throwing function without a return value in Swift: + +**Objective-C definition** + +```objc +/// - Parameters: +/// - someValue: Some description of this parameter. +/// - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an object containing the information about the error. +/// - Returns: `YES` if "doing something" was successful, or `NO` if an error occurred. +- (BOOL)doSomethingWith:(NSInteger)someValue + error:(NSError **)error; +``` + +**Generated Swift interface** + +```swift +func doSomething(with someValue: Int) throws +``` + +Because the Swift representation of this method only has the "someValue" parameter and no return value, DocC hides the "error" parameter documentation and the return value documentation from the Swift version of this symbol's page. + + +You don't need to document the Objective-C representation's "error" parameter or return value for symbols defined in Swift. +DocC automatically adds a generic description for the "error" parameter and extends your return value documentation to describe the Objective-C specific return value behavior. + +If you want to customize this documentation you can manually document the "error" parameter and return value. +Doing so won't change the Swift version of that symbol's page. +DocC will still hide the parameter and return value documentation that doesn't apply to each source language's version of that symbol's page. diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md index 30e23d8f62..6714bd6f42 100644 --- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md +++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md @@ -139,7 +139,7 @@ symbol paths in either source language. For example, consider a `Sloth` class with `@objc` attributes: ```swift -@objc public class Sloth: NSObject { +@objc(TLASloth) public class Sloth: NSObject { @objc public init(name: String, color: Color, power: Power) { self.name = name self.color = color @@ -148,8 +148,7 @@ class with `@objc` attributes: } ``` -A symbol link to the Sloth initializer can be written using the symbol -path in either source language. +You can write a symbol link to the Sloth initializer using the symbol path in either source language. **Swift name** @@ -160,7 +159,7 @@ path in either source language. **Objective-C name** ```markdown -``Sloth/initWithName:color:power:`` +``TLASloth/initWithName:color:power:`` ``` ### Navigate to an Article From 5179166fa2716d014ec486f8e036e05f50b5269e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 24 Apr 2024 15:47:37 +0200 Subject: [PATCH 05/13] Fix additional warnings about undocumented parameters --- .../Checker/Checkers/MissingAbstract.swift | 3 +- .../DocumentationContextConverter.swift | 5 +- .../Services/Convert/ConvertRequest.swift | 4 +- .../Indexing/Navigator/NavigatorIndex.swift | 22 ++-- .../Indexing/Navigator/NavigatorItem.swift | 8 +- .../RenderIndexJSON/RenderIndex.swift | 5 +- .../Diagnostics/DiagnosticConsoleWriter.swift | 4 +- .../Infrastructure/DocumentationBundle.swift | 11 +- .../DocumentationConverter.swift | 30 +++--- .../OutOfProcessReferenceResolver.swift | 3 + .../Workspace/DefaultAvailability.swift | 2 +- .../Workspace/DocumentationBundle+Info.swift | 7 +- .../LocalFileSystemDataProvider.swift | 7 +- .../SwiftDocC/Model/DocumentationNode.swift | 10 +- .../References/TopicRenderReference.swift | 14 +-- .../Rendering/RenderReferenceStore.swift | 3 +- .../Sections/CallToActionSection.swift | 5 +- .../Variants/VariantCollection.swift | 4 +- .../SwiftDocC/Model/Semantics/Parameter.swift | 5 +- .../SwiftDocC/Model/Semantics/Return.swift | 6 +- .../Semantics/DirectiveConvertable.swift | 17 ++- .../Actions/Convert/ConvertAction.swift | 100 ++++++++++++++---- .../Action/Actions/PreviewAction.swift | 2 +- 23 files changed, 179 insertions(+), 98 deletions(-) diff --git a/Sources/SwiftDocC/Checker/Checkers/MissingAbstract.swift b/Sources/SwiftDocC/Checker/Checkers/MissingAbstract.swift index 02fa682097..06f0657ab2 100644 --- a/Sources/SwiftDocC/Checker/Checkers/MissingAbstract.swift +++ b/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 diff --git a/Sources/SwiftDocC/Converter/DocumentationContextConverter.swift b/Sources/SwiftDocC/Converter/DocumentationContextConverter.swift index 1602b6a86f..e5cd6a439b 100644 --- a/Sources/SwiftDocC/Converter/DocumentationContextConverter.swift +++ b/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, diff --git a/Sources/SwiftDocC/DocumentationService/Models/Services/Convert/ConvertRequest.swift b/Sources/SwiftDocC/DocumentationService/Models/Services/Convert/ConvertRequest.swift index 28fb2f04d1..8bd5d1ebcf 100644 --- a/Sources/SwiftDocC/DocumentationService/Models/Services/Convert/ConvertRequest.swift +++ b/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. diff --git a/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift b/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift index f7e7f8910b..597d18cf24 100644 --- a/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift +++ b/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 diff --git a/Sources/SwiftDocC/Indexing/Navigator/NavigatorItem.swift b/Sources/SwiftDocC/Indexing/Navigator/NavigatorItem.swift index 4aa69e4003..ed4f72436c 100644 --- a/Sources/SwiftDocC/Indexing/Navigator/NavigatorItem.swift +++ b/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 diff --git a/Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift b/Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift index 03c4ef3233..a0cb9c34b6 100644 --- a/Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift +++ b/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?, diff --git a/Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticConsoleWriter.swift b/Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticConsoleWriter.swift index ded5aa30a2..64da2ab85b 100644 --- a/Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticConsoleWriter.swift +++ b/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, diff --git a/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift b/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift index 45a94d7fc4..15b7c9fd2d 100644 --- a/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift +++ b/Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift @@ -79,13 +79,13 @@ public struct DocumentationBundle { /// Miscellaneous resources of the bundle. public let miscResourceURLs: [URL] - /// Custom HTML file to use as the header for rendered output. + /// A custom HTML file to use as the header for rendered output. public let customHeader: URL? - /// Custom HTML file to use as the footer for rendered output. + /// A custom HTML file to use as the footer for rendered output. public let customFooter: URL? - /// JSON settings file used to theme renderer output. + /// A custom JSON settings file used to theme renderer output. public let themeSettings: URL? /** @@ -104,8 +104,9 @@ public struct DocumentationBundle { /// - symbolGraphURLs: Symbol Graph JSON files for the modules documented by the bundle. /// - markupURLs: DocC Markup files of the bundle. /// - miscResourceURLs: Miscellaneous resources of the bundle. - /// - customHeader: Custom HTML file to use as the header for rendered output. - /// - customFooter: Custom HTML file to use as the footer for rendered output. + /// - customHeader: A custom HTML file to use as the header for rendered output. + /// - customFooter: A custom HTML file to use as the footer for rendered output. + /// - themeSettings: A custom JSON settings file used to theme renderer output. public init( info: Info, baseURL: URL = URL(string: "/")!, diff --git a/Sources/SwiftDocC/Infrastructure/DocumentationConverter.swift b/Sources/SwiftDocC/Infrastructure/DocumentationConverter.swift index 0aaa6203be..ad91567d6e 100644 --- a/Sources/SwiftDocC/Infrastructure/DocumentationConverter.swift +++ b/Sources/SwiftDocC/Infrastructure/DocumentationConverter.swift @@ -92,6 +92,7 @@ public struct DocumentationConverter: DocumentationConverterProtocol { /// The source repository where the documentation's sources are hosted. var sourceRepository: SourceRepository? + /// Whether the documentation converter should write documentation extension files containing markdown representations of DocC's automatic curation into the source documentation catalog. var experimentalModifyCatalogWithGeneratedCuration: Bool /// The identifiers and access level requirements for symbols that have an expanded version of their documentation page if the requirements are met @@ -103,28 +104,31 @@ public struct DocumentationConverter: DocumentationConverterProtocol { private var processingDurationMetric: Benchmark.Duration? /// Creates a documentation converter given a documentation bundle's URL. - /// + /// /// - Parameters: /// - documentationBundleURL: The root URL of the documentation bundle to convert. /// - emitDigest: Whether the conversion should create metadata files, such as linkable entities information. /// - documentationCoverageOptions: What level of documentation coverage output should be emitted. /// - currentPlatforms: The current version and beta information for platforms that may be encountered while processing symbol graph files. - /// that may be encountered while processing symbol graph files. /// - workspace: A provided documentation workspace. Creates a new empty workspace if value is `nil`. /// - context: A provided documentation context. /// - dataProvider: A data provider to use when registering bundles. - /// - Parameter fileManager: A file persistence manager - /// - Parameter externalIDsToConvert: The external IDs of the documentation nodes to convert. - /// - Parameter documentPathsToConvert: The paths of the documentation nodes to convert. - /// - Parameter bundleDiscoveryOptions: Options to configure how the converter discovers documentation bundles. - /// - Parameter emitSymbolSourceFileURIs: Whether the documentation converter should include - /// source file location metadata in any render nodes representing symbols it creates. - /// - /// 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. - /// - Parameter symbolIdentifiersWithExpandedDocumentation: Identifiers and access level requirements for symbols + /// - externalIDsToConvert: The external IDs of the documentation nodes to convert. + /// - documentPathsToConvert: The paths of the documentation nodes to convert. + /// - bundleDiscoveryOptions: Options to configure how the converter discovers documentation bundles. + /// - emitSymbolSourceFileURIs: Whether the documentation converter should include + /// source file location metadata in any render nodes representing symbols it creates. + /// + /// 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. + /// - isCancelled: A wrapped boolean value used for the caller to cancel converting the documentation. /// that have an expanded version of their documentation page if the access level requirement is met. + /// - diagnosticEngine: The diagnostic engine that collects any problems encountered from converting the documentation. + /// - symbolIdentifiersWithExpandedDocumentation: Identifiers and access level requirements for symbols + /// - experimentalModifyCatalogWithGeneratedCuration: Whether the documentation converter should write documentation extension files containing markdown representations of DocC's automatic curation into the source documentation catalog. public init( documentationBundleURL: URL?, emitDigest: Bool, diff --git a/Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift b/Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift index bf0bf1754f..d6c4ce5f51 100644 --- a/Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift +++ b/Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift @@ -88,6 +88,7 @@ public class OutOfProcessReferenceResolver: ExternalDocumentationSource, GlobalE /// - Parameters: /// - bundleIdentifier: The bundle identifier the server can resolve references for. /// - server: The server to send link resolution requests to. + /// - convertRequestIdentifier: The identifier that the resolver will use for convert requests that it sends to the server. public init(bundleIdentifier: String, server: DocumentationServer, convertRequestIdentifier: String?) throws { self.bundleIdentifier = bundleIdentifier self.externalLinkResolvingClient = LongRunningService( @@ -599,6 +600,8 @@ extension OutOfProcessReferenceResolver { /// - availableLanguages: The languages where the resolved node is available. /// - platforms: The platforms and their versions where the resolved node is available, if any. /// - declarationFragments: The resolved declaration fragments, if any. + /// - topicImages: Images that are used to represent the summarized element. + /// - references: References used in the content of the summarized element. /// - variants: The variants of content for this resolver information. public init( kind: DocumentationNode.Kind, diff --git a/Sources/SwiftDocC/Infrastructure/Workspace/DefaultAvailability.swift b/Sources/SwiftDocC/Infrastructure/Workspace/DefaultAvailability.swift index f5e92d233e..bbf42a69ba 100644 --- a/Sources/SwiftDocC/Infrastructure/Workspace/DefaultAvailability.swift +++ b/Sources/SwiftDocC/Infrastructure/Workspace/DefaultAvailability.swift @@ -90,7 +90,7 @@ public struct DefaultAvailability: Codable, Equatable { /// Creates a new module availability with a given platform name and platform availability set as unavailable. /// /// - Parameters: - /// - platformName: A platform name, such as "iOS" or "macOS"; see ``PlatformName``. + /// - unavailablePlatformName: A platform name, such as "iOS" or "macOS"; see ``PlatformName``. public init(unavailablePlatformName: PlatformName) { self.platformName = unavailablePlatformName self.versionInformation = .unavailable diff --git a/Sources/SwiftDocC/Infrastructure/Workspace/DocumentationBundle+Info.swift b/Sources/SwiftDocC/Infrastructure/Workspace/DocumentationBundle+Info.swift index 72596e12ac..02750c319f 100644 --- a/Sources/SwiftDocC/Infrastructure/Workspace/DocumentationBundle+Info.swift +++ b/Sources/SwiftDocC/Infrastructure/Workspace/DocumentationBundle+Info.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 @@ -253,15 +253,16 @@ extension DocumentationBundle { extension BundleDiscoveryOptions { /// Creates new bundle discovery options with the given information. - /// + /// /// The given fallback values will be used if any of the discovered bundles are missing that /// value in their Info.plist configuration file. - /// + /// /// - Parameters: /// - fallbackDisplayName: A fallback display name for the bundle. /// - fallbackIdentifier: A fallback identifier for the bundle. /// - fallbackVersion: A fallback version for the bundle. /// - fallbackDefaultCodeListingLanguage: A fallback default code listing language for the bundle. + /// - fallbackDefaultModuleKind: A fallback default module kind for the bundle. /// - fallbackDefaultAvailability: A fallback default availability for the bundle. /// - additionalSymbolGraphFiles: Additional symbol graph files to augment any discovered bundles. public init( diff --git a/Sources/SwiftDocC/Infrastructure/Workspace/LocalFileSystemDataProvider.swift b/Sources/SwiftDocC/Infrastructure/Workspace/LocalFileSystemDataProvider.swift index f368125635..c26145a62f 100644 --- a/Sources/SwiftDocC/Infrastructure/Workspace/LocalFileSystemDataProvider.swift +++ b/Sources/SwiftDocC/Infrastructure/Workspace/LocalFileSystemDataProvider.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 @@ -19,10 +19,13 @@ public struct LocalFileSystemDataProvider: DocumentationWorkspaceDataProvider, F public var fileSystem: FSNode + /// Whether to consider the root location as a documentation bundle if the data provider doesn't discover another bundle in the hierarchy from the root location. public let allowArbitraryCatalogDirectories: Bool /// Creates a new provider that recursively traverses the content of the given root URL to discover documentation bundles. - /// - Parameter rootURL: The location that this provider searches for documentation bundles in. + /// - Parameters: + /// - rootURL: The location that this provider searches for documentation bundles in. + /// - allowArbitraryCatalogDirectories: Configures the data provider to consider the root location as a documentation bundle if it doesn't discover another bundle. public init(rootURL: URL, allowArbitraryCatalogDirectories: Bool = false) throws { self.rootURL = rootURL self.allowArbitraryCatalogDirectories = allowArbitraryCatalogDirectories diff --git a/Sources/SwiftDocC/Model/DocumentationNode.swift b/Sources/SwiftDocC/Model/DocumentationNode.swift index 9fb23b9400..cfd6cba4d0 100644 --- a/Sources/SwiftDocC/Model/DocumentationNode.swift +++ b/Sources/SwiftDocC/Model/DocumentationNode.swift @@ -156,6 +156,7 @@ public struct DocumentationNode { /// - markup: The markup that makes up the content for the node. /// - semantic: The parsed documentation structure that's described by the documentation content. /// - platformNames: The names of the platforms for which the node is available. + /// - isVirtual: `true` if the node represents a virtual element that doesn't represent a rendered page of documentation, `false` otherwise. public init(reference: ResolvedTopicReference, kind: Kind, sourceLanguage: SourceLanguage, availableSourceLanguages: Set? = nil, name: Name, markup: Markup, semantic: Semantic?, platformNames: Set? = nil, isVirtual: Bool = false) { self.reference = reference self.kind = kind @@ -184,8 +185,8 @@ public struct DocumentationNode { /// /// - Parameters: /// - reference: The unique reference to the node. - /// - symbol: The symbol to create a documentation node for. - /// - platformName: The name of the platforms for which the node is available. + /// - unifiedSymbol: The symbol to create a documentation node for. + /// - moduleData: The module that the symbol belongs to. /// - moduleName: The name of the module that the symbol belongs to. init(reference: ResolvedTopicReference, unifiedSymbol: UnifiedSymbolGraph.Symbol, moduleData: SymbolGraph.Module, moduleReference: ResolvedTopicReference) { self.reference = reference @@ -583,11 +584,10 @@ public struct DocumentationNode { /// - Parameters: /// - reference: The unique reference to the node. /// - symbol: The symbol to create a documentation node for. - /// - platformNames: The names of the platforms for which the node is available. - /// - moduleName: The name of the module that the symbol belongs to. + /// - platformName: The names of the platform that the symbol is available for. + /// - moduleReference: A reference to the module that the symbol belongs to. /// - article: The documentation extension content for this symbol. /// - engine:The engine that collects any problems encountered during initialization. - /// - bystanderModules: An optional list of cross-import module names. public init(reference: ResolvedTopicReference, symbol: SymbolGraph.Symbol, platformName: String?, moduleReference: ResolvedTopicReference, article: Article?, engine: DiagnosticEngine) { self.reference = reference diff --git a/Sources/SwiftDocC/Model/Rendering/References/TopicRenderReference.swift b/Sources/SwiftDocC/Model/Rendering/References/TopicRenderReference.swift index 95c2e81d88..16fd5adbe5 100644 --- a/Sources/SwiftDocC/Model/Rendering/References/TopicRenderReference.swift +++ b/Sources/SwiftDocC/Model/Rendering/References/TopicRenderReference.swift @@ -104,11 +104,11 @@ public struct TopicRenderReference: RenderReference, VariantContainer, Equatable /// An optional list of text-based tags. public var tags: [RenderNode.Tag]? - /// Author provided images that should be used to represent this page. + /// Author provided images that represent this page. public var images: [TopicImage] /// Creates a new topic reference with all its initial values. - /// + /// /// - Parameters: /// - identifier: The identifier of this reference. /// - title: The title of the destination page. @@ -128,6 +128,7 @@ public struct TopicRenderReference: RenderReference, VariantContainer, Equatable /// - name: Raw name of a symbol, e.g. "com.apple.enableDataAccess", or `nil` if the referenced page is not a symbol. /// - ideTitle: The human friendly symbol name, or `nil` if the referenced page is not a symbol. /// - tags: An optional list of string tags. + /// - images: Author provided images that represent this page. public init( identifier: RenderReferenceIdentifier, title: String, @@ -173,17 +174,17 @@ public struct TopicRenderReference: RenderReference, VariantContainer, Equatable } /// Creates a new topic reference with all its initial values. - /// + /// /// - Parameters: /// - identifier: The identifier of this reference. /// - titleVariants: The variants for the title of the destination page. - /// - abstract: The abstract of the destination page. + /// - abstractVariants: The abstract of the destination page. /// - url: The topic url of the destination page. /// - kind: The kind of page that's referenced. /// - required: Whether the reference is required in its parent context. /// - role: The additional "role" assigned to the symbol, if any. - /// - fragments: The abbreviated declaration of the symbol to display in links, or `nil` if the referenced page is not a symbol. - /// - navigatorTitle: The abbreviated declaration of the symbol to display in navigation, or `nil` if the referenced page is not a symbol. + /// - fragmentsVariants: The abbreviated declaration of the symbol to display in links, or `nil` if the referenced page is not a symbol. + /// - navigatorTitleVariants: The abbreviated declaration of the symbol to display in navigation, or `nil` if the referenced page is not a symbol. /// - estimatedTime: The estimated time to complete the topic. /// - conformance: Information about conditional conformance for the symbol, or `nil` if the referenced page is not a symbol. /// - isBeta: Whether this symbol is built for a beta platform, or `false` if the referenced page is not a symbol. @@ -193,6 +194,7 @@ public struct TopicRenderReference: RenderReference, VariantContainer, Equatable /// - name: Raw name of a symbol, e.g. "com.apple.enableDataAccess", or `nil` if the referenced page is not a symbol. /// - ideTitle: The human friendly symbol name, or `nil` if the referenced page is not a symbol. /// - tags: An optional list of string tags. + /// - images: Author provided images that represent this page. public init( identifier: RenderReferenceIdentifier, titleVariants: VariantCollection, diff --git a/Sources/SwiftDocC/Model/Rendering/RenderReferenceStore.swift b/Sources/SwiftDocC/Model/Rendering/RenderReferenceStore.swift index 9f2f38ece6..6df5e60d38 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderReferenceStore.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderReferenceStore.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 @@ -70,6 +70,7 @@ public extension RenderReferenceStore { /// - taskGroups: A lookup of a topic's task groups. /// - source: The original source file location of the topic. /// - isDocumentationExtensionContent: Whether the topic is a documentation extension. + /// - renderReferenceDependencies: Render reference dependencies. public init( renderReference: RenderReference, canonicalPath: [ResolvedTopicReference]?, diff --git a/Sources/SwiftDocC/Model/Rendering/Tutorials Overview/Sections/CallToActionSection.swift b/Sources/SwiftDocC/Model/Rendering/Tutorials Overview/Sections/CallToActionSection.swift index 5c894f4142..5f0b82c3a7 100644 --- a/Sources/SwiftDocC/Model/Rendering/Tutorials Overview/Sections/CallToActionSection.swift +++ b/Sources/SwiftDocC/Model/Rendering/Tutorials Overview/Sections/CallToActionSection.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,7 @@ public struct CallToActionSection: RenderSection, Equatable { /// An intro-style image or video to display under the content. public var media: RenderReferenceIdentifier? - /// The primary action to perform. + /// The content that describe the primary action. public var action: RenderInlineContent /// A short description of the section. @@ -35,6 +35,7 @@ public struct CallToActionSection: RenderSection, Equatable { /// - title: The title of the section. /// - abstract: The content for the section's abstract. /// - media: A reference to a media item. + /// - action: The content that describe the primary action. /// - featuredEyebrow: A short description of the section. public init(title: String, abstract: [RenderInlineContent], media: RenderReferenceIdentifier?, action: RenderInlineContent, featuredEyebrow: String) { self.title = title diff --git a/Sources/SwiftDocC/Model/Rendering/Variants/VariantCollection.swift b/Sources/SwiftDocC/Model/Rendering/Variants/VariantCollection.swift index dac093be75..8011b94160 100644 --- a/Sources/SwiftDocC/Model/Rendering/Variants/VariantCollection.swift +++ b/Sources/SwiftDocC/Model/Rendering/Variants/VariantCollection.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 @@ -33,7 +33,7 @@ public struct VariantCollection: Codable { /// /// - Parameters: /// - defaultValue: The default value of the variant. - /// - variantOverrides: The trait-specific overrides for the value. + /// - variants: The trait-specific overrides for the value. public init(defaultValue: Value, variants: [Variant] = []) { self.defaultValue = defaultValue self.variants = variants diff --git a/Sources/SwiftDocC/Model/Semantics/Parameter.swift b/Sources/SwiftDocC/Model/Semantics/Parameter.swift index 5bf6cd11f0..a98daa5d10 100644 --- a/Sources/SwiftDocC/Model/Semantics/Parameter.swift +++ b/Sources/SwiftDocC/Model/Semantics/Parameter.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 @@ -27,6 +27,9 @@ public struct Parameter { /// - Parameters: /// - name: The name of this parameter. /// - contents: The content that describe this parameter. + /// - nameRange: The text range where the parameter name was parsed. + /// - range: The text range where this parameter was parsed. + /// - isStandalone: Whether the parameter is documented standalone or as a member of a parameters outline. public init(name: String, nameRange: SourceRange? = nil, contents: [Markup], range: SourceRange? = nil, isStandalone: Bool = false) { self.name = name self.nameRange = nameRange diff --git a/Sources/SwiftDocC/Model/Semantics/Return.swift b/Sources/SwiftDocC/Model/Semantics/Return.swift index d72b051300..1efb11a2dd 100644 --- a/Sources/SwiftDocC/Model/Semantics/Return.swift +++ b/Sources/SwiftDocC/Model/Semantics/Return.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 @@ -18,7 +18,9 @@ public struct Return { var range: SourceRange? /// Initialize a value to describe documentation about a symbol's return value. - /// - Parameter contents: The content that describe the return value for this symbol. + /// - Parameters: + /// - contents: The content that describe the return value for this symbol. + /// - range: The text range where this return value was parsed. public init(contents: [Markup], range: SourceRange? = nil) { self.contents = contents self.range = range diff --git a/Sources/SwiftDocC/Semantics/DirectiveConvertable.swift b/Sources/SwiftDocC/Semantics/DirectiveConvertable.swift index 7e0b67ff12..f758bff38d 100644 --- a/Sources/SwiftDocC/Semantics/DirectiveConvertable.swift +++ b/Sources/SwiftDocC/Semantics/DirectiveConvertable.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 @@ -30,14 +30,13 @@ public protocol DirectiveConvertible { */ var originalMarkup: BlockDirective { get } - /** - Initialize from a `BlockDirective`, performing semantic analyses to determine whether a valid object can form. - - - parameter directive: The `BlockDirective` from which you want to form the object. - - parameter bundle: The documentation bundle that owns the directive. - - parameter context: The documentation context in which the bundle resides. - - parameter problems: An inout array of ``Problem`` to be collected for later diagnostic reporting. - */ + /// Creates a semantic object from the parsed block directive markup and performs semantic analysis to verify that the semantic object is valid. + /// - Parameters: + /// - directive: The parsed block directive to create a semantic object from. + /// - source: The location of the source file that contains the markup for the parsed block directive. + /// - bundle: The documentation bundle that owns the directive. + /// - context: The documentation context in which the bundle resides. + /// - problems: An inout array of ``Problem`` to be collected for later diagnostic reporting. init?(from directive: BlockDirective, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) /// Returns a Boolean value indicating whether the `DirectiveConvertible` recognizes the given directive. diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift index 6fb48481ec..17d15ad64a 100644 --- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift +++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift @@ -82,21 +82,47 @@ public struct ConvertAction: Action, RecreatingContext { private let diagnosticWriterOptions: (formatting: DiagnosticFormattingOptions, baseURL: URL) /// Initializes the action with the given validated options, creates or uses the given action workspace & context. - /// - Parameter buildIndex: Whether or not the convert action should emit an LMDB representation - /// of the navigator index. - /// - /// A JSON representation is built and emitted regardless of this value. - /// - Parameter workspace: A provided documentation workspace. Creates a new empty workspace if value is `nil` - /// - Parameter context: A provided documentation context. Creates a new empty context in the workspace if value is `nil` - /// - Parameter dataProvider: A data provider to use when registering bundles - /// - Parameter fileManager: A file persistence manager - /// - Parameter documentationCoverageOptions: Indicates whether or not to generate coverage output and at what level. - /// - Parameter diagnosticLevel: The level above which diagnostics will be filtered out. This filter level is inclusive, i.e. if a level of ``DiagnosticSeverity/information`` is specified, diagnostics with a severity up to and including `.information` will be printed. - /// - Parameter diagnosticEngine: The engine that will collect and emit diagnostics during this action. + /// + /// - Parameters: + /// - documentationBundleURL: The root of the documentation catalog to convert. + /// - outOfProcessResolver: An out-of-process resolver that + /// - analyze: `true` if the convert action should override the provided `diagnosticLevel` with `.information`, otherwise `false`. + /// - targetDirectory: The location where the convert action will write the built documentation output. + /// - htmlTemplateDirectory: The location of the HTML template to use as a base for the built documentation output. + /// - emitDigest: Whether the conversion should create metadata files, such as linkable entities information. + /// - currentPlatforms: The current version and beta information for platforms that may be encountered while processing symbol graph files. + /// - buildIndex: Whether or not the convert action should emit an LMDB representation of the navigator index. + /// + /// A JSON representation is built and emitted regardless of this value. + /// - workspace: A provided documentation workspace. Creates a new empty workspace if value is `nil` + /// - context: A provided documentation context. Creates a new empty context in the workspace if value is `nil` + /// - dataProvider: A data provider to use when registering bundles + /// - fileManager: The file manager that the convert action uses to create directories and write data to files. + /// - documentationCoverageOptions: Indicates whether or not to generate coverage output and at what level. + /// - bundleDiscoveryOptions: Options to configure how the converter discovers documentation bundles. + /// - diagnosticLevel: The level above which diagnostics will be filtered out. This filter level is inclusive, i.e. if a level of `DiagnosticSeverity.information` is specified, diagnostics with a severity up to and including `.information` will be printed. + /// - diagnosticEngine: The engine that will collect and emit diagnostics during this action. + /// - diagnosticFilePath: The path to a file where the convert action should write diagnostic information. + /// - formatConsoleOutputForTools: `true` if the convert action should write diagnostics to the console in a format suitable for parsing by an IDE or other tool, otherwise `false`. + /// - inheritDocs: `true` if the convert action should retain the original documentation content for inherited symbols, otherwise `false`. + /// - treatWarningsAsErrors: `true` if the convert action should treat warnings as errors, otherwise `false`. + /// - experimentalEnableCustomTemplates: `true` if the convert action should enable support for custom "header.html" and "footer.html" template files, otherwise `false`. + /// - experimentalModifyCatalogWithGeneratedCuration: `true` if the convert action should write documentation extension files containing markdown representations of DocC's automatic curation into the `documentationBundleURL`, otherwise `false`. + /// - transformForStaticHosting: `true` if the convert action should process the build documentation archive so that it supports a static hosting environment, otherwise `false`. + /// - allowArbitraryCatalogDirectories: `true` if the convert action should consider the root location as a documentation bundle if it doesn't discover another bundle, otherwise `false`. + /// - hostingBasePath: The base path where the built documentation archive will be hosted at. + /// - sourceRepository: The source repository where the documentation's sources are hosted. + /// - temporaryDirectory: The location where the convert action should write temporary files while converting the documentation. + /// - dependencies: A list of URLs to already built documentation archives that this documentation depends on. init( - documentationBundleURL: URL?, outOfProcessResolver: OutOfProcessReferenceResolver?, - analyze: Bool, targetDirectory: URL, htmlTemplateDirectory: URL?, emitDigest: Bool, - currentPlatforms: [String : PlatformVersion]?, buildIndex: Bool = false, + documentationBundleURL: URL?, + outOfProcessResolver: OutOfProcessReferenceResolver?, + analyze: Bool, + targetDirectory: URL, + htmlTemplateDirectory: URL?, + emitDigest: Bool, + currentPlatforms: [String : PlatformVersion]?, + buildIndex: Bool = false, workspace: DocumentationWorkspace = DocumentationWorkspace(), context: DocumentationContext? = nil, dataProvider: DocumentationWorkspaceDataProvider? = nil, @@ -218,16 +244,44 @@ public struct ConvertAction: Action, RecreatingContext { } /// Initializes the action with the given validated options, creates or uses the given action workspace & context. - /// - Parameter workspace: A provided documentation workspace. Creates a new empty workspace if value is `nil` - /// - Parameter context: A provided documentation context. Creates a new empty context in the workspace if value is `nil` - /// - Parameter dataProvider: A data provider to use when registering bundles - /// - Parameter documentationCoverageOptions: Indicates whether or not to generate coverage output and at what level. - /// - Parameter diagnosticLevel: The level above which diagnostics will be filtered out. This filter level is inclusive, i.e. if a level of `DiagnosticSeverity.information` is specified, diagnostics with a severity up to and including `.information` will be printed. - /// - Parameter diagnosticEngine: The engine that will collect and emit diagnostics during this action. + /// + /// - Parameters: + /// - documentationBundleURL: The root of the documentation catalog to convert. + /// - outOfProcessResolver: An out-of-process resolver that + /// - analyze: `true` if the convert action should override the provided `diagnosticLevel` with `.information`, otherwise `false`. + /// - targetDirectory: The location where the convert action will write the built documentation output. + /// - htmlTemplateDirectory: The location of the HTML template to use as a base for the built documentation output. + /// - emitDigest: Whether the conversion should create metadata files, such as linkable entities information. + /// - currentPlatforms: The current version and beta information for platforms that may be encountered while processing symbol graph files. + /// - buildIndex: Whether or not the convert action should emit an LMDB representation of the navigator index. + /// + /// A JSON representation is built and emitted regardless of this value. + /// - workspace: A provided documentation workspace. Creates a new empty workspace if value is `nil` + /// - context: A provided documentation context. Creates a new empty context in the workspace if value is `nil` + /// - dataProvider: A data provider to use when registering bundles + /// - documentationCoverageOptions: Indicates whether or not to generate coverage output and at what level. + /// - bundleDiscoveryOptions: Options to configure how the converter discovers documentation bundles. + /// - diagnosticLevel: The level above which diagnostics will be filtered out. This filter level is inclusive, i.e. if a level of `DiagnosticSeverity.information` is specified, diagnostics with a severity up to and including `.information` will be printed. + /// - diagnosticEngine: The engine that will collect and emit diagnostics during this action. + /// - formatConsoleOutputForTools: `true` if the convert action should write diagnostics to the console in a format suitable for parsing by an IDE or other tool, otherwise `false`. + /// - inheritDocs: `true` if the convert action should retain the original documentation content for inherited symbols, otherwise `false`. + /// - experimentalEnableCustomTemplates: `true` if the convert action should enable support for custom "header.html" and "footer.html" template files, otherwise `false`. + /// - experimentalModifyCatalogWithGeneratedCuration: `true` if the convert action should write documentation extension files containing markdown representations of DocC's automatic curation into the `documentationBundleURL`, otherwise `false`. + /// - transformForStaticHosting: `true` if the convert action should process the build documentation archive so that it supports a static hosting environment, otherwise `false`. + /// - allowArbitraryCatalogDirectories: `true` if the convert action should consider the root location as a documentation bundle if it doesn't discover another bundle, otherwise `false`. + /// - hostingBasePath: The base path where the built documentation archive will be hosted at. + /// - sourceRepository: The source repository where the documentation's sources are hosted. + /// - temporaryDirectory: The location where the convert action should write temporary files while converting the documentation. + /// - dependencies: A list of URLs to already built documentation archives that this documentation depends on. public init( - documentationBundleURL: URL, outOfProcessResolver: OutOfProcessReferenceResolver?, - analyze: Bool, targetDirectory: URL, htmlTemplateDirectory: URL?, emitDigest: Bool, - currentPlatforms: [String : PlatformVersion]?, buildIndex: Bool = false, + documentationBundleURL: URL, + outOfProcessResolver: OutOfProcessReferenceResolver?, + analyze: Bool, + targetDirectory: URL, + htmlTemplateDirectory: URL?, + emitDigest: Bool, + currentPlatforms: [String : PlatformVersion]?, + buildIndex: Bool = false, workspace: DocumentationWorkspace = DocumentationWorkspace(), context: DocumentationContext? = nil, dataProvider: DocumentationWorkspaceDataProvider? = nil, diff --git a/Sources/SwiftDocCUtilities/Action/Actions/PreviewAction.swift b/Sources/SwiftDocCUtilities/Action/Actions/PreviewAction.swift index 6c8b44954f..a62dfc18b3 100644 --- a/Sources/SwiftDocCUtilities/Action/Actions/PreviewAction.swift +++ b/Sources/SwiftDocCUtilities/Action/Actions/PreviewAction.swift @@ -66,7 +66,7 @@ public final class PreviewAction: Action, RecreatingContext { /// /// - Parameters: /// - port: The port number used by the preview server. - /// - convertAction: The action used to convert the documentation bundle before preview. + /// - createConvertAction: A closure that returns the action used to convert the documentation before preview. /// On macOS, this action will be reused to convert documentation each time the source is modified. /// - workspace: The documentation workspace used by the action's documentation context. /// - context: The documentation context for the action. From c8411d63073d7b99eae2a1fed32649c363777b65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 24 Apr 2024 15:49:18 +0200 Subject: [PATCH 06/13] Refine the synthesized content phrasing for ObjC API with errors rdar://125835874 --- .../SwiftDocC/Model/ParametersAndReturnValidator.swift | 6 +++--- .../Model/ParametersAndReturnValidatorTests.swift | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Sources/SwiftDocC/Model/ParametersAndReturnValidator.swift b/Sources/SwiftDocC/Model/ParametersAndReturnValidator.swift index bd47eb0add..6d0cac43c0 100644 --- a/Sources/SwiftDocC/Model/ParametersAndReturnValidator.swift +++ b/Sources/SwiftDocC/Model/ParametersAndReturnValidator.swift @@ -592,16 +592,16 @@ struct ParametersAndReturnValidator { private static let objcErrorDescription: [Markup] = [ Paragraph([ - Text("On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.") + Text("On output, a pointer to an error object that describes why the method failed, or ") as InlineMarkup, InlineCode("nil"), Text(" if no error occurred. If you are not interested in the error information, pass "), InlineCode("nil"), Text(" for this parameter.") ]) ] private static let objcBoolErrorDescription: [Markup] = [ Paragraph([ - InlineCode("YES") as InlineMarkup, Text(" if successful, or "), InlineCode("NO"), Text(" if an error occurred.") + InlineCode("YES") as InlineMarkup, Text(" if the method succeeded, otherwise "), InlineCode("NO"), Text(".") ]) ] private static func objcObjectErrorAddition(endPreviousSentence: Bool) -> [InlineMarkup] { - [Text("\(endPreviousSentence ? "." : "") If an error occurs, this method returns "), InlineCode("nil"), Text(" and assigns an appropriate error object to the "), InlineCode("error"), Text(" parameter.")] + [Text("\(endPreviousSentence ? "." : "") On failure, this method returns "), InlineCode("nil"), Text(".")] } private static func newParameterDescription(name: String, standalone: Bool) -> String { diff --git a/Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift b/Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift index b3e2ef4a77..8388abcbdc 100644 --- a/Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift +++ b/Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift @@ -86,11 +86,11 @@ class ParametersAndReturnValidatorTests: XCTestCase { XCTAssertEqual(parameterSections[.swift]?.parameters.first?.contents.map({ $0.format() }).joined(), "Some value.") XCTAssertEqual(parameterSections[.objectiveC]?.parameters.map(\.name), ["someValue", "error"]) XCTAssertEqual(parameterSections[.objectiveC]?.parameters.first?.contents.map({ $0.format() }).joined(), "Some value.") - XCTAssertEqual(parameterSections[.objectiveC]?.parameters.last?.contents.map({ $0.format() }).joined(), "On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.") + XCTAssertEqual(parameterSections[.objectiveC]?.parameters.last?.contents.map({ $0.format() }).joined(), "On output, a pointer to an error object that describes why the method failed, or `nil` if no error occurred. If you are not interested in the error information, pass `nil` for this parameter.") let returnsSections = symbol.returnsSectionVariants XCTAssertEqual(returnsSections[.swift]?.content.map({ $0.format() }).joined(), "", "The method has no return value documentation but needs an empty returns section to so that the rendered page doesn't use the Objective-C variant as a fallback.") - XCTAssertEqual(returnsSections[.objectiveC]?.content.map({ $0.format() }).joined(), "`YES` if successful, or `NO` if an error occurred.", "The Objective-C variant returns BOOL") + XCTAssertEqual(returnsSections[.objectiveC]?.content.map({ $0.format() }).joined(), "`YES` if the method succeeded, otherwise `NO`.", "The Objective-C variant returns BOOL") } // /// Returns something from Swift. @@ -112,7 +112,7 @@ class ParametersAndReturnValidatorTests: XCTestCase { let returnsSections = symbol.returnsSectionVariants XCTAssertEqual(returnsSections[.swift]?.content.map({ $0.format() }).joined(), "Some string.") - XCTAssertEqual(returnsSections[.objectiveC]?.content.map({ $0.format() }).joined(), "Some string. If an error occurs, this method returns `nil` and assigns an appropriate error object to the `error` parameter.") + XCTAssertEqual(returnsSections[.objectiveC]?.content.map({ $0.format() }).joined(), "Some string. On failure, this method returns `nil`.") } } @@ -358,7 +358,7 @@ class ParametersAndReturnValidatorTests: XCTestCase { let parameterSections = symbol.parametersSectionVariants XCTAssertEqual(parameterSections[.swift]?.parameters.map(\.name), [], "The Swift variant has no error parameter") XCTAssertEqual(parameterSections[.objectiveC]?.parameters.map(\.name), ["error"]) - XCTAssertEqual(parameterSections[.objectiveC]?.parameters.last?.contents.map({ $0.format() }).joined(), "On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information.") + XCTAssertEqual(parameterSections[.objectiveC]?.parameters.last?.contents.map({ $0.format() }).joined(), "On output, a pointer to an error object that describes why the method failed, or `nil` if no error occurred. If you are not interested in the error information, pass `nil` for this parameter.") let returnsSections = symbol.returnsSectionVariants XCTAssertEqual(returnsSections[.swift]?.content.map({ $0.format() }).joined(), "", "The Swift variant has no return value") From fb2a141b205507b6ce54381784e20cb123b78c8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 24 Apr 2024 17:27:01 +0200 Subject: [PATCH 07/13] Clarify documentation about documenting return values. --- .../documenting-api-with-different-language-representations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md b/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md index 879d18f1af..434d0a3776 100644 --- a/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md +++ b/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md @@ -53,7 +53,7 @@ func doSomething(with someValue: Int) throws Because the Swift representation of this method only has the "someValue" parameter and no return value, DocC hides the "error" parameter documentation and the return value documentation from the Swift version of this symbol's page. -You don't need to document the Objective-C representation's "error" parameter or return value for symbols defined in Swift. +You don't need to document the Objective-C representation's "error" parameter or Objective-C specific return value for symbols defined in Swift. DocC automatically adds a generic description for the "error" parameter and extends your return value documentation to describe the Objective-C specific return value behavior. If you want to customize this documentation you can manually document the "error" parameter and return value. From 57340264e6e2da6cb4944f3d2aa33bd330001eac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 24 Apr 2024 17:27:14 +0200 Subject: [PATCH 08/13] Update example error documentation --- ...documenting-api-with-different-language-representations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md b/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md index 434d0a3776..7357c4bdce 100644 --- a/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md +++ b/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md @@ -38,8 +38,8 @@ When a symbol has different parameters or return values in different source lang ```objc /// - Parameters: /// - someValue: Some description of this parameter. -/// - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an object containing the information about the error. -/// - Returns: `YES` if "doing something" was successful, or `NO` if an error occurred. +/// - error: On output, a pointer to an error object that describes why "doing somehting" failed, or `nil` if no error occurred. +/// - Returns: `YES` if "doing something" was successful, `NO` if an error occurred. - (BOOL)doSomethingWith:(NSInteger)someValue error:(NSError **)error; ``` From 5950f9fcbcbfaef7448366a92a4bc97b750e58fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 24 Apr 2024 17:27:49 +0200 Subject: [PATCH 09/13] Rename feature flag to remove "experimental" --- .../SwiftDocC/Model/ParametersAndReturnValidator.swift | 2 +- Sources/SwiftDocC/Utility/FeatureFlags.swift | 10 ++++++++-- .../ConvertAction+CommandInitialization.swift | 2 +- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/Sources/SwiftDocC/Model/ParametersAndReturnValidator.swift b/Sources/SwiftDocC/Model/ParametersAndReturnValidator.swift index 6d0cac43c0..2baada31a2 100644 --- a/Sources/SwiftDocC/Model/ParametersAndReturnValidator.swift +++ b/Sources/SwiftDocC/Model/ParametersAndReturnValidator.swift @@ -68,7 +68,7 @@ struct ParametersAndReturnValidator { parameterSection: DocumentationDataVariants, returnsSection: DocumentationDataVariants ) { - guard FeatureFlags.current.isExperimentalParametersAndReturnsValidationEnabled, + guard FeatureFlags.current.isParametersAndReturnsValidationEnabled, let symbol = unifiedSymbol, !hasInheritedDocumentationComment(symbol: symbol), let signatures = Self.traitSpecificSignatures(symbol) diff --git a/Sources/SwiftDocC/Utility/FeatureFlags.swift b/Sources/SwiftDocC/Utility/FeatureFlags.swift index 4d0ef87f95..2ccaf9f062 100644 --- a/Sources/SwiftDocC/Utility/FeatureFlags.swift +++ b/Sources/SwiftDocC/Utility/FeatureFlags.swift @@ -27,8 +27,14 @@ public struct FeatureFlags: Codable { /// that mention that symbol. public var isExperimentalMentionedInEnabled = false - /// Whether or not experimental support validating parameters and return value documentation is enabled. - public var isExperimentalParametersAndReturnsValidationEnabled = true + /// Whether or not support for validating parameters and return value documentation is enabled. + public var isParametersAndReturnsValidationEnabled = true + + @available(*, deprecated, renamed: "isParametersAndReturnsValidationEnabled", message: "Use 'isParametersAndReturnsValidationEnabled' instead. This deprecated API will be removed after 6.1 is released") + public var isExperimentalParametersAndReturnsValidationEnabled: Bool { + get { isParametersAndReturnsValidationEnabled } + set { isParametersAndReturnsValidationEnabled = newValue } + } /// Creates a set of feature flags with the given values. /// diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift index 9cc086ea6a..5fc21e41ad 100644 --- a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift +++ b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift @@ -24,7 +24,7 @@ extension ConvertAction { FeatureFlags.current.isExperimentalLinkHierarchySerializationEnabled = convert.enableExperimentalLinkHierarchySerialization FeatureFlags.current.isExperimentalOverloadedSymbolPresentationEnabled = convert.enableExperimentalOverloadedSymbolPresentation FeatureFlags.current.isExperimentalMentionedInEnabled = convert.enableExperimentalMentionedIn - FeatureFlags.current.isExperimentalParametersAndReturnsValidationEnabled = convert.enableParametersAndReturnsValidation + FeatureFlags.current.isParametersAndReturnsValidationEnabled = convert.enableParametersAndReturnsValidation // If the user-provided a URL for an external link resolver, attempt to // initialize an `OutOfProcessReferenceResolver` with the provided URL. From a3b34121e8748457a734dc7ac813958dfbf57079 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 24 Apr 2024 17:41:36 +0200 Subject: [PATCH 10/13] Remove redundant test setup --- .../Model/ParametersAndReturnValidatorTests.swift | 5 ----- 1 file changed, 5 deletions(-) diff --git a/Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift b/Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift index 8388abcbdc..0e268eddac 100644 --- a/Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift +++ b/Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift @@ -17,11 +17,6 @@ import SwiftDocCTestUtilities class ParametersAndReturnValidatorTests: XCTestCase { - override func setUp() { - super.setUp() - enableFeatureFlag(\.isExperimentalParametersAndReturnsValidationEnabled) - } - func testFiltersParameters() throws { let (bundle, context) = try testBundleAndContext(named: "ErrorParameters") From f9545b387a7c8969428e696f9c0428b9fd6c2e15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 24 Apr 2024 17:37:52 +0200 Subject: [PATCH 11/13] Fix test that documented parameters that the symbol didn't have --- .../AutoCapitalizationTests.swift | 36 ++++++++++--------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/Tests/SwiftDocCTests/Infrastructure/AutoCapitalizationTests.swift b/Tests/SwiftDocCTests/Infrastructure/AutoCapitalizationTests.swift index 3bbfb7f470..47d3733d6b 100644 --- a/Tests/SwiftDocCTests/Infrastructure/AutoCapitalizationTests.swift +++ b/Tests/SwiftDocCTests/Infrastructure/AutoCapitalizationTests.swift @@ -10,29 +10,22 @@ import Foundation import XCTest -import Markdown -@testable import SymbolKit -@_spi(ExternalLinks) @testable import SwiftDocC +import SymbolKit +@testable import SwiftDocC import SwiftDocCTestUtilities class AutoCapitalizationTests: XCTestCase { - // MARK: Test helpers private let start = SymbolGraph.LineList.SourceRange.Position(line: 7, character: 6) // an arbitrary non-zero start position private let symbolURL = URL(fileURLWithPath: "/path/to/SomeFile.swift") - private func makeSymbolGraph(docComment: String) -> SymbolGraph { + private func makeSymbolGraph(docComment: String, parameters: [String]) -> SymbolGraph { makeSymbolGraph( docComment: docComment, sourceLanguage: .swift, - parameters: [ - ("firstParameter", nil), - ("secondParameter", nil), - ("thirdParameter", nil), - ("fourthParameter", nil), - ], + parameters: parameters.map { ($0, nil) }, returnValue: .init(kind: .typeIdentifier, spelling: "ReturnValue", preciseIdentifier: "return-value-id") ) } @@ -79,7 +72,8 @@ class AutoCapitalizationTests: XCTestCase { // MARK: End-to-end integration tests func testParametersCapitalization() throws { - let symbolGraph = makeSymbolGraph(docComment: """ + let symbolGraph = makeSymbolGraph( + docComment: """ Some symbol description. - Parameters: @@ -88,7 +82,9 @@ class AutoCapitalizationTests: XCTestCase { - three: inValid third parameter will not be capitalized - four: `code block` will not be capitalized - five: a`nother invalid capitalization - """) + """, + parameters: ["one", "two", "three", "four", "five"] + ) let url = try createTempFolder(content: [ Folder(name: "unit-test.docc", content: [ @@ -124,7 +120,8 @@ class AutoCapitalizationTests: XCTestCase { } func testIndividualParametersCapitalization() throws { - let symbolGraph = makeSymbolGraph(docComment: """ + let symbolGraph = makeSymbolGraph( + docComment: """ Some symbol description. - parameter one: upper-cased first parameter description. @@ -132,7 +129,9 @@ class AutoCapitalizationTests: XCTestCase { - parameter three: inValid third parameter will not be capitalized - parameter four: `code block` will not be capitalized - parameter five: a`nother invalid capitalization - """) + """, + parameters: ["one", "two", "three", "four", "five"] + ) let url = try createTempFolder(content: [ Folder(name: "unit-test.docc", content: [ @@ -168,11 +167,14 @@ class AutoCapitalizationTests: XCTestCase { } func testReturnsCapitalization() throws { - let symbolGraph = makeSymbolGraph(docComment: """ + let symbolGraph = makeSymbolGraph( + docComment: """ Some symbol description. - Returns: string, first word should have been capitalized here. - """) + """, + parameters: [] + ) let url = try createTempFolder(content: [ Folder(name: "unit-test.docc", content: [ From dcf2f402fd26a6633b77c4f37dee803804beda2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 24 Apr 2024 17:41:46 +0200 Subject: [PATCH 12/13] Fix test that was expecting the wrong number of diagnostics --- .../DocumentationContext/DocumentationContextTests.swift | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift b/Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift index 0991134048..ecbd88f093 100644 --- a/Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift +++ b/Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift @@ -4472,8 +4472,8 @@ let expected = """ // "Log a hello world message. This line contains an ``invalid`` link." let (_, context) = try testBundleAndContext(named: "ObjCFrameworkWithInvalidLink") let problems = context.problems - if FeatureFlags.current.isExperimentalParametersAndReturnsValidationEnabled { - XCTAssertEqual(5, problems.count) + if FeatureFlags.current.isParametersAndReturnsValidationEnabled { + XCTAssertEqual(4, problems.count) } else { XCTAssertEqual(1, problems.count) } From d870fbe58d1638726f11b660185417f27ff1f3d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20R=C3=B6nnqvist?= Date: Wed, 24 Apr 2024 18:13:37 +0200 Subject: [PATCH 13/13] Add license comment to new documentation article --- .../documenting-api-with-different-language-representations.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md b/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md index 7357c4bdce..3f9db27dfd 100644 --- a/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md +++ b/Sources/docc/DocCDocumentation.docc/documenting-api-with-different-language-representations.md @@ -59,3 +59,5 @@ DocC automatically adds a generic description for the "error" parameter and exte If you want to customize this documentation you can manually document the "error" parameter and return value. Doing so won't change the Swift version of that symbol's page. DocC will still hide the parameter and return value documentation that doesn't apply to each source language's version of that symbol's page. + +