More documentation updates for Perms

Author: hdgarrood

README.md

@@ -200,16 +200,17 @@ newtype Perms
 ```
 
 A `Perms` value includes all the permissions information about a
-particular file or directory,
+particular file or directory, by storing a `Perm` value for each of the
+file owner, the group, and others.
 
 #### `none`
 
 ``` purescript
 none :: Perm
 ```
 
-No permissions. This is the identity of the Semigroup (<>) operation for
-Perm.
+No permissions. This is the identity of the `Semigroup` operation `(<>)`
+for `Perm`.
 
 #### `r`
 
@@ -256,6 +257,9 @@ instance semigroupPerm :: Semigroup Perm
 permsFromString :: String -> Maybe Perms
 ```
 
+Attempt to parse a `Perms` value from a `String` containing an octal
+integer. For example,
+`permsFromString "644" == Just (mkPerms (r <> w) r r)`.
 
 #### `mkPerms`
 
@@ -272,13 +276,18 @@ others' permission sets, respectively.
 permsToString :: Perms -> String
 ```
 
+Convert a `Perms` value to an octal string, in a format similar to that
+accepted by `chmod`. For example:
+
+* `permsToString (mkPerms (r <> w) r r) == "0644"`
 
 #### `permsToInt`
 
 ``` purescript
 permsToInt :: Perms -> Int
 ```
 
+Convert a `Perms` value to an `Int`, via `permsToString`.
 
 #### `showPerm`
 

src/Node/FS/Perms.purs

@@ -26,11 +26,12 @@ import Data.Int (Int(), fromNumber, toNumber)
 newtype Perm = Perm { r :: Boolean, w :: Boolean, x :: Boolean }
 
 -- | A `Perms` value includes all the permissions information about a
--- | particular file or directory,
+-- | particular file or directory, by storing a `Perm` value for each of the
+-- | file owner, the group, and others.
 newtype Perms = Perms { u :: Perm, g :: Perm, o :: Perm }
 
--- | No permissions. This is the identity of the Semigroup (<>) operation for
--- | Perm.
+-- | No permissions. This is the identity of the `Semigroup` operation `(<>)`
+-- | for `Perm`.
 none :: Perm
 none = Perm { r: false, w: false, x: false }
 
@@ -54,10 +55,13 @@ instance semigroupPerm :: Semigroup Perm where
   (<>) (Perm { r = r0, w = w0, x = x0 }) (Perm { r = r1, w = w1, x = x1 }) =
     Perm { r: r0 || r1, w: w0 || w1, x: x0 || x1  }
 
+-- | Attempt to parse a `Perms` value from a `String` containing an octal
+-- | integer. For example,
+-- | `permsFromString "644" == Just (mkPerms (r <> w) r r)`.
 permsFromString :: String -> Maybe Perms
 permsFromString = _perms <<< toCharArray
   where
-    _perms (u : g : o : []) =
+    _perms [u, g, o] =
       mkPerms <$> permFromChar u
               <*> permFromChar g
               <*> permFromChar o
@@ -77,7 +81,7 @@ permFromChar = _perm <<< charString
     _perm _   = Nothing
 
 -- | Create a `Perm` value. The arguments represent the readable, writable, and
--- | executable permissions respectively.
+-- | executable permissions, in that order.
 mkPerm :: Boolean -> Boolean -> Boolean -> Perm
 mkPerm r w x = Perm { r: r, w: w, x: x }
 
@@ -86,15 +90,25 @@ mkPerm r w x = Perm { r: r, w: w, x: x }
 mkPerms :: Perm -> Perm -> Perm -> Perms
 mkPerms u g o = Perms { u: u, g: g, o: o }
 
+-- | Convert a `Perm` to an octal digit. For example:
+-- |
+-- | * `permToInt r == 4`
+-- | * `permToInt w == 2`
+-- | * `permToInt (r <> w) == 6`
 permToInt :: Perm -> Int
 permToInt (Perm { r = r, w = w, x = x }) = fromNumber $
     (if r then 4 else 0)
   + (if w then 2 else 0)
   + (if x then 1 else 0)
 
+-- | Convert a `Perm` to an octal string, via `permToInt`.
 permToString :: Perm -> String
 permToString = show <<< toNumber <<< permToInt
 
+-- | Convert a `Perms` value to an octal string, in a format similar to that
+-- | accepted by `chmod`. For example:
+-- |
+-- | * `permsToString (mkPerms (r <> w) r r) == "0644"`
 permsToString :: Perms -> String
 permsToString (Perms { u = u, g = g, o = o }) =
      "0"