   Notice we had to escape the escape character `\`. By giving `\0`,
   one can inject the whole matched pattern in the replacement string.
 
-  When strings are used as a pattern, a developer can also use the
-  replaced part inside the `replacement` via the `:insert_replaced` option:
+  When the pattern is a string, a developer can use the replaced part inside
+  the `replacement` by using the `:insert_replace` option and specifying the
+  position(s) inside the `replacement` where the string pattern will be
+  inserted:
 
       iex> String.replace("a,b,c", "b", "[]", insert_replaced: 1)
       "a,[b],c"

      iex> String.replace("a,b,c", ",", "[]", insert_replaced: [1, 1])
      "a[,,]b[,,]c"

  """
  @spec replace(t, pattern | Regex.t, t, Keyword.t) :: t
  def replace(subject, pattern, replacement, options \\ []) when is_binary(replacement) do

  Returns a new binary created by replacing occurences of `pattern` in
  `subject` with `replacement`.

  By default, it replaces all occurences, unless the `global` option is
  set to `false`.

  The `pattern` may be a string or a regular expression.

  ## Examples

