[containers] explain how "is rw" attribute accessors work

Author: moritz

lib/containers.pod

@@ -55,6 +55,28 @@ Inside the subroutine, the lexpad entry for C<$a> points to the same
 container that C<$x> points to outside the subroutine. Which is why assignment
 to C<$a> also modifies the contents of C<$x>.
 
+Likewise a routine can return a container if it is marked as C<is rw>:
+
+    my $x = 23;
+    sub f() is rw { $x };
+    f() = 42;
+    say $x;         # 42
+
+For explicit returns, C<return-rw> instead of C<return> must be used.
+
+Returning a container is how C<is rw> attribute accessors work. So
+
+    class A {
+        has $.attr is rw;
+    }
+
+is equivalent to
+
+    class A {
+        has $!attr;
+        method attr() is rw { $!attr }
+    }
+
 =head2 Binding
 
 Next to assignment, Perl 6 also supports I<binding> with the C<:=> operator.