Improve documentation and examples about modifiers

lib/elixir/lib/regex.ex

@@ -38,35 +38,35 @@ defmodule Regex do
 
   The modifiers available when creating a Regex are:
 
-    * `unicode` (u) - enables Unicode specific patterns like `\p` and causes
+    * `:unicode` (u) - enables Unicode specific patterns like `\p` and causes
       character classes like `\w`, `\W`, `\s`, and the like to also match on Unicode
       (see examples below in "Character classes"). It expects valid Unicode
       strings to be given on match
 
-    * `caseless` (i) - adds case insensitivity
+    * `:caseless` (i) - adds case insensitivity
 
-    * `dotall` (s) - causes dot to match newlines and also set newline to
+    * `: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 `(*CRLF)` or `(*ANY)` according to `:re` documentation
 
-    * `multiline` (m) - causes `^` and `$` to mark the beginning and end of
+    * `:multiline` (m) - causes `^` and `$` to mark the beginning and end of
       each line; use `\A` and `\z` to match the end or beginning of the string
 
-    * `extended` (x) - whitespace characters are ignored except when escaped
+    * `:extended` (x) - whitespace characters are ignored except when escaped
       and allow `#` to delimit comments
 
-    * `firstline` (f) - forces the unanchored pattern to match before or at the
+    * `:firstline` (f) - forces the unanchored pattern to match before or at the
       first newline, though the matched text may continue over the newline
 
-    * `ungreedy` (U) - inverts the "greediness" of the regexp
+    * `:ungreedy` (U) - inverts the "greediness" of the regexp
       (the previous `r` option is deprecated in favor of `U`)
 
   The options not available are:
 
-    * `anchored` - not available, use `^` or `\A` instead
-    * `dollar_endonly` - not available, use `\z` instead
-    * `no_auto_capture` - not available, use `?:` instead
-    * `newline` - not available, use `(*CR)` or `(*LF)` or `(*CRLF)` or
+    * `:anchored` - not available, use `^` or `\A` instead
+    * `:dollar_endonly` - not available, use `\z` instead
+    * `:no_auto_capture` - not available, use `?:` instead
+    * `:newline` - not available, use `(*CR)` or `(*LF)` or `(*CRLF)` or
       `(*ANYCRLF)` or `(*ANY)` at the beginning of the regexp according to the
       `:re` documentation
 
@@ -180,6 +180,12 @@ defmodule Regex do
       iex> Regex.compile("*foo")
       {:error, {'nothing to repeat', 0}}
 
+      iex> Regex.compile("foo", "i")
+      {:ok, ~r/foo/i}
+
+      iex> Regex.compile("foo", [:caseless])
+      {:ok, Regex.compile!("foo", [:caseless])}
+
   """
   @spec compile(binary, binary | [term]) :: {:ok, t} | {:error, any}
   def compile(source, options \\ "") when is_binary(source) do