Improve generate-manual error descriptions (#663)

Adds a human readable description to `GenerateManualError` and updates
the non-zero exit code error to include stderr to aid debugging.

Fixes: #653

Author: rauhul

Tools/generate-manual/Extensions/Process+SimpleAPI.swift

@@ -14,16 +14,24 @@ import Foundation
 enum SubprocessError: Swift.Error, LocalizedError, CustomStringConvertible {
   case missingExecutable(url: URL)
   case failedToLaunch(error: Swift.Error)
-  case nonZeroExitCode(code: Int)
+  case nonZeroExitCode(code: Int, stderr: String?)
 
   var description: String {
     switch self {
     case .missingExecutable(let url):
       return "No executable at '\(url.standardizedFileURL.path)'."
     case .failedToLaunch(let error):
       return "Couldn't run command process. \(error.localizedDescription)"
-    case .nonZeroExitCode(let code):
-      return "Process returned non-zero exit code '\(code)'."
+    case .nonZeroExitCode(let code, let stderr):
+      var description = "Process returned non-zero exit code '\(code)'."
+      if let stderr = stderr {
+        description.append(
+          """
+           Standard error:
+          \(stderr)
+          """)
+      }
+      return description
     }
   }
 
@@ -48,7 +56,8 @@ func executeCommand(
 
   let output = Pipe()
   process.standardOutput = output
-  process.standardError = FileHandle.nullDevice
+  let error = Pipe()
+  process.standardError = error
 
   if #available(macOS 10.13, *) {
     do {
@@ -60,10 +69,15 @@ func executeCommand(
     process.launch()
   }
   let outputData = output.fileHandleForReading.readDataToEndOfFile()
+  let errorData = error.fileHandleForReading.readDataToEndOfFile()
   process.waitUntilExit()
 
   guard process.terminationStatus == 0 else {
-    throw SubprocessError.nonZeroExitCode(code: Int(process.terminationStatus))
+    let errorActual = String(data: errorData, encoding: .utf8)?
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    throw SubprocessError.nonZeroExitCode(
+      code: Int(process.terminationStatus),
+      stderr: errorActual)
   }
 
   let outputActual = String(data: outputData, encoding: .utf8)?

Tools/generate-manual/GenerateManual.swift

@@ -13,14 +13,30 @@ import ArgumentParser
 import ArgumentParserToolInfo
 import Foundation
 
+enum GenerateManualError: Error {
+  case failedToRunSubprocess(error: Error)
+  case unableToParseToolOutput(error: Error)
+  case unsupportedDumpHelpVersion(expected: Int, found: Int)
+  case failedToGenerateManualPages(error: Error)
+}
+
+extension GenerateManualError: CustomStringConvertible {
+  var description: String {
+    switch self {
+    case let .failedToRunSubprocess(error):
+      "Failed to run subprocess: \(error)"
+    case let .unableToParseToolOutput(error):
+      "Failed to parse tool output: \(error)"
+    case let .unsupportedDumpHelpVersion(expected, found):
+      "Unsupported dump help version, expected '\(expected)' but found: '\(found)'"
+    case let .failedToGenerateManualPages(error):
+      "Failed to generated manual pages: \(error)"
+    }
+  }
+}
+
 @main
 struct GenerateManual: ParsableCommand {
-  enum Error: Swift.Error {
-    case failedToRunSubprocess(error: Swift.Error)
-    case unableToParseToolOutput(error: Swift.Error)
-    case unsupportedDumpHelpVersion(expected: Int, found: Int)
-    case failedToGenerateManualPages(error: Swift.Error)
-  }
 
   static let configuration = CommandConfiguration(
     commandName: "generate-manual",
@@ -70,25 +86,25 @@ struct GenerateManual: ParsableCommand {
       let output = try executeCommand(executable: tool, arguments: ["--experimental-dump-help"])
       data = output.data(using: .utf8) ?? Data()
     } catch {
-      throw Error.failedToRunSubprocess(error: error)
+      throw GenerateManualError.failedToRunSubprocess(error: error)
     }
 
     do {
       let toolInfoThin = try JSONDecoder().decode(ToolInfoHeader.self, from: data)
       guard toolInfoThin.serializationVersion == 0 else {
-        throw Error.unsupportedDumpHelpVersion(
+        throw GenerateManualError.unsupportedDumpHelpVersion(
           expected: 0,
           found: toolInfoThin.serializationVersion)
       }
     } catch {
-      throw Error.unableToParseToolOutput(error: error)
+      throw GenerateManualError.unableToParseToolOutput(error: error)
     }
 
     let toolInfo: ToolInfoV0
     do {
       toolInfo = try JSONDecoder().decode(ToolInfoV0.self, from: data)
     } catch {
-      throw Error.unableToParseToolOutput(error: error)
+      throw GenerateManualError.unableToParseToolOutput(error: error)
     }
 
     do {
@@ -100,7 +116,7 @@ struct GenerateManual: ParsableCommand {
           savingTo: URL(fileURLWithPath: outputDirectory))
       }
     } catch {
-      throw Error.failedToGenerateManualPages(error: error)
+      throw GenerateManualError.failedToGenerateManualPages(error: error)
     }
   }