Enable "mentioned in" feature by default (#1114)

* Enable "mentioned in" feature by default

* Briefly document the "mentioned in" links feature

Author: d-ronnqvist

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -681,7 +681,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,

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<CodableContentSection?>? {
-        guard FeatureFlags.current.isExperimentalMentionedInEnabled else {
+        guard FeatureFlags.current.isMentionedInEnabled else {
             return nil
         }
 

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

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

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.

Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md

@@ -13,6 +13,17 @@ DocC supports the following link types to enable navigation between pages:
 | Tutorial | Links to a tutorial in your documentation catalog.
 | Web      | Links to an external URL.
 
+When you link to a symbol from an article's content, DocC automatically creates a "mentioned in" link from mentioned symbol's page to the article that mentioned the symbol.
+These "mentioned in" links helps the reader find conceptual content that put a specific symbol in context or that describe how to accomplish some task using that symbol.
+
+DocC only creates "mentioned in" links when an _article_ links to a symbol and only when that link appears in the article's _content_.
+Links in topic groups---that organize your documentation into a hierarchy of topics and subtopics---doesn't produce "mentioned in" links.
+For more information about topic groups, see <doc:adding-structure-to-your-documentation-pages>.  
+
+> Earlier Versions:
+> Before Swift-DocC 6.2, automatic "mentioned in" links require that you pass the `--enable-experimental-mentioned-in` command line flag to `docc`. 
+> This flag is available as of Swift-DocC 6.0. 
+
 ### Navigate to a Symbol
 
 To add a link to a symbol in your module, wrap the symbol's name in a set of double backticks (\`\`):

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,

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)
 

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.