Merge pull request #1394 from MrNickBarker/master

[SR-6347] Added "SEE ALSO" to --help for Swift commands

Author: hartbit

Sources/Commands/SwiftBuildTool.swift

@@ -37,7 +37,8 @@ public class SwiftBuildTool: SwiftTool<BuildToolOptions> {
             toolName: "build",
             usage: "[options]",
             overview: "Build sources into binary products",
-            args: args
+            args: args,
+            seeAlso: type(of: self).otherToolNames()
         )
     }
 
@@ -178,3 +179,9 @@ fileprivate extension BuildSubset {
         }
     }
 }
+
+extension SwiftBuildTool: ToolName {
+    static var toolName: String {
+        return "swift build"
+    }
+}

Sources/Commands/SwiftPackageTool.swift

@@ -37,7 +37,8 @@ public class SwiftPackageTool: SwiftTool<PackageToolOptions> {
             toolName: "package",
             usage: "[options] subcommand",
             overview: "Perform operations on Swift packages",
-            args: args
+            args: args,
+            seeAlso: type(of: self).otherToolNames()
         )
     }
     override func runImpl() throws {
@@ -470,3 +471,9 @@ extension PackageToolOptions.CompletionToolMode: StringEnumArgument {
         ])
     }
 }
+
+extension SwiftPackageTool: ToolName {
+    static var toolName: String {
+        return "swift package"
+    }
+}

Sources/Commands/SwiftRunTool.swift

@@ -89,7 +89,8 @@ public class SwiftRunTool: SwiftTool<RunToolOptions> {
             toolName: "run",
             usage: "[options] [executable [arguments ...]]",
             overview: "Build and run an executable product",
-            args: args
+            args: args,
+            seeAlso: type(of: self).otherToolNames()
         )
     }
 
@@ -187,3 +188,8 @@ public class SwiftRunTool: SwiftTool<RunToolOptions> {
     }
 }
 
+extension SwiftRunTool: ToolName {
+    static var toolName: String {
+        return "swift run"
+    }
+}

Sources/Commands/SwiftTestTool.swift

@@ -115,7 +115,8 @@ public class SwiftTestTool: SwiftTool<TestToolOptions> {
             toolName: "test",
             usage: "[options]",
             overview: "Build and run tests",
-            args: args
+            args: args,
+            seeAlso: type(of: self).otherToolNames()
         )
     }
 
@@ -620,3 +621,9 @@ fileprivate extension Sequence where Iterator.Element == TestSuite {
         }
     }
 }
+
+extension SwiftTestTool: ToolName {
+    static var toolName: String {
+        return "swift test"
+    }
+}

Sources/Commands/SwiftTool.swift

@@ -104,6 +104,17 @@ private class ToolWorkspaceDelegate: WorkspaceDelegate {
     }
 }
 
