Reorganizes and adds info on «is» for classes. Refs #1957

Author: JJ

doc/Language/traits.pod6

@@ -8,41 +8,33 @@ In Perl 6,  I<traits> are compiler hooks attached to objects and classes that
 modify their default behavior, functionality or representation. As such compiler
 hooks, they are defined in compile time, although they can be used in runtime.
 
+Several traits are already defined as part of the language or the Rakudo
+compiler by using the C<trait_mod> keyword. They are listed, and explained,
+next.
+
 =head1 The X<C<is> trait|is (trait)>
 
-Traits are used extensively in L<native calls|/language/nativecall> to
-L<specify the representation|/language/nativecall#Specifying_the_native_representation>
-of the
-data structures that are going to be handled by the native functions via the
-C<is repr> suffix; at the same time, C<is native> is used for the routines that
-are actually implemented via native functions. These are the representations
-that can be used:
+Defined as
 
-=item X<CStruct> corresponds to a C<struct> in the C language. It is a composite
-data structure which includes different and heterogeneous lower-level data
-structures; see L<this|/language/nativecall#Structs> for examples and further
-explanations.
+    proto sub trait_mod:<is>(Mu $, |) {*}
 
-=item X<CPPStruct>, similarly, correspond to a C<struct> in C++. However, this
-is Rakudo specific for the time being.
+C<is> applies to any kind of scalar object, and can take any number of named or
+positional arguments. It is the most commonly used trait, and takes the
+following forms, depending on the type of the first argument.
 
-=item X<CPointer> is a pointer in any of these languages. It is a dynamic data
-structure that must be instantiated before being used, can be
-L<used|/language/nativecall#Basic_use_of_Pointers> for classes whose methods are
-also native.
+=head2 C<is> applied to classes.
 
-=item X<CUnion> is going to use the same representation as an C<union> in C; see
-L<this|/language/nativecall#CUnions> for an example.
+The most common form, involving two classes, one that is being defined and the
+other existing, L<defines parenthood|/syntax/is>. C<A is B>, if both are
+classes, defines A as a subclass of B.
 
-On the other hand, X<P6opaque> is the default representation used for all
-objects in Perl 6.
-
-    m: class Thar {};
-    say Thar.REPR;    #OUTPUT: «P6opaque␤»
+L<C<is DEPRECATED>|/Attribute#trait_is_DEPRECATED> can be applied to classes,
+Attributes or Routines, marks them as deprecated and issues a message, if
+provided.
 
-The L<meta object protocol|/language/mop> uses it by default for every object
-and class unless specified otherwise; for that reason, it is in general not
-necessary unless you are effectively working with that interface.
+Several instances of C<is> are translated directly into attributes for the class
+they refer to: C<rw>, C<nativesize>, C<ctype>, C<unsigned>, C<hidden>,
+C<array_type>.
 
 The X<Uninstantiable representation trait> is not so much related to the
 representation as related to what can be done with an specific class; it
@@ -67,7 +59,44 @@ methods, as above. However, trying to instantiate them this way: C<my
 $do-instantiate = don't-instantiate.new;> will yield the error C<You
 cannot create an instance of this type (don't-instantiate)>.
 
-=head3 C<is> on routines
+=head2 C<is repr> and native representations.
+
+Since the C<is> trait refers, in general, to the nature of the class or object
+they are applied to, they are used extensively in
+L<native calls|/language/nativecall> to L<specify the representation|/language/nativecall#Specifying_the_native_representation>
+of the data structures that are going to be handled by the native functions via
+the C<is repr> suffix; at the same time, C<is native> is used for the routines
+that are actually implemented via native functions. These are the
+representations that can be used:
+
+=item X<CStruct> corresponds to a C<struct> in the C language. It is a composite
+data structure which includes different and heterogeneous lower-level data
+structures; see L<this|/language/nativecall#Structs> for examples and further
+explanations.
+
+=item X<CPPStruct>, similarly, correspond to a C<struct> in C++. However, this
+is Rakudo specific for the time being.
+
+=item X<CPointer> is a pointer in any of these languages. It is a dynamic data
+structure that must be instantiated before being used, can be
+L<used|/language/nativecall#Basic_use_of_Pointers> for classes whose methods are
+also native.
+
+=item X<CUnion> is going to use the same representation as an C<union> in C; see
+L<this|/language/nativecall#CUnions> for an example.
+
+On the other hand, X<P6opaque> is the default representation used for all
+objects in Perl 6.
+
+    m: class Thar {};
+    say Thar.REPR;    #OUTPUT: «P6opaque␤»
+
+The L<meta object protocol|/language/mop> uses it by default for every object
+and class unless specified otherwise; for that reason, it is in general not
+necessary unless you are effectively working with that interface.
+
+
+=head2 C<is> on routines
 
 The C<is> trait can be used on the definition of methods and routines to
 establish L<precedence|/functions#Precedence> and