 
   The given options can either be a binary with the characters
   representing the same regex options given to the `%r` sigil,
-  or a list of options, as expected by the Erlang `re` docs.
+  or a list of options, as expected by the [Erlang `re` docs](http://www.erlang.org/doc/man/re.html).
 
   It returns `{ :ok, regex }` in case of success,
   `{ :error, reason }` otherwise.
+
+  ## Examples
+
+      iex> Regex.compile("foo")
+      {:ok, %r"foo"}
+      iex> Regex.compile("*foo")
+      {:error, {'nothing to repeat', 0}}
+
   """
   @spec compile(binary, binary | [term]) :: t
   def compile(source, options // "")

      # A regular expression with case insensitive options and handling for unicode chars
      %r/foo/iu

  The re module provides several options, the ones available in Elixir, followed by
  their shortcut in parenthesis, are:

  * `unicode` (u) - enable unicode specific patterns like \p
  * `caseless` (i) - add case insensitivity
  * `dotall` (s) - causes dot to match newlines and also set newline to anycrlf.
    The new line setting can be overridden by setting `(*CR)` or `(*LF)` or

    allow `#` to delimit comments
  * `firstline` (f) - forces the unanchored pattern to match before or at the first
    newline, though the matched text may continue over the newline
  * `ungreedy` (r) - inverts the "greediness" of the regexp
  * `groups` (g) - compiles with info about groups available

  The options not available are:

