Document routine trait rw

Author: moritz

lib/Type/Routine.pod

@@ -91,9 +91,60 @@ Calculating 43th prime
 191
 =end code
 
+=head2 trait is pure
+
+    multi sub trait_mod:<is>(Routine $r, :!$pure)
+
+Marks a subroutine as I<pure>, that is, it asserts that for the same input, it
+will always produce the same output without any additional side effects.
+
+This is a hint to the compiler that it can constant-fold calls to such
+functions when the arguments are known at compile time.
+
+    sub double(Numeric:D $x) is pure {
+        2 * $x;
+    }
+
+=head2 trait is rw
+
+    multi sub trait_mod:<is>(Routine $r, :!$rw)
+
+When a routine is modifies with this trait, its return value will be writable.
+This is useful when returning variables or writable elements of hashes or
+arrays, for example:
+
+=begin code
+sub walk(\thing, *@keys) is rw {
+    my $current := thing;
+    for @keys -> $k {
+        if $k ~~ Int {
+            $current := $current[$k];
+        }
+        else {
+            $current := $current{$k};
+        }
+    }
+    $current;
+}
+
+my %hash;
+walk(%hash, 'some', 'key', 1, 2) = 'autovivified';
+
+say %hash.perl;
+=end code
+
+produces
+
+=begin code
+("some" => {"key" => [Any, [Any, Any, "autovivified"]]}).hash
+=end code
+
+Note that C<return> marks return values as read only; if you need an early
+exit from an C<is rw> routine, you have to use C<return-rw> instead.
+
 =begin comment
 
-TODO: traits hidden_from_backtrace, pure, export, rw, DEPRECATED
+TODO: traits hidden_from_backtrace, export, DEPRECATED
 
 =end comment