Improve docs

README.md

@@ -15,21 +15,29 @@ let docs = Path.home/"Documents"
 // paths are *always* absolute thus avoiding common bugs
 let path = Path(userInput) ?? Path.cwd/userInput
 
-// chainable syntax so you have less boilerplate
+// elegant, chainable syntax
 try Path.home.join("foo").mkdir().join("bar").touch().chmod(0o555)
 
-// easy file-management
-try Path.root.join("foo").copy(to: Path.root/"bar")
+// sensible considerations
+try Path.home.join("bar").mkdir()
+try Path.home.join("bar").mkdir()  // doesn’t throw ∵ we already have the desired result
 
-// careful API to avoid common bugs
-try Path.root.join("foo").copy(into: Path.root.mkdir("bar"))
-// ^^ other libraries would make the above `to:` form handle both these cases
-// but that can easily lead to bugs where you accidentally write files that
-// were meant to be directory destinations
+// easy file-management
+let bar = try Path.root.join("foo").copy(to: Path.root/"bar")
+print(bar)         // => /bar
+print(bar.isFile)  // => true
+
+// careful API considerations so as to avoid common bugs
+let foo = try Path.root.join("foo").copy(into: Path.root.mkdir("bar"))
+print(foo)         // => /bar/foo
+print(foo.isFile)  // => true
+
+// A practical example: installing a helper executable
+try Bundle.resources.join("helper").copy(into: Path.home.join(".local/bin").mkpath()).chmod(0o500)
 ```
 
-We emphasize safety and correctness, just like Swift, and also just
-like Swift, we provide a thoughtful and comprehensive (yet concise) API.
+We emphasize safety and correctness, just like Swift, and also (again like
+Swift), we provide a thoughtful and comprehensive (yet concise) API.
 
 # Support mxcl
 

Sources/Extensions.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// Extensions on Foundation’s `Bundle` so you get `Path` rather than `String` or `URL`.
 public extension Bundle {
     /// Returns the path for requested resource in this bundle.
     func path(forResource: String, ofType: String?) -> Path? {
@@ -24,6 +25,7 @@ public extension Bundle {
     }
 }
 
+/// Extensions on `String` that work with `Path` rather than `String` or `URL`
 public extension String {
     /// Initializes this `String` with the contents of the provided path.
     @inlinable
@@ -40,6 +42,7 @@ public extension String {
     }
 }
 
+/// Extensions on `Data` that work with `Path` rather than `String` or `URL`
 public extension Data {
     /// Initializes this `Data` with the contents of the provided path.
     @inlinable

Sources/Path+Codable.swift

@@ -1,10 +1,12 @@
 import Foundation
 
+/// Provided for relative-path coding. See the instructions in our `README`.
 public extension CodingUserInfoKey {
     /// If set paths are encoded as relative to this path.
     static let relativePath = CodingUserInfoKey(rawValue: "dev.mxcl.Path.relative")!
 }
 
+/// Provided for relative-path coding. See the instructions in our `README`.
 extension Path: Codable {
     public init(from decoder: Decoder) throws {
         let value = try decoder.singleValueContainer().decode(String.self)

Sources/Path+FileManager.swift

@@ -22,6 +22,9 @@ public extension Path {
      Copies a file into a directory
 
      If the destination does not exist, this function creates the directory first.
+    
+        // Create ~/.local/bin, copy `ls` there and make the new copy executable
+        try Path.root.join("bin/ls").copy(into: Path.home.join(".local/bin").mkpath()).chmod(0o500)
 
      - Note: `throws` if `into` is a file.
      - Parameter into: Destination directory

Sources/Path.swift

@@ -10,7 +10,7 @@ import Foundation
      let p3 = Path.cwd/relativePathString
      let p4 = Path(userInput) ?? Path.cwd/userInput
 
- - Note: There may not be an actual filename at the path.
+ - Note: There may not be an actual filesystem entry at the path.
  */
 public struct Path: Equatable, Hashable, Comparable {
     /// The underlying filesystem path
@@ -113,7 +113,7 @@ public struct Path: Equatable, Hashable, Comparable {
 
      - Parameter pathComponent: The string to join with this path.
      - Returns: A new joined path.
-     - SeeAlso: /(:Path,:String)
+     - SeeAlso: `/(_:, _:)`
      */
     public func join<S>(_ pathComponent: S) -> Path where S: StringProtocol {
         //TODO standardizingPath does more than we want really (eg tilde expansion)
@@ -154,7 +154,7 @@ public struct Path: Equatable, Hashable, Comparable {
  - Parameter lhs: The base path to join with `rhs`.
  - Parameter rhs: The string to join with this `lhs`.
  - Returns: A new joined path.
- - SeeAlso: Path.join(_:)
+ - SeeAlso: `Path.join(_:)`
  */
 @inlinable
 public func /<S>(lhs: Path, rhs: S) -> Path where S: StringProtocol {