   * `newline` - not available, use `(*CR)` or `(*LF)` or `(*CRLF)` or `(*ANYCRLF)`
     or `(*ANY)` at the beginning of the regexp according to the re documentation
 
+  ## Captures
+
+  Many functions in this module allows what to capture in a regex
+  match via the `:capture` option. The supported values are:
+
+  * `:all` - all captured subpatterns including the complete matching string.
+             This is the default;
+
+  * `:first` - only the first captured subpattern, which is always the complete
+               matching part of the string. All explicitly captured subpatterns are
+               discarded;
+
+  * `:all_but_first`- all but the first matching subpattern, i.e. all explicitly
+                      captured subpatterns, but not the complete matching part of
+                      the string;
+
+  * `:none` - do not return matching subpatterns at all;
+
+  * `:groups` - captures only named captures in the Regex;
+
+  * `list(binary)` - a list of named captures to capture;
+
   """
 
   defrecordp :regex, Regex, [:re_pattern, :source, :options]

  Runs the regular expression against the given string until the first match.
  It returns a list with all captures or `nil` if no match occurred.

  When the option `:capture` is set to `:groups`, it will capture all
  the groups in the regex. The option `:return` can be set to `:index`
  to get indexes back.

  ## Examples


  where each entry in the primary list represents a match and each
  entry in the secondary list represents the captured contents.

  ## Options

  * `:return` - Set to `:index` to return indexes. Defaults to `:binary`;
  * `:capture` - What to capture in the result. Check the moduledoc for Regex
                 to see the possible capture values;

  ## Examples

