 defmodule Regex do
   @moduledoc %S"""
-  Regular expressions for Elixir built on top of the re module
+  Regular expressions for Elixir built on top of the `re` module
   in the Erlang Standard Library. More information can be found
-  in the re documentation: http://www.erlang.org/doc/man/re.html
-
-  Regular expressions in Elixir can be created using Regex.compile!
+  in the [`re` documentation](http://www.erlang.org/doc/man/re.html).
+
+  Regular expressions in Elixir can be created using `Regex.compile!`
   or using the special form with `%r`:
 
       # A simple regular expressions that matches foo anywhere in the string


  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.

  It returns `{ :ok, regex }` in case of success,
  `{ :error, reason }` otherwise.
  """
  @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) - enables 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
