From 2f3726a5b040f334525c01e4d8cde74541420f63 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?M=C3=A1rton=20Boros?= <martonboros@gmail.com>
Date: Fri, 20 Mar 2015 17:34:39 +0100
Subject: [PATCH 1/2] add documentation

---
 README.md                   | 388 ++++++++++++++++++++++++++++--------
 src/Data/Char/Char.purs     |   5 +
 src/Data/String.purs        |  48 ++++-
 src/Data/String/Regex.purs  |  24 +++
 src/Data/String/Unsafe.purs |   7 +
 5 files changed, 385 insertions(+), 87 deletions(-)

diff --git a/README.md b/README.md
index 410cbdd..8052e4e 100644
--- a/README.md
+++ b/README.md
@@ -2,227 +2,445 @@
 
 ## Module Data.Char
 
-### Types
+
+A type and functions for single characters.
 
 #### `Char`
 
-    newtype Char
+``` purescript
+newtype Char
+```
+
+A unicode character.
+
+#### `charString`
+
+``` purescript
+charString :: Char -> String
+```
+
+Returns the string of length `1` containing only the given character.
+
+#### `toCharCode`
+
+``` purescript
+toCharCode :: Char -> Number
+```
 
+Returns the numeric Unicode value of the character.
+
+#### `fromCharCode`
 
-### Type Class Instances
+``` purescript
+fromCharCode :: Number -> Char
+```
+
+Constructs a character from the given Unicode numeric value.
 
 #### `eqChar`
 
-    instance eqChar :: Eq Char
+``` purescript
+instance eqChar :: Eq Char
+```
+
 
 #### `ordChar`
 
-    instance ordChar :: Ord Char
+``` purescript
+instance ordChar :: Ord Char
+```
+
 
 #### `showChar`
 
-    instance showChar :: Show Char
+``` purescript
+instance showChar :: Show Char
+```
 
 
-### Values
 
-#### `charString`
+## Module Data.String
 
-    charString :: Char -> String
 
-#### `fromCharCode`
+Wraps the functions of Javascript's `String` object.
+A String represents a sequence of characters.
+For examples and details of the underlying implementation, see [String Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).
 
-    fromCharCode :: Number -> Char
+#### `charAt`
 
-#### `toCharCode`
+``` purescript
+charAt :: Number -> String -> Maybe Char
+```
 
-    toCharCode :: Char -> Number
+Returns the character at the given index, if the index is within bounds.
 
+#### `fromChar`
 
-## Module Data.String
+``` purescript
+fromChar :: Char -> String
+```
 
-### Values
+Returns a string of length `1` containing the given character.
 
-#### `charAt`
+#### `singleton`
+
+``` purescript
+singleton :: Char -> String
+```
 
-    charAt :: Number -> String -> Maybe Char
+Returns a string of length `1` containing the given character.
+Same as `fromChar`.
 
 #### `charCodeAt`
 
-    charCodeAt :: Number -> String -> Maybe Number
+``` purescript
+charCodeAt :: Number -> String -> Maybe Number
+```
 
-#### `count`
+Returns the numeric Unicode value of the character at the given index,
+if the index is within bounds.
 
-    count :: (Char -> Boolean) -> String -> Number
+#### `null`
 
-#### `drop`
+``` purescript
+null :: String -> Boolean
+```
 
-    drop :: Number -> String -> String
+Returns `true` if the given string is empty.
 
-#### `dropWhile`
+#### `uncons`
 
-    dropWhile :: (Char -> Boolean) -> String -> String
+``` purescript
+uncons :: String -> Maybe { tail :: String, head :: Char }
+```
 
-#### `fromChar`
+Returns the first character and the rest of the string,
+if the string is not empty.
 
-    fromChar :: Char -> String
+#### `takeWhile`
+
+``` purescript
+takeWhile :: (Char -> Boolean) -> String -> String
+```
+
+Returns the longest prefix (possibly empty) of characters that satisfy the
+predicate:
+
+#### `dropWhile`
+
+``` purescript
+dropWhile :: (Char -> Boolean) -> String -> String
+```
+
+Returns the suffix remaining after `takeWhile`.
 
 #### `fromCharArray`
 
