Limit the number of items in automatic See Also sections (#1043)

* Limit the number of items in automatic See Also sections rdar://134376209 * Make See Also limit externally configurable
swiftlang · Oct 8, 2024 · 79bb1d0 · 79bb1d0
1 parent 37df0ee
commit 79bb1d0
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 2 deletions.
diff --git a/Sources/SwiftDocC/Infrastructure/Topic Graph/AutomaticCuration.swift b/Sources/SwiftDocC/Infrastructure/Topic Graph/AutomaticCuration.swift
@@ -12,6 +12,11 @@ import Foundation
 import Markdown
 import SymbolKit
 
+
+private let automaticSeeAlsoLimit: Int = {
+    ProcessInfo.processInfo.environment["DOCC_AUTOMATIC_SEE_ALSO_LIMIT"].flatMap { Int($0) } ?? 15
+}()
+
 /// A set of functions that add automatic symbol curation to a topic graph.
 public struct AutomaticCuration {
     /// A value type to store an automatically curated task group and its sorting index.
@@ -167,7 +172,8 @@ public struct AutomaticCuration {
         }
 
         func filterReferences(_ references: [ResolvedTopicReference]) -> [ResolvedTopicReference] {
-            references
+            Array(
+                references
                 // Don't include the current node.
                 .filter { $0 != node.reference }
 
@@ -177,6 +183,9 @@ public struct AutomaticCuration {
                         variantsTraits.contains(where: { $0.interfaceLanguage == language.id})
                     })
                 }
+                // Don't create too long See Also sections
+                .prefix(automaticSeeAlsoLimit)
+            )
         }
 
         // Look up the render context first

diff --git a/Tests/SwiftDocCTests/Model/SemaToRenderNodeMultiLanguageTests.swift b/Tests/SwiftDocCTests/Model/SemaToRenderNodeMultiLanguageTests.swift
@@ -11,6 +11,7 @@
 import Foundation
 @testable import SwiftDocC
 import SymbolKit
+import SwiftDocCTestUtilities
 import XCTest
 
 class SemaToRenderNodeMixedLanguageTests: XCTestCase {
@@ -969,7 +970,48 @@ class SemaToRenderNodeMixedLanguageTests: XCTestCase {
         XCTAssertTrue(objCTopicIDs.contains("doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/_MixedLanguageFrameworkVersionNumber"))
         XCTAssertFalse(objCTopicIDs.contains("doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/SwiftOnlyStruct"))
     }
-
+
+    func testAutomaticSeeAlsoSectionElementLimit() throws {
+        let fileSystem = try TestFileSystem(folders: [
+            Folder(name: "unit-test.docc", content: [
+                JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(moduleName: "ModuleName", symbols: (1...50).map {
+                    makeSymbol(id: "symbol-id-\($0)", kind: .class, pathComponents: ["SymbolName\($0)"])
+                })),
+
+                TextFile(name: "ModuleName.md", utf8Content: """
+                # ``ModuleName``
+                
+                A topic section with many elements
+                
+                ## Topics
+                
+                ### Many symbols
+                
+                \((1...50).map { "- ``SymbolName\($0)``" }.joined(separator: "\n"))
+                """),
+            ])
+        ])
+
+        let workspace = DocumentationWorkspace()
+        let context = try DocumentationContext(dataProvider: workspace)
+        try workspace.registerProvider(fileSystem)
+
+        XCTAssert(context.problems.isEmpty, "Unexpected problems: \(context.problems.map(\.diagnostic.summary))")
+        let bundle = try XCTUnwrap(context.registeredBundles.first)
+
+        let converter = DocumentationNodeConverter(bundle: bundle, context: context)
+
+        let moduleReference = try XCTUnwrap(context.soleRootModuleReference)
+        let moduleNode = try converter.convert(context.entity(with: moduleReference))
+        XCTAssertEqual(moduleNode.topicSections.first?.identifiers.count, 50, "The module curates 50 symbols")
+
+        for number in 1...50 {
+            let symbolReference = moduleReference.appendingPath("SymbolName\(number)")
+            let symbolNode = try converter.convert(context.entity(with: symbolReference))
+            XCTAssertEqual(symbolNode.seeAlsoSections.first?.identifiers.count, 15, "The limit is applies to the large See Also section")
+        }
+    }
+
     func renderNodeApplyingObjectiveCVariantOverrides(to renderNode: RenderNode) throws -> RenderNode {
         return try renderNodeApplying(variant: "occ", to: renderNode)
     }