Adds explanations on native types refs #1512

Author: JJ

doc/Language/nativetypes.pod6

@@ -4,9 +4,11 @@
 
 =SUBTITLE Using the types the compiler and hardware make available to you.
 
+X<|int>X<|uint>X<|num>X<|str>
+=head1 Types with native representation
+
 Some simple types in Perl 6 have a I<native> representation, indicating that they will use the C language representation provided by the compiler, operating system and machine. These are the four native types available:
 
-X<|int>X<|uint>X<|num>X<|str>
 =begin table
     int            Equivalent to Int
     uint           Equivalent to Int with the unsigned trait
@@ -19,20 +21,57 @@ L<NativeCall|/lang/nativecall> interface (e.g., Perl 6's C<int> can be 8 bytes
 but C's C<int> is only 4 bytes). Instead, the types below will have to be used
 instead of the types C<int> or C<num> listed above.
 
-X<|int8>X<|int16>X<|int32>X<|int64>X<|uint8>X<|uint16>X<|uint32>X<|uint64>X<|num32>X<|num64>
+In general, these variables will behave in the same way as regular scalar
+variables, in a behavior that is called I<auto-boxing>; however, there are some
+differences, since what you are actually declaring is how they will be
+represented, not their actual type. The first one is that their type will be
+actually their equivalent type, not their native type.
+
+    my int $intillo = 3;
+    say $intillo.^name; # OUTPUT: «Int␤»
+
+This obviously means that they will smartmatch their equivalent, not their
+native type:
+
+    my str $strillo = "tres";
+    say $strillo ~~ str; # OUTPUT: «False␤»
+    say $strillo ~~ Str; # OUTPUT: «True␤»
+
+They cannot be bound either. Trying to do C<my num $numillo := 3.5> will raise
+the exception C<Cannot bind to natively typed variable '$variable-name'; use
+assignment instead>.
+
+X<|int8>X<|int16>X<|int32>X<|int64>X<|uint8>X<|uint16>X<|uint32>X<|uint64>X<|num32>X<|num64>X<|byte>
+=head1 Types with native representation and size
+
+What has been mentioned about types with native representation also applies
+here; they will be auto-boxed to Perl 6 types and will not be boundable.
+However, these types, which are listed in the table below, have the
+characteristic of being usable in L<NativeCall> functions.
+
 =begin table
     int8           (int8_t in C, also used for char)
     int16          (int16_t in C, also used for short)
     int32          (int32_t in C, also used for int)
     int64          (int64_t in C)
-    uint8          (uint8_t in C, also used for unsigned char)
+    byte, uint8    (uint8_t in C, also used for unsigned char)
     uint16         (uint16_t in C, also used for unsigned short)
     uint32         (uint32_t in C, also used for unsigned int)
     uint64         (uint64_t in C)
     num32          (float in C)
     num64          (double in C)
 =end table
 
+These types have a fixed size representation which is independent of the
+platform, and thus can be used safely for those calls. Nothing prevents us from
+using it in any other environment, if we so wish. In the same way as the types
+above, this size will have to be taken into account when assigning values to
+variables of this type:
+
+    my byte $intillo = 257;
+    say $intillo; # OUTPUT: «1␤»
+
+Since C<byte> is able to hold only 8 bits, it will I<wrap over> and assign the result of the original value modulo 256, which is what is shown.
 
 =end pod