-    fromCharArray :: [Char] -> String
+``` purescript
+fromCharArray :: [Char] -> String
+```
+
+Converts an array of characters into a string.
 
 #### `indexOf`
 
-    indexOf :: String -> String -> Number
+``` purescript
+indexOf :: String -> String -> Number
+```
 
-#### `indexOf'`
+Returns the index of the first occurrence of the first string in the
+second string. Returns `-1` if there is no match.
 
-    indexOf' :: String -> Number -> String -> Number
+#### `indexOf'`
 
-#### `joinWith`
+``` purescript
+indexOf' :: String -> Number -> String -> Number
+```
 
-    joinWith :: String -> [String] -> String
+Returns the index of the first occurrence of the first string in the
+second string, starting at the given index. Returns `-1` if there is
+no match.
 
 #### `lastIndexOf`
 
-    lastIndexOf :: String -> String -> Number
+``` purescript
+lastIndexOf :: String -> String -> Number
+```
+
+Returns the index of the last occurrence of the first string in the
+second string. Returns `-1` if there is no match.
 
 #### `lastIndexOf'`
 
-    lastIndexOf' :: String -> Number -> String -> Number
+``` purescript
+lastIndexOf' :: String -> Number -> String -> Number
+```
+
+Returns the index of the first occurrence of the last string in the
+second string, starting at the given index. Returns `-1` if there is
+no match.
 
 #### `length`
 
-    length :: String -> Number
+``` purescript
+length :: String -> Number
+```
 
-#### `localeCompare`
+Returns the number of characters the string is composed of.
 
-    localeCompare :: String -> String -> Number
+#### `localeCompare`
 
-#### `null`
+``` purescript
+localeCompare :: String -> String -> Number
+```
 
-    null :: String -> Boolean
+Locale-aware sort order comparison. Returns a negative number if the
+first string occurs before the second in a sort, a positive number
+if the first string occurs after the second, and 0 if they occur at the same level.
 
 #### `replace`
 
-    replace :: String -> String -> String -> String
+``` purescript
+replace :: String -> String -> String -> String
+```
 
-#### `singleton`
+Replaces the first occurence of the first argument with the second argument.
 
-    singleton :: Char -> String
+#### `take`
 
-#### `split`
+``` purescript
+take :: Number -> String -> String
+```
 
-    split :: String -> String -> [String]
+Returns the first `n` characters of the string.
 
-#### `take`
+#### `drop`
 
-    take :: Number -> String -> String
+``` purescript
+drop :: Number -> String -> String
+```
 
-#### `takeWhile`
+Returns the string without the first `n` characters.
+
+#### `count`
+
+``` purescript
+count :: (Char -> Boolean) -> String -> Number
+```
 
-    takeWhile :: (Char -> Boolean) -> String -> String
+Returns the number of characters in the string for which the predicate holds.
+
+#### `split`
+
+``` purescript
+split :: String -> String -> [String]
+```
+
+Returns the substrings of the first string separated along occurences
+of the second string.
 
 #### `toCharArray`
 
-    toCharArray :: String -> [Char]
+``` purescript
+toCharArray :: String -> [Char]
+```
+
+Converts the string into an array of characters.
 
 #### `toLower`
 
-    toLower :: String -> String
+``` purescript
+toLower :: String -> String
+```
+
+Returns the argument converted to lowercase.
 
 #### `toUpper`
 
-    toUpper :: String -> String
+``` purescript
+toUpper :: String -> String
+```
+
+Returns the argument converted to uppercase.
 
 #### `trim`
 
-    trim :: String -> String
+``` purescript
+trim :: String -> String
+```
 
-#### `uncons`
+Removes whitespace from the beginning and end of a string, where
+whitespace means all the whitespace characters (space, tab, no-break
+space, etc.) and all the line terminator characters (LF, CR, etc.).
 
