roles and stubs

lib/objects.pod

@@ -375,6 +375,33 @@ produces the same class C<C> as
     }
     class C does R2 does R1 { }
 
+=head2 Stubs
+
+When a role contains a stubbed method, a non-stubbed version of a method
+of the same name must be supplied at the time the role is applied to a class.
+This allows you to create roles that act as abstract interfaces.
+
+    role AbstractSerializable {
+        method serialize() { ... }  # literal ... here marks the
+                                    # method as a stub
+    }
+
+    # the following is a compile time error, for example
+    #        Method 'serialize' must be implemented by Point because
+    #        it is required by a role
+    class APoint does AbstractSerializable {
+        has $.x;
+        has $.y;
+    }
+
+    # this works:
+    class SPoint does AbstractSerializable {
+        has $.x;
+        has $.y;
+        method serialize() { "p($.x, $.y)" }
+    }
+
+The implementation of the stubbed method may also be provided by another role.
 
 
 TODO:  parameterized roles