From dfad7367b757e5f467471d4a85b3247bf47148eb Mon Sep 17 00:00:00 2001
From: Max Howell <mxcl@me.com>
Date: Sun, 21 Jul 2019 21:35:48 -0400
Subject: [PATCH] Get out documentation %age up

---
 Sources/Path+ls.swift | 12 ++++++++----
 Sources/Path.swift    |  1 +
 Sources/Pathish.swift |  3 +++
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/Sources/Path+ls.swift b/Sources/Path+ls.swift
index 1b0feda..0bd04fc 100644
--- a/Sources/Path+ls.swift
+++ b/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>?
     }
 }
@@ -83,9 +88,7 @@ public extension Path.Finder {
     }
 }
 
-public extension Pathish {    
-    //MARK: Directory Listings
-
+public extension Pathish {
     /**
      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
diff --git a/Sources/Path.swift b/Sources/Path.swift
index 369ae6c..c140d5d 100644
--- a/Sources/Path.swift
+++ b/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 {
 
diff --git a/Sources/Pathish.swift b/Sources/Pathish.swift
index 0bebe9e..992d2bc 100644
--- a/Sources/Pathish.swift
+++ b/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
     }