Hola,
en realidad es mucho (muchísimo) más complejo que eso, aunque seguramente no necesiten utilizar todo el potencial de los mismos. Estamos mejorando la documentación de esa parte, pero mientras te explico por encima:
Ahora puedes tener varias cláusulas "when" con sus "return" respectivos (son como una especie de "if" anidados al fin y al cabo). En los return no solo puedes asignar esos valores que nombras: editable, visible, oculto. Te hago un breve resúmen: En realidad se hacen diferencias entre lo que se puede hacer en cuanto a la "vista" (editable, visible, oculto); que no tiene nada que ver con lo que se puede hacer con respecto a las acciones o entidades (crear, editar, leer, borrar); y se complica mucho más cuando mezclas ambas cosas...
all -> permite "hacer" de todo básicamente.
denegar -> no permite hacer nada (es como que no cumple ninguna de las cláusulas "when")
Respecto al aspecto gráfico
editable -> el contenido visualmente es "editable"
visible -> es visible
oculto -> evidentemente no se vería
Respecto a acciones:
leer
editar
crear
borrar
permitirá unas cosas u otras (puedes agruparlas incluso).
Más complejo es aún, que permite entre otras cosas devolver "pares"; es decir para una acción específica permito un "aspecto gráfico"; un ejemplo (aunque no tiene sentido en este caso): Si la acción con la que entro en la página es "leer", permitiré que el contenido sea "editable"; en esos casos devolvería el par "leer : editable"..... y lo que resulta interesante de estos casos es que puedes devolver varios "pares" de acción-grafico en el mismo return del permiso.
Evidentemente se que es complicado el tema de los permisos, tanto la sintaxis como la semántica de los mismos; Siempre puedes sobreescribir programáticamente los mismos, para "permitir lo que quieras". Tienes algún ejemplo de como hacerlo en:
Aunque con "all, editable, visible y oculto" seguramente podrás hacer el 90% de lo que quieras.
Saludos.