Comment fixes + class descriptions added

framework/rbac/Assignment.php

@@ -11,6 +11,15 @@ use Yii;
 use yii\base\Object;
 
 /**
+ * Assignment represents an assignment of a role to a user.
+ * It includes additional assignment information such as [[bizRule]] and [[data]].
+ * Do not create a Assignment instance using the 'new' operator.
+ * Instead, call [[IManager::assign]].
+ *
+ * @property mixed $userId User ID (see [[User::id]]).
+ * @property string $itemName The authorization item name.
+ * @property string $bizRule The business rule associated with this assignment.
+ * @property mixed $data Additional data for this assignment.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @author Alexander Kochetov <creocoder@gmail.com>

framework/rbac/DbManager.php

@@ -14,6 +14,14 @@ use yii\base\Exception;
 use yii\base\InvalidConfigException;
 
 /**
+ * DbManager represents an authorization manager that stores authorization information in database.
+ *
+ * The database connection is specified by [[db]]. And the database schema
+ * should be as described in "framework/rbac/*.sql". You may change the names of
+ * the three tables used to store the authorization data by setting [[itemTable]],
+ * [[itemChildTable]] and [[assignmentTable]].
+ *
+ * @property array $authItems The authorization items of the specific type.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @author Alexander Kochetov <creocoder@gmail.com>
@@ -60,9 +68,9 @@ class DbManager extends Manager
 
 	/**
 	 * Performs access check for the specified user.
-	 * @param mixed $userId the user ID. This should can be either an integer and a string representing
+	 * @param mixed $userId the user ID. This should can be either an integer or a string representing
-	 * @param string $itemName the name of the operation that need access check
 	 * the unique identifier of a user. See [[User::id]].
+	 * @param string $itemName the name of the operation that need access check
 	 * @param array $params name-value pairs that would be passed to biz rules associated
 	 * with the tasks and roles assigned to the user. A param with name 'userId' is added to this array,
 	 * which holds the value of `$userId`.

framework/rbac/IManager.php

@@ -10,6 +10,8 @@ namespace yii\rbac;
 /**
  * IManager interface is implemented by an auth manager application component.
  *
+ * An auth manager is mainly responsible for providing role-based access control (RBAC) service.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @author Alexander Kochetov <creocoder@gmail.com>
  * @since 2.0

framework/rbac/Item.php

@@ -11,6 +11,20 @@ use Yii;
 use yii\base\Object;
 
 /**
+ * Item represents an authorization item.
+ * An authorization item can be an operation, a task or a role.
+ * They form an authorization hierarchy. Items on higher levels of the hierarchy
+ * inherit the permissions represented by items on lower levels.
+ * A user may be assigned one or several authorization items (called [[Assignment]] assignments).
+ * He can perform an operation only when it is among his assigned items.
+ *
+ * @property IManager $authManager The authorization manager.
+ * @property integer $type The authorization item type. This could be 0 (operation), 1 (task) or 2 (role).
+ * @property string $name The item name.
+ * @property string $description The item description.
+ * @property string $bizRule The business rule associated with this item.
+ * @property mixed $data The additional data associated with this item.
+ * @property array $children All child items of this item.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @author Alexander Kochetov <creocoder@gmail.com>

framework/rbac/Manager.php

@@ -12,6 +12,30 @@ use yii\base\Component;
 use yii\base\Exception;
 
 /**
+ * Manager is the base class for authorization manager classes.
+ *
+ * Manager extends [[Component]] and implements some methods
+ * that are common among authorization manager classes.
+ *
+ * Manager together with its concrete child classes implement the Role-Based
+ * Access Control (RBAC).
+ *
+ * The main idea is that permissions are organized as a hierarchy of
+ * [[Item]] authorization items. Items on higer level inherit the permissions
+ * represented by items on lower level. And roles are simply top-level authorization items
+ * that may be assigned to individual users. A user is said to have a permission
+ * to do something if the corresponding authorization item is inherited by one of his roles.
+ *
+ * Using authorization manager consists of two aspects. First, the authorization hierarchy
+ * and assignments have to be established. Manager and its child classes
+ * provides APIs to accomplish this task. Developers may need to develop some GUI
+ * so that it is more intuitive to end-users. Second, developers call [[IManager::checkAccess()]]
+ * at appropriate places in the application code to check if the current user
+ * has the needed permission for an operation.
+ *
+ * @property array $roles Roles (name=>Item).
+ * @property array $tasks Tasks (name=>Item).
+ * @property array $operations Operations (name=>Item).
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @author Alexander Kochetov <creocoder@gmail.com>

framework/rbac/PhpManager.php

@@ -11,6 +11,17 @@ use Yii;
 use yii\base\Exception;
 
 /**
+ * PhpManager represents an authorization manager that stores authorization
+ * information in terms of a PHP script file.
+ *
+ * The authorization data will be saved to and loaded from a file
+ * specified by [[authFile]], which defaults to 'protected/data/rbac.php'.
+ *
+ * PhpManager is mainly suitable for authorization data that is not too big
+ * (for example, the authorization data for a personal blog system).
+ * Use [[DbManager]] for more complex authorization data.
+ *
+ * @property array $authItems The authorization items of the specific type.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @author Alexander Kochetov <creocoder@gmail.com>
@@ -20,7 +31,7 @@ class PhpManager extends Manager
 {
 	/**
 	 * @var string the path of the PHP script that contains the authorization data.
-	 * If not set, it will be using 'protected/data/auth.php' as the data file.
+	 * If not set, it will be using 'protected/data/rbac.php' as the data file.
 	 * Make sure this file is writable by the Web server process if the authorization
 	 * needs to be changed.
 	 * @see loadFromFile