From 5b27235ad17850a268f77ebe10e0a191ac6bce7c Mon Sep 17 00:00:00 2001
From: Seamus Lee <seamuslee001@gmail.com>
Date: Fri, 25 Oct 2019 11:38:43 +1100
Subject: [PATCH] [NFC] dev/core#1336 Update doc blocks for various ACL related
 functions

---
 CRM/ACL/BAO/Cache.php                  | 17 ++++++++++++-----
 CRM/Contact/BAO/Contact/Permission.php |  8 ++++----
 2 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/CRM/ACL/BAO/Cache.php b/CRM/ACL/BAO/Cache.php
index c165e940c0..5ea2c6e069 100644
--- a/CRM/ACL/BAO/Cache.php
+++ b/CRM/ACL/BAO/Cache.php
@@ -39,7 +39,8 @@ class CRM_ACL_BAO_Cache extends CRM_ACL_DAO_ACLCache {
   public static $_cache = NULL;
 
   /**
-   * @param int $id
+   * Build an array of ACLs for a specific ACLed user
+   * @param int $id - contact_id of the ACLed user
    *
    * @return mixed
    */
@@ -91,8 +92,10 @@ SELECT acl_id
   }
 
   /**
-   * @param int $id
-   * @param array $cache
+   * Store ACLs for a specific user in the `civicrm_acl_cache` table
+   * @param int $id - contact_id of the ACLed user
+   * @param array $cache - key civicrm_acl.id - values is the details of the ACL.
+   *
    */
   public static function store($id, &$cache) {
     foreach ($cache as $aclID => $data) {
@@ -109,7 +112,9 @@ SELECT acl_id
   }
 
   /**
-   * @param int $id
+   * Remove entries from civicrm_acl_cache for a specified ACLed user
+   * @param int $id - contact_id of the ACLed user
+   *
    */
   public static function deleteEntry($id) {
     if (self::$_cache &&
@@ -127,7 +132,9 @@ WHERE contact_id = %1
   }
 
   /**
-   * @param int $id
+   * Update ACL caches `civicrm_acl_cache` and `civicrm_acl_contact_cache for the specified ACLed user
+   * @param int $id - contact_id of ACLed user to update caches for.
+   *
    */
   public static function updateEntry($id) {
     // rebuilds civicrm_acl_cache
diff --git a/CRM/Contact/BAO/Contact/Permission.php b/CRM/Contact/BAO/Contact/Permission.php
index 80cbe37847..606d2d76cd 100644
--- a/CRM/Contact/BAO/Contact/Permission.php
+++ b/CRM/Contact/BAO/Contact/Permission.php
@@ -187,12 +187,12 @@ WHERE contact_a.id = %1 AND $permission
   }
 
   /**
-   * Fill the acl contact cache for this contact id if empty.
+   * Fill the acl contact cache for this ACLed contact id if empty.
    *
-   * @param int $userID
+   * @param int $userID - contact_id of the ACLed user
    * @param int|string $type the type of operation (view|edit)
-   * @param bool $force
-   *   Should we force a recompute.
+   * @param bool $force - Should we force a recompute.
+   *
    */
   public static function cache($userID, $type = CRM_Core_Permission::VIEW, $force = FALSE) {
     // FIXME: maybe find a better way of keeping track of this. @eileen pointed out
-- 
2.25.1