-    uncons :: String -> Maybe { tail :: String, head :: Char }
+#### `joinWith`
+
+``` purescript
+joinWith :: String -> [String] -> String
+```
+
+Joins the strings in the array together, inserting the first argument
+as separator between them.
 
 
 ## Module Data.String.Regex
 
-### Types
+
+Wraps Javascript's `RegExp` object that enables matching strings with
+patternes defined by regular expressions.
+For examples and details of the underlying implementation, see [RegExp Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp).
 
 #### `Regex`
 
-    data Regex :: *
+``` purescript
+data Regex :: *
+```
+
+Wraps Javascript `RegExp` objects.
+
+#### `showRegex`
+
+``` purescript
+instance showRegex :: Show Regex
+```
+
 
 #### `RegexFlags`
 
-    type RegexFlags = { unicode :: Boolean, sticky :: Boolean, multiline :: Boolean, ignoreCase :: Boolean, global :: Boolean }
+``` purescript
+type RegexFlags = { unicode :: Boolean, sticky :: Boolean, multiline :: Boolean, ignoreCase :: Boolean, global :: Boolean }
+```
 
+Flags that control matching.
 
-### Type Class Instances
+#### `noFlags`
 
-#### `showRegex`
+``` purescript
+noFlags :: RegexFlags
+```
 
-    instance showRegex :: Show Regex
+All flags set to false.
+
+#### `regex`
+
+``` purescript
+regex :: String -> RegexFlags -> Regex
+```
+
+Constructs a `Regex` from a pattern string and flags.
+
+#### `source`
 
+``` purescript
+source :: Regex -> String
+```
 
-### Values
+Returns the pattern string used to construct the given `Regex`.
 
 #### `flags`
 
-    flags :: Regex -> RegexFlags
+``` purescript
+flags :: Regex -> RegexFlags
+```
 
-#### `match`
+Returns the `RegexFlags` used to construct the given `Regex`.
 
-    match :: Regex -> String -> Maybe [String]
+#### `renderFlags`
 
-#### `noFlags`
+``` purescript
+renderFlags :: RegexFlags -> String
+```
 
-    noFlags :: RegexFlags
+Returns the string representation of the given `RegexFlags`.
 
 #### `parseFlags`
 
-    parseFlags :: String -> RegexFlags
+``` purescript
+parseFlags :: String -> RegexFlags
+```
 
-#### `regex`
+Parses the string representation of `RegexFlags`.
 
-    regex :: String -> RegexFlags -> Regex
+#### `test`
 
-#### `renderFlags`
+``` purescript
+test :: Regex -> String -> Boolean
+```
 
-    renderFlags :: RegexFlags -> String
+Returns `true` if the `Regex` matches the string.
+
+#### `match`
+
+``` purescript
+match :: Regex -> String -> Maybe [String]
+```
+
+Matches the string against the `Regex` and returns an array of matches
+if there were any.
+See [reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match).
 
 #### `replace`
 
-    replace :: Regex -> String -> String -> String
+``` purescript
+replace :: Regex -> String -> String -> String
+```
+
+Replaces occurences of the `Regex` with the first string. The replacement
+string can include special replacement patterns escaped with `"$"`.
+See [reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace).
 
 #### `replace'`
 
-    replace' :: Regex -> (String -> [String] -> String) -> String -> String
+``` purescript
+replace' :: Regex -> (String -> [String] -> String) -> String -> String
+```
 
-#### `search`
+Transforms occurences of the `Regex` using a function of the matched
+substring and a list of submatch strings.
+See the [reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_function_as_a_parameter).
 
-    search :: Regex -> String -> Number
+#### `search`
 
-#### `source`
+``` purescript
+search :: Regex -> String -> Number
+```
 
-    source :: Regex -> String
+Returns the index of the first match of the `Regex` in the string, or
+`-1` if there is no match.
 
 #### `split`
 
-    split :: Regex -> String -> [String]
-
-#### `test`
+``` purescript
+split :: Regex -> String -> [String]
+```
 
