(NFC) CRM_Core_Permission - More docblocks

diff --git a/CRM/Core/Permission.php b/CRM/Core/Permission.php
index 0ae7e331637d5a57a840d02e09936adf539ca387..a9d085594ef8d728f74c3135a5dd6666469f2da3 100644 (file)
--- a/CRM/Core/Permission.php
+++ b/CRM/Core/Permission.php
@@ -53,10 +53,19 @@ class CRM_Core_Permission {
   const AUTH_SRC_UNKNOWN = 0, AUTH_SRC_CHECKSUM = 1, AUTH_SRC_SITEKEY = 2, AUTH_SRC_LOGIN = 4;
 
   /**
-   * Get the current permission of this user.
+   * Get the maximum permission of the current user with respect to _any_ contact records.
    *
-   * @return string
-   *   the permission of the user (edit or view or null)
+   * Note: This appears to be hydrated via `CRM_Core_Permission*::group()`, which appears to run in
+   * many page-views, but I'm not certain that it's guaranteed.
+   *
+   * @return int|string|null
+   *   Highest permission held by the current user.
+   *   If the user has "edit" rights to at least 1 contact (via permission or ACL),
+   *     then CRM_Core_Permission::EDIT.
+   *   If the user has "view" rights to at least 1 contact (via permission or ACL),
+   *     then CRM_Core_Permission::VIEW.
+   *   Otherwise, NULL.
+   * @see \CRM_Core_Permission_Base::group()
    */
   public static function getPermission() {
     $config = CRM_Core_Config::singleton();

diff --git a/CRM/Core/Permission/Base.php b/CRM/Core/Permission/Base.php
index c0ac7fcf7447625b50042a1e8a511a5a5a5ca7b9..9b1ae5709bbcfa3486bfe22485ba5a401efe33ef 100644 (file)
--- a/CRM/Core/Permission/Base.php
+++ b/CRM/Core/Permission/Base.php
@@ -75,10 +75,10 @@ class CRM_Core_Permission_Base {
   }
 
   /**
-   * Get the current permission of this user.
+   * Get the maximum permission of the current user with respect to _any_ contact records.
    *
-   * @return string
-   *   the permission of the user (edit or view or null)
+   * @return int|string|null
+   * @see \CRM_Core_Permission::getPermission()
    */
   public function getPermission() {
     $this->group();