fixup! Polish documentation for the binary module

lib/stdlib/src/binary.erl

@@ -376,7 +376,7 @@ first(_) ->
 Returns the last byte of binary `Subject` as an integer.
 
 If the size of `Subject` is zero, a `badarg` exception is raised.
-
+a
 ## Examples
 
 ```erlang
@@ -467,17 +467,6 @@ position and length.
 The function returns `{Pos, Length}` for the binary in `Pattern`, starting at
 the lowest position in `Subject`.
 
-## Examples
-
-```erlang
-> binary:match(<<"abcde">>, [<<"bcde">>, <<"cd">>],[]).
-{1,4}
-```
-
-Even though `<<"cd">>` ends before `<<"bcde">>`, `<<"bcde">>` begins first and
-is therefore the first match. If two overlapping matches begin at the same
-position, the longest is returned.
-
 Summary of the options:
 
 - **\{scope, \{Start, Length\}\}** - Only the specified part is searched. Return
@@ -491,6 +480,22 @@ For a description of `Pattern`, see function `compile_pattern/1`.
 If `{scope, {Start,Length}}` is specified in the options such that `Start` >
 size of `Subject`, `Start` \+ `Length` < 0 or `Start` \+ `Length` > size of
 `Subject`, a `badarg` exception is raised.
+
+## Examples
+
+```erlang
+> binary:match(<<"abcde">>, [<<"bcde">>, <<"cd">>],[]).
+{1,4}
+```
+
+Even though `<<"cd">>` ends before `<<"bcde">>`, `<<"bcde">>` begins first and
+is therefore the first match. If two overlapping matches begin at the same
+position, the longest is returned.
+
+```erlang
+> binary:match(~"the rain in spain", ~"ain", []).
+{5,3}
+```
 """.
 -doc(#{since => <<"OTP R14B">>}).
 -spec match(Subject, Pattern, Options) -> Found | nomatch when
@@ -531,7 +536,7 @@ the following example:
 The result shows that <<"bcde">> is selected instead of the shorter match
 <<"bc">> (which would have given raise to one more match, <<"de">>). This
 corresponds to the behavior of POSIX regular expressions (and programs like
-awk), but is not consistent with alternative matches in `re` (and Perl), where
+`awk`), but is not consistent with alternative matches in `re` (and Perl), where
 instead lexical ordering in the search pattern selects which string matches.
 
 If none of the strings in a pattern is found, an empty list is returned.
@@ -542,6 +547,13 @@ available options, see `match/3`.
 If `{scope, {Start,Length}}` is specified in the options such that `Start` >
 size of `Subject`, `Start + Length` < 0 or `Start + Length` is > size of
 `Subject`, a `badarg` exception is raised.
+
+## Examples
+
+```erlang
+> binary:matches(~"the rain in spain", ~"ai", []).
+[{5,2},{14,2}]
+```
 """.
 -doc(#{since => <<"OTP R14B">>}).
 -spec matches(Subject, Pattern, Options) -> Found when