-    test :: Regex -> String -> Boolean
+Split the string into an array of substrings along occurences of the `Regex`.
 
 
 ## Module Data.String.Unsafe
 
-### Values
+
+Unsafe string and character functions.
+
+#### `charCodeAt`
+
+``` purescript
+charCodeAt :: Number -> String -> Number
+```
+
+Returns the numeric Unicode value of the character at the given index.
+
+**Unsafe:** returns `NaN` if the index is out of bounds.
 
 #### `charAt`
 
-    charAt :: Number -> String -> Char
+``` purescript
+charAt :: Number -> String -> Char
+```
+
+Returns the character at the given index.
+
+**Unsafe:** returns an illegal value if the index is out of bounds.
+
 
-#### `charCodeAt`
 
-    charCodeAt :: Number -> String -> Number
\ No newline at end of file
diff --git a/src/Data/Char/Char.purs b/src/Data/Char/Char.purs
index 2fa34e3..f9034bc 100644
--- a/src/Data/Char/Char.purs
+++ b/src/Data/Char/Char.purs
@@ -1,3 +1,4 @@
+-- | A type and functions for single characters.
 module Data.Char
   ( Char(),
     charString,
@@ -5,11 +6,14 @@ module Data.Char
     toCharCode
   ) where
 
+  --| A unicode character.
   newtype Char = Char String
 
+  -- | Returns the string of length `1` containing only the given character.
   charString :: Char -> String
   charString (Char s) = s
 
+  -- | Returns the numeric Unicode value of the character.
   foreign import toCharCode
     """
     function toCharCode(c) {
@@ -17,6 +21,7 @@ module Data.Char
     }
     """ :: Char -> Number
 
+  -- | Constructs a character from the given Unicode numeric value.
   foreign import fromCharCode
     """
     function fromCharCode(c) {
diff --git a/src/Data/String.purs b/src/Data/String.purs
index 09e2714..20c93fe 100644
--- a/src/Data/String.purs
+++ b/src/Data/String.purs
@@ -1,3 +1,6 @@
+-- | Wraps the functions of Javascript's `String` object.
+-- | A String represents a sequence of characters.
+-- | For examples and details of the underlying implementation, see [String Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).
 module Data.String
   (
     charAt,
@@ -39,12 +42,16 @@ module Data.String
     }
     """ :: forall a. Fn4 Number String (a -> Maybe a) (Maybe a) (Maybe Char)
 
+  -- | Returns the character at the given index, if the index is within bounds.
   charAt :: Number -> String -> Maybe Char
   charAt n s = runFn4 _charAt n s Just Nothing
 
+  -- | Returns a string of length `1` containing the given character.
   fromChar :: Char -> String
   fromChar = charString
 
+  -- | Returns a string of length `1` containing the given character.
+  -- | Same as `fromChar`.
   singleton :: Char -> String
   singleton = fromChar
 
