Document additional options for String.split/3 (#5217)

Issue #5213

1 files changed, 7 insertions, 0 deletions

diff --git a/lib/elixir/lib/string.ex b/lib/elixir/lib/string.ex
index 8c28c99f6..306e93fc7 100644
--- a/lib/elixir/lib/string.ex
+++ b/lib/elixir/lib/string.ex
@@ -276,6 +276,10 @@ defmodule String do
   Empty strings are only removed from the result if the
   `trim` option is set to `true` (default is `false`).
 
+  When the pattern used is a regular expression, the string is
+  split using `Regex.split/3`. In that case this function accepts
+  additional options which are documented in `Regex.split/3`.
+
   ## Examples
 
   Splitting with a string pattern:
@@ -305,6 +309,9 @@ defmodule String do
       iex> String.split(" a b c ", ~r{\s}, trim: true)
       ["a", "b", "c"]
 
+      iex> String.split("abc", ~r{b}, include_captures: true)
+      ["a", "b", "c"]
+
   Splitting on empty patterns returns graphemes:
 
       iex> String.split("abc", ~r{})