Docs tweaks

[ci skip]

README.md

@@ -1,7 +1,7 @@
-# Path.swift ![badge-platforms] ![badge-languages] [![Build Status](https://travis-ci.com/mxcl/Path.swift.svg)](https://travis-ci.com/mxcl/Path.swift)
+# Path.swift ![badge-platforms] ![badge-languages][] [![Build Status](https://travis-ci.com/mxcl/Path.swift.svg)](https://travis-ci.com/mxcl/Path.swift)
 
-A file-system pathing library focused on developer experience and robust
+A file-system pathing library focused on developer experience and robust end
-end‐results.
+results.
 
 ```swift
 import Path
@@ -32,7 +32,10 @@ let foo = try Path.root.join("foo").copy(into: Path.root.join("bar").mkdir())
 print(foo)         // => /bar/foo
 print(foo.isFile)  // => true
 
-// A practical example: installing a helper executable
+// we support dynamic members (_use_sparingly_):
+let prefs = Path.home.Library.Preferences
+
+// a practical example: installing a helper executable
 try Bundle.resources.join("helper").copy(into: Path.home.join(".local/bin").mkdir(.p)).chmod(0o500)
 ```
 
@@ -42,8 +45,9 @@ Swift), we provide a thoughtful and comprehensive (yet concise) API.
 # Support mxcl
 
 Hi, I’m Max Howell and I have written a lot of open source software, and
-probably you already use some of it (Homebrew anyone?). Please help me so I
+probably you already use some of it (Homebrew anyone?). I work full-time on
-can continue to make tools and software you need and love. I appreciate it x.
+open source and it’s hard; currently I earn *less* than minimum wage. Please
+help me continue my work, I appreciate it x
 
 <a href="https://www.patreon.com/mxcl">
 	<img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
@@ -134,8 +138,7 @@ bashProfile += "\n\nfoo"
 
 try bashProfile.write(to: Path.home/".bash_profile")
 
-try Bundle.main.resources!.join("foo").copy(to: .home)
+try Bundle.main.resources.join("foo").copy(to: .home)
-// ^^ `-> Path?` because the underlying `Bundle` function is `-> String?`
 ```
 
 ## Directory listings

Sources/Path.swift

@@ -1,7 +1,10 @@
 import Foundation
 
 /**
- Represents a filesystem absolute path.
+ A `Path` represents an absolute path on a filesystem.
+
+ All functions on `Path` are chainable and short to facilitate doing sequences
+ of file operations in a concise manner.
 
  `Path` supports `Codable`, and can be configured to
  [encode paths *relatively*](https://github.com/mxcl/Path.swift/#codable).
@@ -9,9 +12,6 @@ import Foundation
  Sorting a `Sequence` of `Path`s will return the locale-aware sort order, which
  will give you the same order as Finder.
 
- All functions on `Path` are chainable and short to facilitate doing sequences
- of file operations in a concise manner.
-
  Converting from a `String` is a common first step, here are the recommended
  ways to do that:
 
@@ -20,6 +20,11 @@ import Foundation
      let p3 = Path.cwd/relativePathString
      let p4 = Path(userInput) ?? Path.cwd/userInput
 
+ If you are constructing Paths from static-strings we provide support for
+ dynamic members:
+
+     let p1 = Path.root.usr.bin.ls  // => /usr/bin/ls
+
  - Note: There may not be an actual filesystem entry at the path. The underlying
    representation for `Path` is `String`.
  */
@@ -37,6 +42,12 @@ public struct Path: Equatable, Hashable, Comparable {
         self.init(string: (description as NSString).standardizingPath)
     }
 
+    /// :nodoc:
+    public subscript(dynamicMember pathComponent: String) -> Path {
+        let str = (string as NSString).appendingPathComponent(pathComponent)
+        return Path(string: str)
+    }
+
 //MARK: Properties
 
     /// The underlying filesystem path
@@ -47,12 +58,6 @@ public struct Path: Equatable, Hashable, Comparable {
         return URL(fileURLWithPath: string)
     }
 
-    /// Facilitates constructing paths for static strings
-    public subscript(dynamicMember pathComponent: String) -> Path {
-        let str = (string as NSString).appendingPathComponent(pathComponent)
-        return Path(string: str)
-    }
-
     /**
      Returns the parent directory for this path.