@@ -55,22 +62,31 @@ module Data.String
     }
     """ :: forall a. Fn4 Number String (a -> Maybe a) (Maybe a) (Maybe Number)
 
+  -- | Returns the numeric Unicode value of the character at the given index,
+  -- | if the index is within bounds.
   charCodeAt :: Number -> String -> Maybe Number
   charCodeAt n s = runFn4 _charCodeAt n s Just Nothing
 
+  -- | Returns `true` if the given string is empty.
   null :: String -> Boolean
   null s = length s == 0
 
+  -- | Returns the first character and the rest of the string,
+  -- | if the string is not empty.
   uncons :: String -> Maybe {head :: Char, tail :: String}
   uncons s | null s = Nothing
   uncons s = Just {head : U.charAt 0 s, tail : drop 1 s}
 
+  -- | Returns the longest prefix (possibly empty) of characters that satisfy the
+  -- | predicate:
   takeWhile :: (Char -> Boolean) -> String -> String
   takeWhile p s = take (count p s) s
 
+  -- | Returns the suffix remaining after `takeWhile`.
   dropWhile :: (Char -> Boolean) -> String -> String
   dropWhile p s = drop (count p s) s
 
+  -- | Converts an array of characters into a string.
   foreign import fromCharArray
     """
     function fromCharArray(a) {
@@ -78,6 +94,8 @@ module Data.String
     }
     """ :: [Char] -> String
 
+  -- | Returns the index of the first occurrence of the first string in the
+  -- | second string. Returns `-1` if there is no match.
   foreign import indexOf
     """
     function indexOf(x) {
@@ -87,6 +105,9 @@ module Data.String
     }
     """ :: String -> String -> Number
 
+  -- | Returns the index of the first occurrence of the first string in the
+  -- | second string, starting at the given index. Returns `-1` if there is
+  -- | no match.
   foreign import indexOf'
     """
     function indexOf$prime(x) {
@@ -98,6 +119,8 @@ module Data.String
     }
     """ :: String -> Number -> String -> Number
 
+  -- | Returns the index of the last occurrence of the first string in the
+  -- | second string. Returns `-1` if there is no match.
   foreign import lastIndexOf
     """
     function lastIndexOf(x) {
@@ -107,6 +130,9 @@ module Data.String
     }
     """ :: String -> String -> Number
 
+  -- | Returns the index of the first occurrence of the last string in the
+  -- | second string, starting at the given index. Returns `-1` if there is
+  -- | no match.
   foreign import lastIndexOf'
     """
     function lastIndexOf$prime(x) {
@@ -118,6 +144,7 @@ module Data.String
     }
     """ :: String -> Number -> String -> Number
 
+  -- | Returns the number of characters the string is composed of.
   foreign import length
     """
     function length(s) {
@@ -125,6 +152,9 @@ module Data.String
     }
     """ :: String -> Number
 
+  -- | Locale-aware sort order comparison. Returns a negative number if the
+  -- | first string occurs before the second in a sort, a positive number
+  -- | if the first string occurs after the second, and 0 if they occur at the same level.
   foreign import localeCompare
     """
     function localeCompare(s1) {
@@ -134,6 +164,7 @@ module Data.String
     }
     """ :: String -> String -> Number
 
+  -- | Replaces the first occurence of the first argument with the second argument.
   foreign import replace
     """
     function replace(s1) {
@@ -145,6 +176,7 @@ module Data.String
     }
     """ :: String -> String -> String -> String
 
+  -- | Returns the first `n` characters of the string.
   foreign import take
     """
     function take(n) {
@@ -154,6 +186,7 @@ module Data.String
     }
     """ :: Number -> String -> String
 
+  -- | Returns the string without the first `n` characters.
   foreign import drop
     """
     function drop(n) {
@@ -163,17 +196,20 @@ module Data.String
     }
     """ :: Number -> String -> String
 
+  -- | Returns the number of characters in the string for which the predicate holds.
   foreign import count
     """
