No documentation on hierarchical roles

Hierarchical roles landed a while ago, however, there is no documentation on how to describe hierarchies or specify subroles. This is particularly important since hierarchical roles are not straightforward, i.e.:

1. role gives permissions to role but not its sub-roles.
2. role/% gives permissions to all subroles of role but not role itself.
3. role/subrole gives permission to the subrole subrole
4. * is not a wildcard character as many users expect.