From 75840aec1bb00b057936df7ad211824001cd5ad2 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Thu, 21 Jul 2022 23:51:29 -0700
Subject: [PATCH] (NFC) CRM_Core_Permission - More docblocks

---
 CRM/Core/Permission.php      | 15 ++++++++++++---
 CRM/Core/Permission/Base.php |  6 +++---
 2 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/CRM/Core/Permission.php b/CRM/Core/Permission.php
index 0ae7e331637d..a9d085594ef8 100644
--- 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 c0ac7fcf7447..9b1ae5709bbc 100644
--- a/CRM/Core/Permission/Base.php
+++ b/CRM/Core/Permission/Base.php
@@ -75,10 +75,10 @@ public function translatePermission($perm, $nativePrefix, $map) {
   }
 
   /**
-   * 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();