-    function count(p){      
+    function count(p){
       return function(s){
         var i;
         for(i = 0; i < s.length && p(s.charAt(i)); i++){};
         return i;
-      };      
+      };
     }
     """ :: (Char -> Boolean) -> String -> Number
 
+  -- | Returns the substrings of the first string separated along occurences
+  -- | of the second string.
   foreign import split
     """
     function split(sep) {
@@ -183,6 +219,7 @@ module Data.String
     }
     """ :: String -> String -> [String]
 
+  -- | Converts the string into an array of characters.
   foreign import toCharArray
     """
     function toCharArray(s) {
@@ -190,6 +227,7 @@ module Data.String
     }
     """ :: String -> [Char]
 
+  -- | Returns the argument converted to lowercase.
   foreign import toLower
     """
     function toLower(s) {
@@ -197,6 +235,7 @@ module Data.String
     }
     """ :: String -> String
 
+  -- | Returns the argument converted to uppercase.
   foreign import toUpper
     """
     function toUpper(s) {
@@ -204,6 +243,9 @@ module Data.String
     }
     """ :: String -> String
 
+  -- | Removes whitespace from the beginning and end of a string, where
+  -- | whitespace means all the whitespace characters (space, tab, no-break
+  -- | space, etc.) and all the line terminator characters (LF, CR, etc.).
   foreign import trim
     """
     function trim(s) {
@@ -211,6 +253,8 @@ module Data.String
     }
     """ :: String -> String
 
+  -- | Joins the strings in the array together, inserting the first argument
+  -- | as separator between them.
   foreign import joinWith
     """
     function joinWith(s) {
diff --git a/src/Data/String/Regex.purs b/src/Data/String/Regex.purs
index 6ad1bce..f3daf42 100644
--- a/src/Data/String/Regex.purs
+++ b/src/Data/String/Regex.purs
@@ -1,3 +1,6 @@
+-- | Wraps Javascript's `RegExp` object that enables matching strings with
+-- | patternes defined by regular expressions.
+-- | For examples and details of the underlying implementation, see [RegExp Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp).
 module Data.String.Regex
   ( Regex(..)
   , RegexFlags(..)
@@ -19,6 +22,7 @@ import Data.Function
 import Data.Maybe
 import Data.String (indexOf)
 
+-- | Wraps Javascript `RegExp` objects.
 foreign import data Regex :: *
 
 foreign import showRegex'
@@ -31,6 +35,7 @@ foreign import showRegex'
 instance showRegex :: Show Regex where
   show = showRegex'
 
+-- | Flags that control matching.
 type RegexFlags =
   { global :: Boolean
   , ignoreCase :: Boolean
@@ -39,6 +44,7 @@ type RegexFlags =
   , unicode :: Boolean
   }
 
+-- | All flags set to false.
 noFlags :: RegexFlags
 noFlags = { global     : false
           , ignoreCase : false
@@ -55,9 +61,11 @@ foreign import regex'
   }
   """ :: String -> String -> Regex
 
+-- | Constructs a `Regex` from a pattern string and flags.
 regex :: String -> RegexFlags -> Regex
 regex source flags = regex' source $ renderFlags flags
 
+-- | Returns the pattern string used to construct the given `Regex`.
 foreign import source
   """
   function source(r) {
@@ -65,6 +73,7 @@ foreign import source
   }
   """ :: Regex -> String
 
+-- | Returns the `RegexFlags` used to construct the given `Regex`.
 foreign import flags
   """
   function flags(r) {
@@ -78,6 +87,7 @@ foreign import flags
   }
   """ :: Regex -> RegexFlags
 
+-- | Returns the string representation of the given `RegexFlags`.
 renderFlags :: RegexFlags -> String
 renderFlags flags =
   (if flags.global then "g" else "") ++
@@ -86,6 +96,7 @@ renderFlags flags =
   (if flags.sticky then "y" else "") ++
   (if flags.unicode then "u" else "")
 
+-- | Parses the string representation of `RegexFlags`.
 parseFlags :: String -> RegexFlags
 parseFlags s =
   { global: indexOf "g" s >= 0
@@ -95,6 +106,7 @@ parseFlags s =
   , unicode: indexOf "u" s >= 0
   }
 
+-- | Returns `true` if the `Regex` matches the string.
 foreign import test
   """
   function test(r) {
@@ -112,9 +124,15 @@ foreign import _match
   }
   """ :: forall r. Fn4 Regex String ([String] -> r) r r
 
+-- | Matches the string against the `Regex` and returns an array of matches
+-- | if there were any.
+-- | See [reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match).
 match :: Regex -> String -> Maybe [String]
 match r s = runFn4 _match r s Just Nothing
 
+-- | Replaces occurences of the `Regex` with the first string. The replacement
+-- | string can include special replacement patterns escaped with `"$"`.
+-- | See [reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace).
 foreign import replace
   """
   function replace(r) {
@@ -126,6 +144,9 @@ foreign import replace
   }
   """ :: Regex -> String -> String -> String
 
+-- | Transforms occurences of the `Regex` using a function of the matched
+-- | substring and a list of submatch strings.
+-- | See the [reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_function_as_a_parameter).
 foreign import replace'
   """
   function replace$prime(r) {
@@ -139,6 +160,8 @@ foreign import replace'
   }
   """ :: Regex -> (String -> [String] -> String) -> String -> String
 
+-- | Returns the index of the first match of the `Regex` in the string, or
+-- | `-1` if there is no match.
 foreign import search
   """
   function search(r) {
@@ -148,6 +171,7 @@ foreign import search
   }
   """ :: Regex -> String -> Number
 
+-- | Split the string into an array of substrings along occurences of the `Regex`.
 foreign import split
   """
   function split(r) {
diff --git a/src/Data/String/Unsafe.purs b/src/Data/String/Unsafe.purs
index 20e54dc..c31cba7 100644
--- a/src/Data/String/Unsafe.purs
+++ b/src/Data/String/Unsafe.purs
@@ -1,3 +1,4 @@
+-- | Unsafe string and character functions.
 module Data.String.Unsafe
   ( charAt
   , charCodeAt
@@ -5,6 +6,9 @@ module Data.String.Unsafe
 
   import Data.Char
 
+  -- | Returns the numeric Unicode value of the character at the given index.
+  -- |
+  -- | **Unsafe:** returns `NaN` if the index is out of bounds.
   foreign import charCodeAt
     """
     function charCodeAt(i) {
@@ -14,6 +18,9 @@ module Data.String.Unsafe
     }
     """ :: Number -> String -> Number
 
+  -- | Returns the character at the given index.
+  -- |
+  -- | **Unsafe:** returns an illegal value if the index is out of bounds.
   foreign import charAt
     """
     function charAt(i) {

From 0316afb3b291f290ce8f80b19c7746ae72dfe382 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?M=C3=A1rton=20Boros?= <martonboros@gmail.com>
Date: Sat, 21 Mar 2015 18:41:23 +0100
Subject: [PATCH 2/2] cleanup, add instance doc

---
 README.md                  | 20 ++++++++++++--------
 src/Data/Char/Char.purs    |  3 +++
 src/Data/String.purs       | 15 ++++++++-------
 src/Data/String/Regex.purs |  2 +-
 4 files changed, 24 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 8052e4e..31504b7 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,7 @@ Constructs a character from the given Unicode numeric value.
 instance eqChar :: Eq Char
 ```
 
+Characters can be compared for equality with `==` and `/=`.
 
 #### `ordChar`
 
@@ -50,6 +51,7 @@ instance eqChar :: Eq Char
 instance ordChar :: Ord Char
 ```
 
+Characters can be compared with `compare`, `>`, `>=`, `<` and `<=`.
 
 #### `showChar`
 
@@ -57,6 +59,7 @@ instance ordChar :: Ord Char
 instance showChar :: Show Char
 ```
 
+Characters can be rendered as a string with `show`.
 
 
 ## Module Data.String
@@ -64,7 +67,7 @@ instance showChar :: Show Char
 
 Wraps the functions of Javascript's `String` object.
 A String represents a sequence of characters.
-For examples and details of the underlying implementation, see [String Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).
+For details of the underlying implementation, see [String Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).
 
 #### `charAt`
 
@@ -123,8 +126,8 @@ if the string is not empty.
 takeWhile :: (Char -> Boolean) -> String -> String
 ```
 
-Returns the longest prefix (possibly empty) of characters that satisfy the
-predicate:
+Returns the longest prefix (possibly empty) of characters that satisfy
+the predicate:
 
 #### `dropWhile`
 
@@ -196,7 +199,8 @@ localeCompare :: String -> String -> Number
 
 Locale-aware sort order comparison. Returns a negative number if the
 first string occurs before the second in a sort, a positive number
-if the first string occurs after the second, and 0 if they occur at the same level.
+if the first string occurs after the second, and `0` if their sort order
+is equal.
 
 #### `replace`
 
@@ -269,9 +273,9 @@ Returns the argument converted to uppercase.
 trim :: String -> String
 ```
 
-Removes whitespace from the beginning and end of a string, where
-whitespace means all the whitespace characters (space, tab, no-break
-space, etc.) and all the line terminator characters (LF, CR, etc.).
+Removes whitespace from the beginning and end of a string, including
+[whitespace characters](http://www.ecma-international.org/ecma-262/5.1/#sec-7.2)
+and [line terminators](http://www.ecma-international.org/ecma-262/5.1/#sec-7.3).
 
 #### `joinWith`
 
@@ -288,7 +292,7 @@ as separator between them.
 
 Wraps Javascript's `RegExp` object that enables matching strings with
 patternes defined by regular expressions.
-For examples and details of the underlying implementation, see [RegExp Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp).
+For details of the underlying implementation, see [RegExp Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp).
 
 #### `Regex`
 
diff --git a/src/Data/Char/Char.purs b/src/Data/Char/Char.purs
index f9034bc..a243607 100644
--- a/src/Data/Char/Char.purs
+++ b/src/Data/Char/Char.purs
@@ -29,13 +29,16 @@ module Data.Char
     }
     """ :: Number -> Char
 
+  -- | Characters can be compared for equality with `==` and `/=`.
   instance eqChar :: Eq Char where
     (==) (Char a) (Char b) = a == b
 
     (/=) a b = not (a == b)
 
+  -- | Characters can be compared with `compare`, `>`, `>=`, `<` and `<=`.
   instance ordChar :: Ord Char where
     compare (Char a) (Char b) = a `compare` b
 
+  -- | Characters can be rendered as a string with `show`.
   instance showChar :: Show Char where
     show (Char s) = "Char " ++ show s
diff --git a/src/Data/String.purs b/src/Data/String.purs
index 20c93fe..8b31d4d 100644
--- a/src/Data/String.purs
+++ b/src/Data/String.purs
@@ -1,6 +1,6 @@
 -- | Wraps the functions of Javascript's `String` object.
 -- | A String represents a sequence of characters.
--- | For examples and details of the underlying implementation, see [String Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).
+-- | For details of the underlying implementation, see [String Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).
 module Data.String
   (
     charAt,
@@ -77,8 +77,8 @@ module Data.String
   uncons s | null s = Nothing
   uncons s = Just {head : U.charAt 0 s, tail : drop 1 s}
 
-  -- | Returns the longest prefix (possibly empty) of characters that satisfy the
-  -- | predicate:
+  -- | Returns the longest prefix (possibly empty) of characters that satisfy
+  -- | the predicate:
   takeWhile :: (Char -> Boolean) -> String -> String
   takeWhile p s = take (count p s) s
 
@@ -154,7 +154,8 @@ module Data.String
 
   -- | Locale-aware sort order comparison. Returns a negative number if the
   -- | first string occurs before the second in a sort, a positive number
-  -- | if the first string occurs after the second, and 0 if they occur at the same level.
+  -- | if the first string occurs after the second, and `0` if their sort order
+  -- | is equal.
   foreign import localeCompare
     """
     function localeCompare(s1) {
@@ -243,9 +244,9 @@ module Data.String
     }
     """ :: String -> String
 
-  -- | Removes whitespace from the beginning and end of a string, where
-  -- | whitespace means all the whitespace characters (space, tab, no-break
-  -- | space, etc.) and all the line terminator characters (LF, CR, etc.).
+  -- | Removes whitespace from the beginning and end of a string, including
+  -- | [whitespace characters](http://www.ecma-international.org/ecma-262/5.1/#sec-7.2)
+  -- | and [line terminators](http://www.ecma-international.org/ecma-262/5.1/#sec-7.3).
   foreign import trim
     """
     function trim(s) {
diff --git a/src/Data/String/Regex.purs b/src/Data/String/Regex.purs
index f3daf42..8a06310 100644
--- a/src/Data/String/Regex.purs
+++ b/src/Data/String/Regex.purs
@@ -1,6 +1,6 @@
 -- | Wraps Javascript's `RegExp` object that enables matching strings with
 -- | patternes defined by regular expressions.
--- | For examples and details of the underlying implementation, see [RegExp Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp).
+-- | For details of the underlying implementation, see [RegExp Reference at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp).
 module Data.String.Regex
   ( Regex(..)
   , RegexFlags(..)