Improved documentation; Fixes #12

.gitignore

@@ -1,3 +1,5 @@
 .DS_Store
 /.build
 /*.xcodeproj
+/build
+/docs

.travis.yml

@@ -69,6 +69,8 @@ jobs:
           - UseModernBuildSystem=NO
         output: output
         github_url: https://github.com/mxcl/Path.swift
+        exclude:
+          - Sources/Path+StringConvertibles.swift
         EOF
         sed -i '' "s/TRAVIS_TAG/$TRAVIS_TAG/" .jazzy.yaml
       # ^^ this weirdness because Travis multiline YAML is broken and inserts

README.md

@@ -107,10 +107,8 @@ This is explicit, not hiding anything that code-review may miss and preventing
 common bugs like accidentally creating `Path` objects from strings you did not
 expect to be relative.
 
-Our initializer is nameless because we conform to `LosslessStringConvertible`,
-the same conformance as that `Int`, `Float` etc. conform. The protocol enforces
-a nameless initialization and since it is appropriate for us to conform to it,
-we do.
+Our initializer is nameless to be consistent with the equivalent operation for
+converting strings to `Int`, `Float` etc. in the standard library.
 
 ## Extensions
 

Sources/Path+Attributes.swift

@@ -1,6 +1,34 @@
 import Foundation
 
 public extension Path {
+    //MARK: Filesystem Attributes
+
+    /**
+     Returns the modification-time.
+     - Note: Returns the creation time if there is no modification time.
+     - Note: Returns UNIX-time-zero if neither are available, though this *should* be impossible.
+     */
+    var mtime: Date {
+        do {
+            let attrs = try FileManager.default.attributesOfItem(atPath: string)
+            return attrs[.modificationDate] as? Date ?? attrs[.creationDate] as? Date ?? Date(timeIntervalSince1970: 0)
+        } catch {
+            //TODO log error
+            return Date(timeIntervalSince1970: 0)
+        }
+    }
+
+    /**
+     Sets the file’s attributes using UNIX octal notation.
+
+         Path.home.join("foo").chmod(0o555)
+     */
+    @discardableResult
+    func chmod(_ octal: Int) throws -> Path {
+        try FileManager.default.setAttributes([.posixPermissions: octal], ofItemAtPath: string)
+        return self
+    }
+
     /// - Note: If file is already locked, does nothing
     /// - Note: If file doesn’t exist, throws
     @discardableResult
@@ -31,30 +59,4 @@ public extension Path {
         }
         return self
     }
-
-    /**
-     Sets the file’s attributes using UNIX octal notation.
-
-         Path.home.join("foo").chmod(0o555)
-     */
-    @discardableResult
-    func chmod(_ octal: Int) throws -> Path {
-        try FileManager.default.setAttributes([.posixPermissions: octal], ofItemAtPath: string)
-        return self
-    }
-
-    /**
-     Returns the modification-time.
-     - Note: Returns the creation time if there is no modification time.
-     - Note: Returns UNIX-time-zero if neither are available, though this *should* be impossible.
-     */
-    var mtime: Date {
-        do {
-            let attrs = try FileManager.default.attributesOfItem(atPath: string)
-            return attrs[.modificationDate] as? Date ?? attrs[.creationDate] as? Date ?? Date(timeIntervalSince1970: 0)
-        } catch {
-            //TODO log error
-            return Date(timeIntervalSince1970: 0)
-        }
-    }
 }

Sources/Path+Codable.swift

@@ -1,13 +1,31 @@
 import Foundation
 
-/// Provided for relative-path coding. See the instructions in our `README`.
+/**
+ Provided for relative-path coding. See the instructions in our
+ [README](https://github.com/mxcl/Path.swift/#codable).
+*/
 public extension CodingUserInfoKey {
-    /// If set paths are encoded as relative to this path.
+    /**
+     If set on an `Encoder`’s `userInfo` all paths are encoded relative to this path.
+
+     For example:
+
+         let encoder = JSONEncoder()
+         encoder.userInfo[.relativePath] = Path.home
+         encoder.encode([Path.home, Path.home/"foo"])
+
+     - Remark: See the [README](https://github.com/mxcl/Path.swift/#codable) for more information.
+    */
     static let relativePath = CodingUserInfoKey(rawValue: "dev.mxcl.Path.relative")!
 }
 
