perform some path sanitization over the generated names

The current scheme for the file generation uses the function label,
which uses ':' as a parameter separator.  However, this character is not
valid on all file systems.  This results in partial content generation
on Windows.  Add a sanitization step which replaces "invalid" characters
with `_` instead.  This does not impact the rendering, only the
filenames and the generated URL references between the pages.  With
this, we can generate and link function documentation on Windows.

Author: compnerd

Sources/SwiftDoc/Helpers.swift

@@ -13,10 +13,19 @@ public func path(for symbol: Symbol, with baseURL: String) -> String {
 }
 
 public func path(for identifier: CustomStringConvertible, with baseURL: String) -> String {
-    let url = URL(string: baseURL)?.appendingPathComponent("\(identifier)") ?? URL(string: "\(identifier)")
+    let tail: String = path(for: "\(identifier)")
+    let url = URL(string: baseURL)?.appendingPathComponent(tail) ?? URL(string: tail)
     guard let string = url?.absoluteString else {
         fatalError("Unable to construct path for \(identifier) with baseURL \(baseURL)")
     }
 
     return string
 }
+
+public func path(for identifier: String) -> String {
+    let kReservedCharacters: CharacterSet = [
+      // Windows Reserved Characters
+      "<", ">", ":", "\"", "/", "\\", "|", "?", "*",
+    ]
+    return identifier.components(separatedBy: kReservedCharacters).joined(separator: "_")
+}

Sources/swift-doc/Subcommands/Generate.swift

@@ -121,11 +121,11 @@ extension SwiftDoc {
             let filename: String
             switch format {
             case .commonmark:
-              filename = "\($0.key).md"
+              filename = "\(path(for: $0.key)).md"
             case .html where $0.key == "Home":
               filename = "index.html"
             case .html:
-              filename = "\($0.key)/index.html"
+              filename = "\(path(for: $0.key))/index.html"
             }
 
             let url = outputDirectoryURL.appendingPathComponent(filename)