Bug 1226252: fill out roles docs

src/manual/apis/roles.md

@@ -11,9 +11,6 @@ constitutes a simple _expansion rule_ that says if you have the scope
 `assume:<roleId>` you get the set of scopes associated with the role named
 `roleId`.  Roles can refer to other roles in the same way.
 
-It is common to think of roles as a kind of shorthand for scopes.  Another
-perspective is to think of `assume:<roleId>` as a scope that allows a client to
-assume the named role.
 
 Stars in Roles
 --------------
@@ -23,6 +20,21 @@ As in scopes, a final `*` in a role ID acts as a wildcard.  It matches any
 `repo:github.com/taskcluster/*` will match
 `assume:repo:github.com/taskcluster/taskcluster-auth`.
 
+When roles are concerned, stars expand in two ways:
+
+ * (scope expansion) An `assume` scope ending in a star will satisfy any scope
+   implied by any role of which it is a prefix.  For example, if role
+   `repo:github.com/taskcluster/taskcluster-auth` has scope
+   `secrets:get:auth-tests`, then credentials with scope
+   `assume:repo:github.com/taskcluster/*` can get the `auth-tests` secret.
+   This means that `assume:` scopes ending in a star can be very powerful!
+
+ * (role expansion) A role ending in a star will apply to all roles of which it
+   is a prefix.  For example, if role `hook:taskcluster/*` has scope
+   `queue:create-task:aws-provisioner/taskcluster-hooks`, then a credential
+   with `assume:hook:taskcluster/nightly-diagnostics` can create a task with
+   the `taskcluster-hooks` worker type.
+
 In Practice
 -----------
 
@@ -31,6 +43,7 @@ In practice, roles are used in a few ways within TaskCluster:
  * As a shorthand for a commonly-used set of scopes
  * As a means of associating scopes with external things such as source-code repositories or users
  * As a way to configure scopes for TaskCluster resources like hooks or worker types
+ * As a scope allowing the bearer to "assume" the named role.
 
 See the [namespaces](../../devel/namespaces/) document for more information.