-/// Provided for relative-path coding. See the instructions in our `README`.
-extension Path: Codable {
+/**
+ Provided for relative-path coding. See the instructions in our
+ [README](https://github.com/mxcl/Path.swift/#codable).
+*/
+extension Path: Codable {    
+    /// - SeeAlso: `CodingUserInfoKey.relativePath`
+    // :nodoc:
     public init(from decoder: Decoder) throws {
         let value = try decoder.singleValueContainer().decode(String.self)
         if value.hasPrefix("/") {
@@ -20,6 +38,8 @@ extension Path: Codable {
         }
     }
 
+    /// - SeeAlso: `CodingUserInfoKey.relativePath`
+    // :nodoc:
     public func encode(to encoder: Encoder) throws {
         var container = encoder.singleValueContainer()
         if let root = encoder.userInfo[.relativePath] as? Path {

Sources/Path+CommonDirectories.swift

@@ -1,6 +1,8 @@
 import Foundation
 
 extension Path {
+    //MARK: Common Directories
+
     /// Returns a `Path` containing ``FileManager.default.currentDirectoryPath`.
     public static var cwd: Path {
         return Path(string: FileManager.default.currentDirectoryPath)

Sources/Path+FileManager.swift

@@ -1,6 +1,8 @@
 import Foundation
 
 public extension Path {
+    //MARK: File Management
+
     /**
      Copies a file.
      - Note: `throws` if `to` is a directory.

Sources/Path+StringConvertibles.swift

@@ -1,14 +1,6 @@
 import class Foundation.NSString
 
-extension Path: LosslessStringConvertible {
-    /// Returns `nil` unless fed an absolute path
-    public init?(_ description: String) {
-        guard description.starts(with: "/") || description.starts(with: "~/") else { return nil }
-        self.init(string: (description as NSString).standardizingPath)
-    }
-}
-
-extension Path: CustomStringConvertible {
+extension Path: CustomStringConvertible {    
     /// Returns `Path.string`
     public var description: String {
         return string

Sources/Path+ls.swift

@@ -1,8 +1,10 @@
 import Foundation
 
 public extension Path {
+    //MARK: Directory Listings
+
     /**
-     Same as the `ls -a` command ∴ is ”shallow”
+     Same as the `ls -a` command ∴ output is ”shallow” and unsorted.
      - Parameter includeHiddenFiles: If `true`, hidden files are included in the results. Defaults to `true`.
      - Important: `includeHiddenFiles` does not work on Linux
      */
@@ -22,6 +24,7 @@ public extension Path {
     }
 }
 
+/// Convenience functions for the array return value of `Path.ls()`
 public extension Array where Element == Path.Entry {
     /// Filters the list of entries to be a list of Paths that are directories.
     var directories: [Path] {

Sources/Path->Bool.swift

@@ -1,19 +1,17 @@
 import Foundation
 
 public extension Path {
-    /// Returns true if the path represents an actual file that is also writable by the current user.
-    var isWritable: Bool {
-        return FileManager.default.isWritableFile(atPath: string)
-    }
-
-    /// Returns true if the path represents an actual file that is also readable by the current user.
-    var isReadable: Bool {
-        return FileManager.default.isReadableFile(atPath: string)
+    //MARK: Filesystem Properties
+
+    /// Returns true if the path represents an actual filesystem entry.
+    var exists: Bool {
+        return FileManager.default.fileExists(atPath: string)
     }
-
-    /// Returns true if the path represents an actual file that is also deletable by the current user.
-    var isDeletable: Bool {
-        return FileManager.default.isDeletableFile(atPath: string)
+
+    /// Returns true if the path represents an actual filesystem entry that is *not* a directory.
+    var isFile: Bool {
+        var isDir: ObjCBool = true
+        return FileManager.default.fileExists(atPath: string, isDirectory: &isDir) && !isDir.boolValue
     }
 
     /// Returns true if the path represents an actual directory.
@@ -22,19 +20,23 @@ public extension Path {
         return FileManager.default.fileExists(atPath: string, isDirectory: &isDir) && isDir.boolValue
     }
 
-    /// Returns true if the path represents an actual filesystem entry that is *not* a directory.
-    var isFile: Bool {
-        var isDir: ObjCBool = true
-        return FileManager.default.fileExists(atPath: string, isDirectory: &isDir) && !isDir.boolValue
+    /// Returns true if the path represents an actual file that is also readable by the current user.
+    var isReadable: Bool {
+        return FileManager.default.isReadableFile(atPath: string)
+    }
+
+    /// Returns true if the path represents an actual file that is also writable by the current user.
+    var isWritable: Bool {
+        return FileManager.default.isWritableFile(atPath: string)
+    }
+
+    /// Returns true if the path represents an actual file that is also deletable by the current user.
+    var isDeletable: Bool {
+        return FileManager.default.isDeletableFile(atPath: string)
     }
 
     /// Returns true if the path represents an actual file that is also executable by the current user.
     var isExecutable: Bool {
         return FileManager.default.isExecutableFile(atPath: string)
     }
-
-    /// Returns true if the path represents an actual filesystem entry.
-    var exists: Bool {
-        return FileManager.default.fileExists(atPath: string)
-    }
 }