diff --git a/lib/stdlib/doc/src/binary.xml b/lib/stdlib/doc/src/binary.xml
index 00f22381d329..9c3637013696 100644
--- a/lib/stdlib/doc/src/binary.xml
+++ b/lib/stdlib/doc/src/binary.xml
@@ -512,41 +512,60 @@ store(Binary, GBSet) ->
Replace bytes in a binary according to a pattern.An integer() =< byte_size(Replacement)
-
+ if Replacement is given as a binary.
-
Constructs a new binary by replacing the parts in
- Subject matching Pattern with
- the content of Replacement.
-
-
If the matching subpart of Subject giving raise
- to the replacement is to be inserted in the result, option
- {insert_replaced, InsPos} inserts the matching part
- into Replacement at the specified position (or
- positions) before inserting Replacement into
- Subject.
+
Constructs a new binary by replacing the parts in
+ Subject matching Pattern with
+ Replacement if given as a literal binary()
+ or with the result of applying Replacement to a matching
+ subpart if given as a fun.
+
+
If Replacement is given as a binary() and the
+ matching subpart of Subject giving raise
+ to the replacement is to be inserted in the result, option
+ {insert_replaced, InsPos} inserts the matching part
+ into Replacement at the specified position (or
+ positions) before inserting Replacement into
+ Subject. If Replacement is given
+ as a fun instead, this option is ignored.
-
Example:
+
If any position specified in InsPos > size
+ of the replacement binary, a badarg exception is raised.