Adds TWEAK examples, closes #1393

Author: JJ

doc/Language/classtut.pod6

@@ -35,6 +35,7 @@ say $r.area(); # OUTPUT: «100␤»
 In the two classes, the default constructor is being used. This constructor will
 use named parameters in its invocation: C<Point.new(x => 0, y => 0)>.
 
+X<submethods>
 You can also provide your own construction and C<BUILD> implementation.  The
 following, more elaborate example shows how a dependency handler might look in
 Perl 6.  It showcases custom constructors, private and public attributes,
@@ -95,6 +96,30 @@ parameters. That is one of the reasons why using C<new> is discouraged. If you
 need to declare it anyway, use C<multi method new> if you do not want to disable
 the default constructors.
 
+C<TWEAK> is the last submethod to be called, and it has got the advantage of
+having the object properties available without needing to use the meta object
+protocol. It can be used, for instance, to assign values to instance variables
+based on the values of other attributes or instance variables:
+
+=begin code
+class Str-with-ID is Str {
+    my $.counter = 0;
+    has Str $.string;
+    has Int $.ID;
+
+    method TWEAK() {
+        $!ID = $.counter++;
+    }
+}
+
+say Str-with-ID.new(string => 'First').ID;  # OUTPUT: «0»
+say Str-with-ID.new(string => 'Second').ID; # OUTPUT: «1»
+=end code
+
+In this case, we need to compute C<$.ID> from the value of a counter that is a
+class variable, C<$.counter>, thus we simply assign a value to it and increment
+the counter at the same time.
+
 =head1 Starting with class
 
 X<|class>
@@ -239,7 +264,7 @@ class Str-with-ID is Str {
     has Int $.ID;
 
     method new( Str $string ) {
-        self.bless( $:string, ID => $.counter++ )
+        self.bless( :$string, ID => $.counter++ )
     }
 }
 
@@ -250,7 +275,10 @@ say Str-with-ID.new('Second').ID; # OUTPUT: «1»
 In this case, using C<new> might be the easiest way to initialize the C<$.ID>
 field and increment the value of the counter at the same time. C<new>, through
 C<bless>, will invoke the default C<BUILD>, assigninng the values to their
-properties correctly.
+properties correctly. You can obtain the same effect using C<TWEAK>, which is
+considered a more I<p6y> way. Please check <the section on submethods|/language/classtut#index-entry-OOP>
+for an alternative example on how
+to do this.
 
 =head1 Static fields?
 

doc/Language/objects.pod6

@@ -630,21 +630,21 @@ need to C<callsame> to invoke the parent classes C<BUILDALL>.
     }
     =end code
 
-The C<TWEAK> method allows you to check things or modify attributes after
+The C<TWEAK> submethod allows you to check things or modify attributes after
 object construction:
 
-    =begin code
-    class RectangleWithCachedArea {
-        has ($.x1, $.x2, $.y1, $.y2);
-        has $.area;
-        submethod TWEAK() {
-            $!area = abs( ($!x2 - $!x1) * ( $!y2 - $!y1) );
-        }
+=begin code
+class RectangleWithCachedArea {
+    has ($.x1, $.x2, $.y1, $.y2);
+    has $.area;
+    submethod TWEAK() {
+        $!area = abs( ($!x2 - $!x1) * ( $!y2 - $!y1) );
     }
+}
 
-    say RectangleWithCachedArea.new( x2 => 5, x1 => 1, y2 => 1, y1 => 0).area;
-    # OUTPUT: «4␤»
-    =end code
+say RectangleWithCachedArea.new( x2 => 5, x1 => 1, y2 => 1, y1 => 0).area;
+# OUTPUT: «4␤»
+=end code
 
 =head2 Object Cloning