fixup! Polish documentation for the binary module

lib/stdlib/src/binary.erl

@@ -27,12 +27,13 @@ bit syntax, the functions in this module are highly optimized and are
 expected to either execute faster or consume less memory, or both,
 compared to equivalent implementations written in pure Erlang.
 
-The module is provided according to Erlang Enhancement Proposal (EEP) 31.
+The module is provided according to [EEP 31: Binary manipulation and
+searching module](https://www.erlang.org/eeps/eep-0031).
 
 > #### Note {: .info }
 >
-> The library handles byte-oriented data. For bitstrings that are not binaries
-> (does not contain whole octets of bits) a `badarg` exception is thrown from
+> This module handles byte-oriented data. For bitstrings that are not binaries
+> (does not contain whole octets of bits) a `badarg` exception is raised from
 > any of the functions in this module.
 """.
 -moduledoc(#{since => "OTP R14B"}).
@@ -103,14 +104,14 @@ at(_, _) ->
     erlang:nif_error(undef).
 
 -doc """
-Converts `Subject` to a list of `t:byte/0`s, each representing the value of one byte.
+Converts `Subject` to a list of [`byte()`](`t:byte/0`)s, each
+representing the value of one byte.
 
 ## Examples
 
 ```erlang
-> binary:bin_to_list(<<"erlang">>).
-"erlang"
-%% or [101,114,108,97,110,103] in list notation.
+> binary:bin_to_list(<<"erlang",0>>).
+[101,114,108,97,110,103,0]
 ```
 
 """.
@@ -376,7 +377,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
@@ -394,7 +395,7 @@ last(_) ->
 -doc """
 Works exactly as `erlang:list_to_binary/1`.
 
-This function has been added for completeness.
+This function was added for completeness.
 """.
 -doc(#{since => <<"OTP R14B">>}).
 -spec list_to_bin(ByteList) -> binary() when
@@ -612,17 +613,11 @@ part(_, _, _) ->
 -doc """
 Get the size of the underlying binary referenced by `Binary`.
 
-If a binary references a larger binary (often described as being a subbinary),
-it can be useful to get the size of the referenced binary. This function can be
-used in a program to trigger the use of `copy/1`. By copying
-a binary, one can dereference the original, possibly large, binary that a
-smaller binary is a reference to.
-
 If a binary references a larger binary (often called a subbinary), it
 can be useful to determine the size of the referenced binary. This
 function can be used to decide when to trigger `copy/1`. Copying a
-binary allows dereferencing the original, potentially large, binary
-that the smaller binary refers to.
+binary can help eliminate the reference to the original, potentially
+large, binary that the smaller binary depends on.
 
 > #### Note {: .info }
 >
@@ -922,16 +917,16 @@ encode_hex(Bin) ->
     error_with_info(badarg, [Bin]).
 
 -doc """
-Encodes a binary into a hex encoded binary using the specified case for the
+Encodes a binary into a hex-encoded binary using the specified case for the
 hexadecimal digits "a" to "f".
 
 The default case is `uppercase`.
 
 ## Examples
 
 ```erlang
-> binary:encode_hex(<<"f">>).
-<<"66">>
+> binary:encode_hex(<<"foo">>).
+<<"666F6F">>
 > binary:encode_hex(<<"/">>).
 <<"2F">>
 > binary:encode_hex(<<"/">>, lowercase).
@@ -1036,13 +1031,16 @@ hex(X, Offset) ->
 
 -compile({inline, [unhex/1]}).
 -doc """
-Decodes a hex encoded binary into a binary.
+Decodes a hex-encoded binary into a binary.
+
+An exception is raised if the size of the binary is not evenly divisble by two,
+or if the binary contains any characters that do not represent hex digits.
 
 ## Examples
 
 ```erlang
-> binary:decode_hex(<<"66">>).
-<<"f">>
+> binary:decode_hex(<<"666f6f">>).
+<<"foo">>
 ```
 """.
 -doc(#{since => <<"OTP 24.0">>}).