+protocol ToolName {
+    static var toolName: String { get }
+}
+
+extension ToolName {
+    static func otherToolNames() -> String {
+        let allTools: [ToolName.Type] = [SwiftBuildTool.self, SwiftRunTool.self, SwiftPackageTool.self, SwiftTestTool.self]
+        return  allTools.filter({ $0 != self }).map({ $0.toolName }).joined(separator: ", ")
+    }
+}
+
 public class SwiftTool<Options: ToolOptions> {
     /// The original working directory.
     let originalWorkingDirectory: AbsolutePath
@@ -149,15 +160,16 @@ public class SwiftTool<Options: ToolOptions> {
     /// Create an instance of this tool.
     ///
     /// - parameter args: The command line arguments to be passed to this tool.
-    public init(toolName: String, usage: String, overview: String, args: [String]) {
+    public init(toolName: String, usage: String, overview: String, args: [String], seeAlso: String? = nil) {
         // Capture the original working directory ASAP.
         originalWorkingDirectory = currentWorkingDirectory
 
         // Create the parser.
         parser = ArgumentParser(
             commandName: "swift \(toolName)",
             usage: usage,
-            overview: overview)
+            overview: overview,
+            seeAlso: seeAlso)
 
         // Create the binder.
         let binder = ArgumentBinder<Options>()

Sources/Utility/ArgumentParser.swift

@@ -597,6 +597,9 @@ public final class ArgumentParser {
 
     /// Overview text of this parser.
     let overview: String
+    
+    /// See more text of this parser.
+    let seeAlso: String?
 
     /// If this parser is a subparser.
     private let isSubparser: Bool
@@ -613,11 +616,13 @@ public final class ArgumentParser {
     ///   Otherwise, first command line argument will be used.
     ///   - usage: The "usage" line of the generated usage text.
     ///   - overview: The "overview" line of the generated usage text.
-    public init(commandName: String? = nil, usage: String, overview: String) {
+    ///   - seeAlso: The "see also" line of generated usage text.
+    public init(commandName: String? = nil, usage: String, overview: String, seeAlso: String? = nil) {
         self.isSubparser = false
         self.commandName = commandName
         self.usage = usage
         self.overview = overview
+        self.seeAlso = seeAlso
     }
 
     /// Create a subparser with its help text.
@@ -626,6 +631,7 @@ public final class ArgumentParser {
         self.commandName = nil
         self.usage = ""
         self.overview = overview
+        self.seeAlso = nil
     }
 
     /// Adds an option to the parser.
@@ -901,6 +907,12 @@ public final class ArgumentParser {
                 print(formatted: argument.name, usage: usage, on: stream)
             }
         }
+        
+        if let seeAlso = seeAlso {
+            stream <<< "\n\n"
+            stream <<< "SEE ALSO: \(seeAlso)"
+        }
+        
         stream <<< "\n"
         stream.flush()
     }

Tests/CommandsTests/BuildToolTests.swift

@@ -23,6 +23,10 @@ final class BuildToolTests: XCTestCase {
         XCTAssert(try execute(["-help"]).contains("USAGE: swift build"))
     }
 
+    func testSeeAlso() throws {
+        XCTAssert(try execute(["--help"]).contains("SEE ALSO: swift run, swift package, swift test"))
+    }
+
     func testVersion() throws {
         XCTAssert(try execute(["--version"]).contains("Swift Package Manager"))
     }

Tests/CommandsTests/PackageToolTests.swift

@@ -29,6 +29,10 @@ final class PackageToolTests: XCTestCase {
         XCTAssert(try execute(["--help"]).contains("USAGE: swift package"))
     }
 
+    func testSeeAlso() throws {
+        XCTAssert(try execute(["--help"]).contains("SEE ALSO: swift build, swift run, swift test"))
+    }
+
     func testVersion() throws {
         XCTAssert(try execute(["--version"]).contains("Swift Package Manager"))
     }

Tests/CommandsTests/RunToolTests.swift

@@ -24,6 +24,10 @@ final class RunToolTests: XCTestCase {
         XCTAssert(try execute(["--help"]).contains("USAGE: swift run [options] [executable [arguments ...]]"))
     }
 
+    func testSeeAlso() throws {
+        XCTAssert(try execute(["--help"]).contains("SEE ALSO: swift build, swift package, swift test"))
+    }
+
     func testVersion() throws {
         XCTAssert(try execute(["--version"]).contains("Swift Package Manager"))
     }

Tests/CommandsTests/TestToolTests.swift

@@ -22,6 +22,10 @@ final class TestToolTests: XCTestCase {
         XCTAssert(try execute(["--help"]).contains("USAGE: swift test"))
     }
 
+    func testSeeAlso() throws {
+        XCTAssert(try execute(["--help"]).contains("SEE ALSO: swift build, swift run, swift package"))
+    }
+
     func testVersion() throws {
         XCTAssert(try execute(["--version"]).contains("Swift Package Manager"))
     }