From 499c481c9dc30792d2f25990a1cc1dcf7bf15660 Mon Sep 17 00:00:00 2001
From: JJ Merelo <jjmerelo@gmail.com>
Date: Wed, 15 Aug 2018 11:58:28 +0200
Subject: [PATCH] Adds definition and example for buf8,-16,-32,-64

Also some reflow here and there. Closes #2264
---
 doc/Type/Buf.pod6 | 48 +++++++++++++++++++++++++++++++++--------------
 doc/Type/Str.pod6 |  4 ++--
 2 files changed, 36 insertions(+), 16 deletions(-)

diff --git a/doc/Type/Buf.pod6 b/doc/Type/Buf.pod6
index 66dc4ace3..cddd4e682 100644
--- a/doc/Type/Buf.pod6
+++ b/doc/Type/Buf.pod6
@@ -11,18 +11,39 @@ A C<Buf> is a mutable sequence of (usually unsigned) integers.
     my $b = Buf.new(1, 2, 3);
     $b[1] = 42;
 
+Some types of C<Buf>s which are used often get their own class name.
+
+X<|buf8>X<|buf16>X<|buf32>X<|buf64>
+=begin table
+buf8 | Buf[uint8]
+buf16 | Buf[uint16]
+buf32 | Buf[uint32]
+buf64 | Buf[uint64]
+=end table
+
+You can use this in pretty much the same way you would with C<Buf>:
+
+    my $buf = buf8.new(3,6, 254);
+    say $buf; # OUTPUT: «Buf[uint8]:0x<03 06 fe>␤»
+
+Plus there are some object methods, like
+L<C<encode>|/type/Str#method_encode> that might return a C<buf8> in some
+cases where it is the best representation for a particular encoding.
+
 =head1 Methods
 
 =head2 method subbuf-rw
 
     method subbuf-rw($from = 0, $elems = self.elems - $from) is rw
 
-A mutable version of C<subbuf> that returns a L<Proxy|/type/Proxy> functioning as a
-writable reference to a part of a buffer. Its first argument, C<$from>
-specifies the index in the buffer from which a substitution should occur, and
-its last argument, C<$elems> specifies how many elements are to be replaced.
+A mutable version of C<subbuf> that returns a L<Proxy|/type/Proxy>
+functioning as a writable reference to a part of a buffer. Its first
+argument, C<$from> specifies the index in the buffer from which a
+substitution should occur, and its last argument, C<$elems> specifies
+how many elements are to be replaced.
 
-For example, to replace one element at index 3 with two elements, C<100> and C<101>:
+For example, to replace one element at index 3 with two elements, C<100>
+and C<101>:
 
     my Buf $b .= new(0..5);
     $b.subbuf-rw(3,1) = Buf.new(100, 101);
@@ -62,15 +83,14 @@ Invokes the C<subbuf-rw> method on the specified C<Buf>:
 
     method reallocate($elems)
 
-Change the number of elements of the C<Buf>, returning the
-changed C<Buf>.
-The size of C<Buf> will be adapted depending on the number of C<$elems>
-specified: if it is smaller than the actual size of the C<Buf> the resulting
-C<Buf> will be shrunk down, otherwise it will be enlarged to fit the
-number of C<$elems>. In the case the C<Buf> is enlarged, newly created items
-will be assigned a Virtual Machine specific null value, therefore
-you should not rely upon their value since it could be inconsistent across
-different virtual machines.
+Change the number of elements of the C<Buf>, returning the changed
+C<Buf>. The size of C<Buf> will be adapted depending on the number of
+C<$elems> specified: if it is smaller than the actual size of the C<Buf>
+the resulting C<Buf> will be shrunk down, otherwise it will be enlarged
+to fit the number of C<$elems>. In the case the C<Buf> is enlarged,
+newly created items will be assigned a Virtual Machine specific null
+value, therefore you should not rely upon their value since it could be
+inconsistent across different virtual machines.
 
 
     my Buf $b .= new(^10);
diff --git a/doc/Type/Str.pod6 b/doc/Type/Str.pod6
index 72eb279e3..807e00e7d 100644
--- a/doc/Type/Str.pod6
+++ b/doc/Type/Str.pod6
@@ -118,8 +118,8 @@ string, and C<NaN> for non-numeric characters.
     multi sub    chars(str   $x --> int)
     multi method chars(Str:D:   --> Int:D)
 
-Returns the number of characters in the string in graphemes. On the JVM, this
-currently erroneously returns the number of codepoints instead.
+Returns the number of characters in the string in graphemes. On the JVM,
+this currently erroneously returns the number of codepoints instead.
 
 =head2 method encode