Improve docs

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 {