Add include inherited docs option to symbol graph generation (#9132)

* Use this option from the dump symbol graph command to set the swift
build build setting
* Add this option to the symbol graph generation option from command
plugins
* Update the test conditions to better reflect the required toolchain
version

Author: cmcgee1024

Sources/Commands/PackageCommands/DumpCommands.swift

@@ -60,10 +60,10 @@ struct DumpSymbolGraph: AsyncSwiftCommand {
             BuildOutput.SymbolGraphOptions(
                 prettyPrint: prettyPrint,
                 minimumAccessLevel: .accessLevel(minimumAccessLevel),
+                includeInheritedDocs: !skipInheritedDocs,
                 includeSynthesized: !skipSynthesizedMembers,
                 includeSPI: includeSPISymbols,
                 emitExtensionBlocks: extensionBlockSymbolBehavior != .omitExtensionBlockSymbols,
-                // TODO skip inherited docs
             )
         ), .buildPlan])
 

Sources/Commands/Utilities/PluginDelegate.swift

@@ -443,7 +443,7 @@ final class PluginDelegate: PluginInvocationDelegate {
             case .open:
                 symbolGraphExtractor.minimumAccessLevel = .open
             }
-            symbolGraphExtractor.skipInheritedDocs = true
+            symbolGraphExtractor.skipInheritedDocs = !options.includeInheritedDocs
             symbolGraphExtractor.includeSPISymbols = options.includeSPI
             symbolGraphExtractor.emitExtensionBlockSymbols = options.emitExtensionBlocks
 
