Merge pull request #3052 from perl6/new-write-int-semantics

Document the new semantics of Buf.write-int* methods

doc/Type/Buf.pod6

@@ -315,7 +315,6 @@ Defined as:
 Writes a native C<num64> IEEE floating point value at the given position with
 the given endianness.
 
-
 =head1 Methods on buf8 only (6.d, 2019.03 and later)
 
 =head2 method write-ubits
@@ -338,6 +337,153 @@ Writes a signed integer value for the B<bits> from the given B<bit> offset
 and given number of bits.  The endianness of the bits is assumed to be
 C<BigEndian>.  Always returns Nil.
 
+=head1 Methods on buf8 only (6.d, 2019.10 and later)
+
+These methods are available on the C<buf8> type only.  They allow low level
+access to writing bytes to the underlying data and in different ways with
+regards to type (integer or floating point (num)), size (8, 16, 32, 64 or 128
+bits), signed or unsigned (for integer values) and endianness (native, little
+and big endianness).
+
+These methods can also be called on the C<buf8> type object, in which case
+a new C<buf8> object will be returned.  Otherwise, the invocant will be
+returned to allow for easier chaining of operations on the C<buf8> object.
+The buffer will be automatically resized to support any bytes being written
+if it is not large enough yet.
+
+Endianness must be indicated by using values of the L<Endian|/type/Endian>
+enum as the B<third> parameter to these methods.  If no endianness is
+specified, C<NativeEndian> will be assumed.  Other values are
+C<LittleEndian> and C<BigEndian>.
+
+=head2 method write-uint8
+
+Defined as:
+
+    method write-uint8(buf8: uint $pos, uint8 $value, $endian = NativeEndian --> buf8:D)
+
+Writes an unsigned 8-bit integer value at the given position.  The C<$endian>
+parameter has no meaning, but is available for consistency.
+
+=head2 method write-int8
+
+Defined as:
+
+    method write-int8(buf8: uint $pos, int8 $value, $endian = NativeEndian --> buf8:D)
+
+Writes a signed 8-bit integer value at the given position.  The C<$endian>
+parameter has no meaning, but is available for consistency.
+
+=head2 method write-uint16
+
+Defined as:
+
+    method write-uint16(buf8: uint $pos, uint16 $value, $endian = NativeEndian --> buf8:D)
+
+Writes an unsigned 16-bit integer value at the given position with the given
+endianness.
+
+=head2 method write-int16
+
+Defined as:
+
+    method write-int16(buf8: uint $pos, int16 $value, $endian = NativeEndian --> buf8:D)
+
+Writes a signed 16-bit integer value at the given position with the given
+endianness.
+
+=head2 method write-uint32
+
+Defined as:
+
+    method write-uint32(buf8: uint $pos, uint32 $value, $endian = NativeEndian --> buf8:D)
+
+Writes an unsigned 32-bit integer value at the given position with the given
+endianness.
+
+=head2 method write-int32
+
+Defined as:
+
+    method write-int32(buf8: uint $pos, int32 $value, $endian = NativeEndian --> buf8:D)
+
+Writes a signed 32-bit integer value at the given position with the given
+endianness.
+
+=head2 method write-uint64
+
+Defined as:
+
+    method write-uint64(buf8: uint $pos, uint64 $value, $endian = NativeEndian --> buf8:D)
+
+Writes an unsigned 64-bit integer value at the given position with the given
+endianness.
+
+=head2 method write-int64
+
+Defined as:
+
+    method write-int64(buf8: uint $pos, Int:D $value, $endian = NativeEndian --> buf8:D)
+
+Writes a signed 64-bit integer value at the given position with the given
+endianness.
+
+=head2 method write-uint128
+
+Defined as:
+
+    method write-uint128(buf8: uint $pos, UInt:D $value, $endian = NativeEndian --> buf8:D)
+
+Writes an unsigned 128-bit integer value at the given position with the given
+endianness.
+
+=head2 method write-int128
+
+Defined as:
+
+    method write-int128(buf8: uint $pos, Int:D $value, $endian = NativeEndian --> buf8:D)
+
+Writes a signed 128-bit integer value at the given position with the given
+endianness.
+
+=head2 method write-num32
+
+Defined as:
+
+    method write-num32(buf8: uint $pos, num32 $value, $endian = NativeEndian --> buf8:D)
+
+Writes a native C<num32> IEEE floating point value at the given position with
+the given endianness.
+
+=head2 method write-num64
+
+Defined as:
+
+    method write-num64(buf8: uint $pos, num64 $value, $endian = NativeEndian --> buf8:D)
+
+Writes a native C<num64> IEEE floating point value at the given position with
+the given endianness.
+
+=head2 method write-ubits
+
+Defined as:
+
+    method write-ubits(buf8: uint $pos, uint $bits, UInt:D $value --> buf8:D)
+
+Writes an unsigned integer value to the B<bits> from the given B<bit> offset
+and given number of bits.  The endianness of the bits is assumed to be
+C<BigEndian>.
+
+=head2 method write-bits
+
+Defined as:
+
+    method write-bits(buf8: uint $pos, uint $bits, Int:D $value --> buf8:D)
+
+Writes a signed integer value for the B<bits> from the given B<bit> offset
+and given number of bits.  The endianness of the bits is assumed to be
+C<BigEndian>.
+
 =end pod
 
 # vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6