diff --git a/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift b/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift index d76bfa4126..badc23af89 100644 --- a/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift +++ b/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift @@ -668,7 +668,7 @@ public class DocumentationContext { for result in results.sync({ $0 }) { documentationCache[result.reference] = result.node - if FeatureFlags.current.isExperimentalMentionedInEnabled { + if FeatureFlags.current.isMentionedInEnabled { // Record symbol links as symbol "mentions" for automatic cross references // on rendered symbol documentation. if let article = result.node.semantic as? Article, diff --git a/Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/MentionsSectionTranslator.swift b/Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/MentionsSectionTranslator.swift index a21935dd83..e629a4b4a8 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/MentionsSectionTranslator.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/MentionsSectionTranslator.swift @@ -15,7 +15,7 @@ struct MentionsSectionTranslator: RenderSectionTranslator { } func translateSection(for symbol: Symbol, renderNode: inout RenderNode, renderNodeTranslator: inout RenderNodeTranslator) -> VariantCollection? { - guard FeatureFlags.current.isExperimentalMentionedInEnabled else { + guard FeatureFlags.current.isMentionedInEnabled else { return nil } diff --git a/Sources/SwiftDocC/Utility/FeatureFlags.swift b/Sources/SwiftDocC/Utility/FeatureFlags.swift index 8051d44015..ae409c74d7 100644 --- a/Sources/SwiftDocC/Utility/FeatureFlags.swift +++ b/Sources/SwiftDocC/Utility/FeatureFlags.swift @@ -23,9 +23,14 @@ public struct FeatureFlags: Codable { /// Whether or not experimental support for combining overloaded symbol pages is enabled. public var isExperimentalOverloadedSymbolPresentationEnabled = false - /// Whether experimental support for automatically rendering links on symbol documentation to articles - /// that mention that symbol. - public var isExperimentalMentionedInEnabled = false + /// Whether support for automatically rendering links on symbol documentation to articles that mention that symbol is enabled. + public var isMentionedInEnabled = true + + @available(*, deprecated, renamed: "isMentionedInEnabled", message: "Use 'isMentionedInEnabled' instead. This deprecated API will be removed after 6.2 is released") + public var isExperimentalMentionedInEnabled: Bool { + get { isMentionedInEnabled } + set { isMentionedInEnabled = newValue } + } /// Whether or not support for validating parameters and return value documentation is enabled. public var isParametersAndReturnsValidationEnabled = true diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift index 8115032d96..ffe0344453 100644 --- a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift +++ b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift @@ -23,7 +23,7 @@ extension ConvertAction { FeatureFlags.current.isExperimentalDeviceFrameSupportEnabled = convert.enableExperimentalDeviceFrameSupport FeatureFlags.current.isExperimentalLinkHierarchySerializationEnabled = convert.enableExperimentalLinkHierarchySerialization FeatureFlags.current.isExperimentalOverloadedSymbolPresentationEnabled = convert.enableExperimentalOverloadedSymbolPresentation - FeatureFlags.current.isExperimentalMentionedInEnabled = convert.enableExperimentalMentionedIn + FeatureFlags.current.isMentionedInEnabled = convert.enableMentionedIn FeatureFlags.current.isParametersAndReturnsValidationEnabled = convert.enableParametersAndReturnsValidation // If the user-provided a URL for an external link resolver, attempt to diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift index fd2cfe99f4..9c8aa59a8d 100644 --- a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift +++ b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift @@ -503,11 +503,17 @@ extension Docc { var enableExperimentalOverloadedSymbolPresentation = false @Flag( - name: .customLong("enable-experimental-mentioned-in"), + name: .customLong("mentioned-in"), + inversion: .prefixedEnableDisable, help: ArgumentHelp("Render a section on symbol documentation which links to articles that mention that symbol", discussion: """ Validates and filters symbols' parameter and return value documentation based on the symbol's function signature in each language representation. """) ) + var enableMentionedIn = true + + // This flag only exist to allow developers to pass the previous '--enable-experimental-...' flag without errors. + @Flag(name: .customLong("enable-experimental-mentioned-in"), help: .hidden) + @available(*, deprecated, message: "This deprecated API will be removed after 6.2 is released") var enableExperimentalMentionedIn = false @Flag( @@ -536,6 +542,7 @@ extension Docc { 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("enable-experimental-mentioned-in", message: "This flag has no effect. Automatic mentioned in sections is enabled by default.") Convert.warnAboutDeprecatedOptionIfNeeded("index", message: "Use '--emit-lmdb-index' indead.") emitLMDBIndex = emitLMDBIndex } @@ -598,9 +605,14 @@ extension Docc { /// A user-provided value that is true if the user enables experimental automatically generated "mentioned in" /// links on symbols. + public var enableMentionedIn: Bool { + get { featureFlags.enableMentionedIn } + set { featureFlags.enableMentionedIn = newValue } + } + @available(*, deprecated, renamed: "enableMentionedIn", message: "Use 'enableMentionedIn' instead. This deprecated API will be removed after 6.2 is released") public var enableExperimentalMentionedIn: Bool { - get { featureFlags.enableExperimentalMentionedIn } - set { featureFlags.enableExperimentalMentionedIn = newValue } + get { enableMentionedIn } + set { enableMentionedIn = newValue } } /// A user-provided value that is true if the user enables experimental validation for parameters and return value documentation. diff --git a/Tests/SwiftDocCTests/Rendering/MentionsRenderSectionTests.swift b/Tests/SwiftDocCTests/Rendering/MentionsRenderSectionTests.swift index 893d60c50d..f61244750e 100644 --- a/Tests/SwiftDocCTests/Rendering/MentionsRenderSectionTests.swift +++ b/Tests/SwiftDocCTests/Rendering/MentionsRenderSectionTests.swift @@ -16,7 +16,7 @@ class MentionsRenderSectionTests: XCTestCase { /// Verify that the Mentioned In section is present when a symbol is mentioned, /// pointing to the correct article. func testMentionedInSectionFull() throws { - enableFeatureFlag(\.isExperimentalMentionedInEnabled) + enableFeatureFlag(\.isMentionedInEnabled) let (bundle, context) = try createMentionedInTestBundle() let identifier = ResolvedTopicReference( bundleID: bundle.id, @@ -39,7 +39,7 @@ class MentionsRenderSectionTests: XCTestCase { /// If there are no qualifying mentions of a symbol, the Mentioned In section should not appear. func testMentionedInSectionEmpty() throws { - enableFeatureFlag(\.isExperimentalMentionedInEnabled) + enableFeatureFlag(\.isMentionedInEnabled) let (bundle, context) = try createMentionedInTestBundle() let identifier = ResolvedTopicReference( bundleID: bundle.id, diff --git a/Tests/SwiftDocCTests/Semantics/ArticleSymbolMentionsTests.swift b/Tests/SwiftDocCTests/Semantics/ArticleSymbolMentionsTests.swift index b6d64be2e7..3cb9bb3f7d 100644 --- a/Tests/SwiftDocCTests/Semantics/ArticleSymbolMentionsTests.swift +++ b/Tests/SwiftDocCTests/Semantics/ArticleSymbolMentionsTests.swift @@ -36,10 +36,7 @@ class ArticleSymbolMentionsTests: XCTestCase { XCTAssertEqual(gottenArticle, article) } - /// If the `--enable-mentioned-in` flag is passed, symbol mentions in the test bundle's - /// articles should be recorded. func testSymbolLinkCollectorEnabled() throws { - enableFeatureFlag(\.isExperimentalMentionedInEnabled) let (bundle, context) = try createMentionedInTestBundle() // The test bundle currently only has one article with symbol mentions @@ -61,9 +58,14 @@ class ArticleSymbolMentionsTests: XCTestCase { XCTAssertEqual(mentioningArticle, gottenArticle) } - /// If the `--enable-experimental-mentioned-in` flag is not passed, symbol mentions in the test bundle's - /// articles should not be recorded. func testSymbolLinkCollectorDisabled() throws { + let currentFeatureFlags = FeatureFlags.current + addTeardownBlock { + FeatureFlags.current = currentFeatureFlags + } + FeatureFlags.current.isMentionedInEnabled = false + + let (bundle, context) = try createMentionedInTestBundle() XCTAssertTrue(context.articleSymbolMentions.mentions.isEmpty) diff --git a/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift b/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift index 8cd7e82d45..41027fbba1 100644 --- a/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift +++ b/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift @@ -578,6 +578,24 @@ class ConvertSubcommandTests: XCTestCase { let disabledFlagConvert = try Docc.Convert.parse(["--disable-parameters-and-returns-validation"]) XCTAssertEqual(disabledFlagConvert.enableParametersAndReturnsValidation, false) } + + func testMentionedFeatureFlag() throws { + // The feature is enabled when no flag is passed. + let noFlagConvert = try Docc.Convert.parse([]) + XCTAssertEqual(noFlagConvert.enableMentionedIn, true) + + // It's allowed to pass the previous "--enable-experimental-..." flag. + let oldFlagConvert = try Docc.Convert.parse(["--enable-experimental-mentioned-in"]) + XCTAssertEqual(oldFlagConvert.enableMentionedIn, true) + + // It's allowed to pass the redundant "--enable-..." flag. + let enabledFlagConvert = try Docc.Convert.parse(["--enable-mentioned-in"]) + XCTAssertEqual(enabledFlagConvert.enableMentionedIn, true) + + // Passing the "--disable-..." flag turns of the feature. + let disabledFlagConvert = try Docc.Convert.parse(["--disable-mentioned-in"]) + XCTAssertEqual(disabledFlagConvert.enableMentionedIn, false) + } // This test calls ``ConvertOptions.infoPlistFallbacks._unusedVersionForBackwardsCompatibility`` which is deprecated. // Deprecating the test silences the deprecation warning when running the tests. It doesn't skip the test.