Get out documentation %age up

Sources/Path+ls.swift

@@ -1,14 +1,19 @@
 import Foundation
 
 public extension Path {
+    /// The builder for `Path.find()`
     class Finder {
         fileprivate init(path: Path) {
             self.path = path
         }
 
+        /// The `path` find operations operate on.
         public let path: Path
+        /// The maximum directory depth find operations will dip. Zero means no subdirectories.
         fileprivate(set) public var maxDepth: Int? = nil
+        /// The kinds of filesystem entries find operations will return.
         fileprivate(set) public var kinds: Set<Path.Kind>?
+        /// The file extensions find operations will return. Files *and* directories unless you filter for `kinds`.
         fileprivate(set) public var extensions: Set<String>?
     }
 }
@@ -84,8 +89,6 @@ public extension Path.Finder {
 }
 
 public extension Pathish {
-    //MARK: Directory Listings
-
     /**
      Same as the `ls` command ∴ output is ”shallow” and unsorted.
      - Note: as per `ls`, by default we do *not* return hidden files. Specify `.a` for hidden files.
@@ -105,6 +108,7 @@ public extension Pathish {
         }
     }
 
+    /// Recursively find files under this path. If the path is a file, no files will be found.
     func find() -> Path.Finder {
         return .init(path: Path(self))
     }
@@ -128,7 +132,7 @@ public extension Array where Element == Path {
     }
 }
 
-/// Options for `Path.mkdir(_:)`
+/// Options for `Path.ls(_:)`
 public enum ListDirectoryOptions {
     /// Creates intermediary directories; works the same as `mkdir -p`.
     case a

Sources/Path.swift

@@ -36,6 +36,7 @@ let _realpath = Glibc.realpath
  to the anti-pattern where Path.swift suddenly feels like Javascript otherwise.
 
  - Note: A `Path` does not necessarily represent an actual filesystem entry.
+ - SeeAlso: `Pathish` for most methods you will use on `Path` instances.
  */
 public struct Path: Pathish {
 

Sources/Pathish.swift

@@ -7,6 +7,9 @@ public protocol Pathish: Hashable, Comparable {
 }
 
 public extension Pathish {
+    /// Two `Path`s are equal if their strings are identical. Strings are normalized upon construction, yet
+    /// if the files are different symlinks to the same file the equality check will not succeed. Use `realpath`
+    /// in such circumstances.
     static func ==<P: Pathish> (lhs: Self, rhs: P) -> Bool {
         return lhs.string == rhs.string
     }