@@ -489,6 +489,7 @@ extension BuildOutput {
     static func symbolGraph(_ options: PluginInvocationSymbolGraphOptions) -> BuildOutput {
         return .symbolGraph(SymbolGraphOptions(
                 minimumAccessLevel: .accessLevel(options.minimumAccessLevel),
+                includeInheritedDocs: options.includeInheritedDocs,
                 includeSynthesized: options.includeSynthesized,
                 includeSPI: options.includeSPI,
                 emitExtensionBlocks: options.emitExtensionBlocks
@@ -497,7 +498,7 @@ extension BuildOutput {
 }
 
 fileprivate extension BuildOutput.SymbolGraphAccessLevel {
-    fileprivate static func accessLevel(_ accessLevel: PluginInvocationSymbolGraphOptions.AccessLevel) -> BuildOutput.SymbolGraphAccessLevel {
+    static func accessLevel(_ accessLevel: PluginInvocationSymbolGraphOptions.AccessLevel) -> BuildOutput.SymbolGraphAccessLevel {
         return switch accessLevel {
         case .private:
             .private

Sources/PackagePlugin/PackageManagerProxy.swift

@@ -293,6 +293,9 @@ public struct PackageManager {
             case `private`, `fileprivate`, `internal`, `package`, `public`, open
         }
 
+        /// A Boolean value that indicates whether to include inherited docs from class or protocol members.
+        public var includeInheritedDocs: Bool
+
         /// A Boolean value that indicates whether to include synthesized members.
         public var includeSynthesized: Bool
 
@@ -305,16 +308,19 @@ public struct PackageManager {
         /// Creates a new set of options for returning the symbol graph for a target.
         /// - Parameters:
         ///   - minimumAccessLevel: The minimum access level of symbols to return.
+        ///   - includeInheritedDocs: A Boolean value that indicates whether to include inheirted docs from protocol or class members.
         ///   - includeSynthesized: A Boolean value that indicates whether to include synthesized members.
         ///   - includeSPI: A Boolean value that indicates whether to include symbols marked as SPI.
         ///   - emitExtensionBlocks: A Boolean value that indicates whether to emit symbols for extensions to external types.
         public init(
             minimumAccessLevel: AccessLevel = .public,
+            includeInheritedDocs: Bool = true,
             includeSynthesized: Bool = false,
             includeSPI: Bool = false,
             emitExtensionBlocks: Bool = false
         ) {
             self.minimumAccessLevel = minimumAccessLevel
+            self.includeInheritedDocs = includeInheritedDocs
             self.includeSynthesized = includeSynthesized
             self.includeSPI = includeSPI
             self.emitExtensionBlocks = emitExtensionBlocks
@@ -507,6 +513,7 @@ extension PackageManager.TestResult.TestTarget.TestCase.Test.Result {
 extension PluginToHostMessage.SymbolGraphOptions {
     fileprivate init(_ options: PackageManager.SymbolGraphOptions) {
         self.minimumAccessLevel = .init(options.minimumAccessLevel)
+        self.includeInheritedDocs = options.includeInheritedDocs
         self.includeSynthesized = options.includeSynthesized
         self.includeSPI = options.includeSPI
         self.emitExtensionBlocks = options.emitExtensionBlocks

Sources/PackagePlugin/PluginMessages.swift

@@ -398,6 +398,7 @@ enum PluginToHostMessage: Codable {
             enum AccessLevel: String, Codable {
                 case `private`, `fileprivate`, `internal`, `package`, `public`, `open`
             }
+            var includeInheritedDocs: Bool? = true
             var includeSynthesized: Bool
             var includeSPI: Bool
             var emitExtensionBlocks: Bool

Sources/SPMBuildCore/BuildSystem/BuildSystem.swift

@@ -45,19 +45,22 @@ public enum BuildOutput: Equatable {
     public struct SymbolGraphOptions: Equatable {
         public var prettyPrint: Bool
         public var minimumAccessLevel: SymbolGraphAccessLevel
+        public var includeInheritedDocs: Bool
         public var includeSynthesized: Bool
         public var includeSPI: Bool
         public var emitExtensionBlocks: Bool
 
         public init(
             prettyPrint: Bool = false,
             minimumAccessLevel: SymbolGraphAccessLevel,
+            includeInheritedDocs: Bool,
             includeSynthesized: Bool,
             includeSPI: Bool,
             emitExtensionBlocks: Bool
         ) {
             self.prettyPrint = prettyPrint
             self.minimumAccessLevel = minimumAccessLevel
+            self.includeInheritedDocs = includeInheritedDocs
             self.includeSynthesized = includeSynthesized
             self.includeSPI = includeSPI
             self.emitExtensionBlocks = emitExtensionBlocks

Sources/SPMBuildCore/Plugins/PluginInvocation.swift

@@ -954,6 +954,7 @@ public struct PluginInvocationSymbolGraphOptions {
     public enum AccessLevel: String {
         case `private`, `fileprivate`, `internal`, `package`, `public`, `open`
     }
+    public var includeInheritedDocs: Bool
     public var includeSynthesized: Bool
     public var includeSPI: Bool
     public var emitExtensionBlocks: Bool
@@ -1219,6 +1220,7 @@ fileprivate extension HostToPluginMessage.TestResult.TestTarget.TestCase.Test.Re
 fileprivate extension PluginInvocationSymbolGraphOptions {
     init(_ options: PluginToHostMessage.SymbolGraphOptions) {
         self.minimumAccessLevel = .init(options.minimumAccessLevel)
+        self.includeInheritedDocs = options.includeInheritedDocs ?? true
         self.includeSynthesized = options.includeSynthesized
         self.includeSPI = options.includeSPI
         self.emitExtensionBlocks = options.emitExtensionBlocks

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

@@ -905,6 +905,10 @@ public final class SwiftBuildSystem: SPMBuildCore.BuildSystem {
                 settings["DOCC_EXTRACT_EXTENSION_SYMBOLS"] = "YES"
             }
 
+            if !symbolGraphOptions.includeInheritedDocs {
+                settings["DOCC_SKIP_INHERITED_DOCS"] = "YES"
+            }
+
             if !symbolGraphOptions.includeSynthesized {
                 settings["DOCC_SKIP_SYNTHESIZED_MEMBERS"] = "YES"
             }

Tests/CommandsTests/PackageCommandTests.swift

@@ -6025,8 +6025,13 @@ struct PackageCommandTests {
                                         ? context.package.targets
                                         : try context.package.targets(named: targetNames)
                                     for target in targets {
+                                        #if compiler(>=6.3)
+                                        let symbolGraph = try packageManager.getSymbolGraph(for: target,
+                                            options: .init(minimumAccessLevel: .public, includeInheritedDocs: false))
+                                        #else
                                         let symbolGraph = try packageManager.getSymbolGraph(for: target,
                                             options: .init(minimumAccessLevel: .public))
+                                        #endif
                                         print("\\(target.name): \\(symbolGraph.directoryPath)")
                                     }
                                 }
@@ -6083,8 +6088,15 @@ struct PackageCommandTests {
                     }
                 }
             } when: {
-                (ProcessInfo.hostOperatingSystem == .windows && data.buildSystem == .swiftbuild)
-                || !CiEnvironment.runningInSmokeTestPipeline
+                let shouldSkip: Bool = (ProcessInfo.hostOperatingSystem == .windows && data.buildSystem == .swiftbuild)
+                    || !CiEnvironment.runningInSmokeTestPipeline
+
+                #if compiler(>=6.3)
+                    return shouldSkip
+                #else
+                    // Symbol graph generation options are only available in 6.3 toolchain or later for swift build
+                    return shouldSkip || data.buildSystem == .swiftbuild
+                #endif
             }
         }
 

Tests/FunctionalTests/TraitTests.swift

@@ -591,7 +591,14 @@ struct TraitTests {
                 }
             }
         } when: {
-            !CiEnvironment.runningInSmokeTestPipeline
+            let shouldSkip = !CiEnvironment.runningInSmokeTestPipeline
+
+            #if compiler(>=6.3)
+                return shouldSkip
+            #else
+                // Symbol graph generation options are only available in 6.3 toolchain or later for swift build
+                return shouldSkip || buildSystem == .swiftbuild
+            #endif
         }
     }