encoding/binary: adjust docs for Append, Encode and Decode

Updates #60023

Change-Id: Ida1cc6c4f5537402e11db6b8c411828f2bcc0a5e
Reviewed-on: https://go-review.googlesource.com/c/go/+/587096
Reviewed-by: Austin Clements <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>

src/encoding/binary/binary.go

@@ -272,9 +272,9 @@ func Read(r io.Reader, order ByteOrder, data any) error {
 	return nil
 }
 
-// Decode binary data from buf into data according to the given byte order.
-//
-// Returns an error if buf is too small, otherwise the number of
+// Decode decodes binary data from buf into data according to
+// the given byte order.
+// It returns an error if buf is too small, otherwise the number of
 // bytes consumed from buf.
 func Decode(buf []byte, order ByteOrder, data any) (int, error) {
 	if n, _ := intDataSize(data); n != 0 {
@@ -415,10 +415,10 @@ func Write(w io.Writer, order ByteOrder, data any) error {
 	return err
 }
 
-// Encode the binary representation of data into buf according to the given byte order.
-//
-// Returns an error if the buffer is too short, otherwise the number of bytes
-// written into buf.
+// Encode encodes the binary representation of data into buf according to
+// the given byte order.
+// It returns an error if buf is too small, otherwise the number of
+// bytes written into buf.
 func Encode(buf []byte, order ByteOrder, data any) (int, error) {
 	// Fast path for basic types and slices.
 	if n, _ := intDataSize(data); n != 0 {
@@ -445,12 +445,10 @@ func Encode(buf []byte, order ByteOrder, data any) (int, error) {
 	return size, nil
 }
 
-// Append the binary representation of data to buf.
-//
+// Append appends the binary representation of data to buf.
 // buf may be nil, in which case a new buffer will be allocated.
 // See [Write] on which data are acceptable.
-//
-// Returns the (possibily extended) buffer containing data or an error.
+// It returns the (possibily extended) buffer containing data or an error.
 func Append(buf []byte, order ByteOrder, data any) ([]byte, error) {
 	// Fast path for basic types and slices.
 	if n, _ := intDataSize(data); n != 0 {