clear up roles docs

diff --git a/extra/roles/roles-docs.factor b/extra/roles/roles-docs.factor
index e499c14db51804fe5497e6ce91abe9cad7c3bc1d..f3073e20a7d992f6371eec033652f25af5954216 100644 (file)
--- a/extra/roles/roles-docs.factor
+++ b/extra/roles/roles-docs.factor
@@ -47,7 +47,7 @@ HELP: role-slot-overlap
 { $class-description "This error is thrown if a " { $link POSTPONE: TUPLE: } " or " { $link POSTPONE: ROLE: } " definition attempts to inherit a set of " { $link role } "s in which more than one attempts to define the same slot." } ;
 
 ARTICLE: "roles" "Roles"
-"The " { $vocab-link "roles" } " vocabulary implements a way to extend tuple classes that allows them to be composed of multiple roles objects that contain slots." $nl
+"The " { $vocab-link "roles" } " vocabulary provides a form of tuple interface that can be implemented by concrete tuple classes. A " { $link role } " definition is a mixin class that also prescribes a set of tuple slots. Roles are not tuple classes by themselves and cannot be instantiated by " { $link new } ". The vocabulary extends " { $link POSTPONE: TUPLE: } " syntax to allow concrete tuple types to declare membership to one or more roles, automatically including their prescribed slots." $nl
 "The role superclass:"
 { $subsections role }
 "Syntax for making a new role:"
@@ -56,3 +56,5 @@ ARTICLE: "roles" "Roles"
 { $subsection POSTPONE: TUPLE: } 
 "Errors with roles:"
 { $subsections multiple-inheritance-attempted role-slot-overlap } ;
+
+ABOUT: "roles"