From 932303e61779379b47b5eede7232c507b65e529d Mon Sep 17 00:00:00 2001
From: Coleman Watts <coleman@civicrm.org>
Date: Thu, 30 Sep 2021 15:08:50 -0400
Subject: [PATCH] NFC - Update code comments

First docblock to use the new array shapes annotation
---
 Civi/Api4/Generic/Traits/DAOActionTrait.php | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Civi/Api4/Generic/Traits/DAOActionTrait.php b/Civi/Api4/Generic/Traits/DAOActionTrait.php
index 7e0b356ac2..c032e762f5 100644
--- a/Civi/Api4/Generic/Traits/DAOActionTrait.php
+++ b/Civi/Api4/Generic/Traits/DAOActionTrait.php
@@ -195,6 +195,9 @@ trait DAOActionTrait {
   }
 
   /**
+   * Converts params from flat array e.g. ['GroupName.Fieldname' => value] to the
+   * hierarchy expected by the BAO, nested within $params['custom'].
+   *
    * @param array $params
    * @param int $entityId
    *
@@ -204,8 +207,6 @@ trait DAOActionTrait {
   protected function formatCustomParams(&$params, $entityId) {
     $customParams = [];
 
-    // $customValueID is the ID of the custom value in the custom table for this
-    // entity (i guess this assumes it's not a multi value entity)
     foreach ($params as $name => $value) {
       $field = $this->getCustomFieldInfo($name);
       if (!$field) {
@@ -259,7 +260,7 @@ trait DAOActionTrait {
    *
    * @param string $fieldExpr
    *   Field identifier with possible suffix, e.g. MyCustomGroup.MyField1:label
-   * @return array|NULL
+   * @return array{id: int, name: string, entity: string, suffix: string, html_type: string, data_type: string}|NULL
    */
   protected function getCustomFieldInfo(string $fieldExpr) {
     if (strpos($fieldExpr, '.') === FALSE) {
-- 
2.25.1