Merge pull request #714 from kenjis/docs-permissions

docs: improve descriptions on permissions

Author: kenjis

docs/authorization.md

@@ -80,12 +80,20 @@ public $permissions = [
 ## Assigning Permissions to Groups
 
 In order to grant any permissions to a group, they must have the permission assigned to the group, within the `AuthGroups`
-config file, under the `$matrix` property. The matrix is an associative array with the group name as the key,
+config file, under the `$matrix` property.
+
+> **Note** This defines **group-level permissons**.
+
+The matrix is an associative array with the group name as the key,
 and an array of permissions that should be applied to that group.
 
 ```php
 public $matrix = [
-    'admin' => ['admin.access', 'users.create', 'users.edit', 'users.delete', 'beta.access'],
+    'admin' => [
+        'admin.access',
+        'users.create', 'users.edit', 'users.delete',
+        'beta.access'
+    ],
 ];
 ```
 
@@ -104,8 +112,8 @@ The `Authorizable` trait on the `User` entity provides the following methods to
 #### can()
 
 Allows you to check if a user is permitted to do a specific action. The only argument is the permission string. Returns
-boolean `true`/`false`. Will check the user's direct permissions first, and then check against all of the user's groups
-permissions to determine if they are allowed.
+boolean `true`/`false`. Will check the user's direct permissions (**user-level permissions**) first, and then check against all of the user's groups
+permissions (**group-level permissions**) to determine if they are allowed.
 
 ```php
 if ($user->can('users.create')) {
@@ -133,6 +141,10 @@ if (! $user->hasPermission('users.create')) {
 }
 ```
 
+> **Note** This method checks only **user-level permissions**, and does not check
+> group-level permissions. If you want to check if the user can do something,
+> use the `$user->can()` method instead.
+
 #### Authorizing via Routes
 
 You can restrict access to a route or route group through a
@@ -168,7 +180,7 @@ override the group, so it's possible that a user can perform an action that thei
 
 #### addPermission()
 
-Adds one or more permissions to the user. If a permission doesn't exist, a `CodeIgniter\Shield\Authorization\AuthorizationException`
+Adds one or more **user-level** permissions to the user. If a permission doesn't exist, a `CodeIgniter\Shield\Authorization\AuthorizationException`
 is thrown.
 
 ```php
@@ -177,7 +189,7 @@ $user->addPermission('users.create', 'users.edit');
 
 #### removePermission()
 
-Removes one or more permissions from a user. If a permission doesn't exist, a `CodeIgniter\Shield\Authorization\AuthorizationException`
+Removes one or more **user-level** permissions from a user. If a permission doesn't exist, a `CodeIgniter\Shield\Authorization\AuthorizationException`
 is thrown.
 
 ```php
@@ -186,7 +198,7 @@ $user->removePermission('users.delete');
 
 #### syncPermissions()
 
-Updates the user's permissions to only include the permissions in the given list. Any existing permissions on that user
+Updates the user's **user-level** permissions to only include the permissions in the given list. Any existing permissions on that user
 not in this list will be removed.
 
 ```php
@@ -195,12 +207,14 @@ $user->syncPermissions('admin.access', 'beta.access');
 
 #### getPermissions()
 
-Returns all permissions this user has assigned directly to them.
+Returns all **user-level** permissions this user has assigned directly to them.
 
 ```php
 $user->getPermissions();
 ```
 
+> **Note** This method does not return **group-level permissions**.
+
 ## Managing User Groups
 
 #### addGroup()

src/Config/AuthGroups.php

@@ -20,10 +20,11 @@ class AuthGroups extends BaseConfig
      * --------------------------------------------------------------------
      * Groups
      * --------------------------------------------------------------------
-     * An associative array of the available groups in the system, where the keys are
-     * the group names and the values are arrays of the group info.
+     * An associative array of the available groups in the system, where the keys
+     * are the group names and the values are arrays of the group info.
      *
-     * Whatever value you assign as the key will be used to refer to the group when using functions such as:
+     * Whatever value you assign as the key will be used to refer to the group
+     * when using functions such as:
      *      $user->addGroup('superadmin');
      *
      * @var array<string, array<string, string>>
@@ -57,8 +58,7 @@ class AuthGroups extends BaseConfig
      * --------------------------------------------------------------------
      * Permissions
      * --------------------------------------------------------------------
-     * The available permissions in the system. Each system is defined
-     * where the key is the
+     * The available permissions in the system.
      *
      * If a permission is not listed here it cannot be used.
      */
@@ -77,6 +77,8 @@ class AuthGroups extends BaseConfig
      * Permissions Matrix
      * --------------------------------------------------------------------
      * Maps permissions to groups.
+     *
+     * This defines group-level permissions.
      */
     public array $matrix = [
         'superadmin' => [