From 6cb4888bc1dfedb1f8adb40ca3e5591fe8baffae Mon Sep 17 00:00:00 2001
From: Coleman Watts <coleman@civicrm.org>
Date: Sat, 22 Jan 2022 11:54:04 -0500
Subject: [PATCH] [REF] SearchKit docblock cleanup

---
 ext/search_kit/Civi/Search/Admin.php | 52 ++++++++++++++++++++--------
 1 file changed, 38 insertions(+), 14 deletions(-)

diff --git a/ext/search_kit/Civi/Search/Admin.php b/ext/search_kit/Civi/Search/Admin.php
index 97023d9d79..f811dd772f 100644
--- a/ext/search_kit/Civi/Search/Admin.php
+++ b/ext/search_kit/Civi/Search/Admin.php
@@ -25,6 +25,8 @@ use CRM_Search_ExtensionUtil as E;
 class Admin {
 
   /**
+   * Returns clientside data needed for the `crmSearchAdmin` Angular module.
+   *
    * @return array
    */
   public static function getAdminSettings():array {
@@ -66,6 +68,10 @@ class Admin {
   }
 
   /**
+   * Returns operators supported by SearchKit with translated labels.
+   *
+   * This is a subset of APIv4 operators; some redundant ones are omitted for clarity.
+   *
    * @return string[]
    */
   public static function getOperators():array {
@@ -91,6 +97,8 @@ class Admin {
   }
 
   /**
+   * Returns list of css style names (based on Bootstrap3).
+   *
    * @return string[]
    */
   public static function getStyles():array {
@@ -106,10 +114,11 @@ class Admin {
   }
 
   /**
-   * Fetch all entities the current user has permission to `get`
-   * @return array
+   * Fetch all entities the current user has permission to `get`.
+   *
+   * @return array[]
    */
-  public static function getSchema() {
+  public static function getSchema(): array {
     $schema = [];
     $entities = \Civi\Api4\Entity::get()
       ->addSelect('name', 'title', 'title_plural', 'bridge_title', 'type', 'primary_key', 'description', 'label_field', 'icon', 'dao', 'bridge', 'ui_join_filters', 'searchable', 'order_by')
@@ -154,12 +163,14 @@ class Admin {
   }
 
   /**
-   * Add in FK fields for implicit joins
-   * For example, add a `campaign_id.title` field to the Contribution entity
-   * @param $schema
+   * Add in FK fields for implicit joins.
+   *
+   * For example, add a `campaign_id.title` field to the Contribution entity.
+   *
+   * @param array $schema
    * @return array
    */
-  private static function addImplicitFKFields($schema) {
+  private static function addImplicitFKFields(array $schema):array {
     foreach ($schema as &$entity) {
       if ($entity['searchable'] !== 'bridge') {
         foreach (array_reverse($entity['fields'], TRUE) as $index => $field) {
@@ -186,10 +197,12 @@ class Admin {
   }
 
   /**
+   * Find all the ways each entity can be joined.
+   *
    * @param array $allowedEntities
    * @return array
    */
-  public static function getJoins(array $allowedEntities) {
+  public static function getJoins(array $allowedEntities):array {
     $joins = [];
     foreach ($allowedEntities as $entity) {
       // Multi-record custom field groups (to-date only the contact entity supports these)
@@ -330,6 +343,8 @@ class Admin {
   }
 
   /**
+   * Find the reference for a given fieldName.
+   *
    * @param string $fieldName
    * @param \CRM_Core_Reference_Basic[] $references
    * @return \CRM_Core_Reference_Basic
@@ -343,15 +358,15 @@ class Admin {
   }
 
   /**
-   * Boilerplate join clause
+   * Fill in boilerplate join clause with supplied values.
    *
    * @param string $nearCol
    * @param string $farCol
-   * @param string $targetTable
+   * @param string|null $targetTable
    * @param string|null $dynamicCol
    * @return array[]
    */
-  private static function getJoinConditions($nearCol, $farCol, $targetTable = NULL, $dynamicCol = NULL) {
+  private static function getJoinConditions(string $nearCol, string $farCol, string $targetTable = NULL, string $dynamicCol = NULL):array {
     $conditions = [
       [
         $nearCol,
@@ -370,11 +385,13 @@ class Admin {
   }
 
   /**
-   * @param $alias
+   * Calculate default conditions for a join.
+   *
+   * @param string $alias
    * @param array ...$entities
    * @return array
    */
-  private static function getJoinDefaults($alias, ...$entities):array {
+  private static function getJoinDefaults(string $alias, ...$entities):array {
     $conditions = [];
     foreach ($entities as $entity) {
       foreach ($entity['ui_join_filters'] ?? [] as $fieldName) {
@@ -401,7 +418,14 @@ class Admin {
     return $conditions;
   }
 
-  private static function getSqlFunctions() {
+  /**
+   * Get all sql functions that can be used in SearchKit.
+   *
+   * Includes the generic "Arithmetic" pseudo-function.
+   *
+   * @return array
+   */
+  private static function getSqlFunctions():array {
     $functions = \CRM_Api4_Page_Api4Explorer::getSqlFunctions();
     // Add faux function "e" for SqlEquations
     $functions[] = [
-- 
2.25.1