From 2884d9564feb3d59d4f4f582aa75d3d4668faf61 Mon Sep 17 00:00:00 2001
From: Bradley Taylor <hello@brad-taylor.co.uk>
Date: Tue, 1 Feb 2022 19:36:08 +0000
Subject: [PATCH] Ensure all api3 functions have documented types

---
 api/class.api.php          | 14 +++++++-------
 api/v3/Case.php            |  8 ++++----
 api/v3/Contribution.php    |  4 ++--
 api/v3/Extension.php       | 12 ++++++------
 api/v3/Generic.php         |  4 ++--
 api/v3/Generic/Getlist.php |  6 +++---
 api/v3/Job.php             |  2 +-
 api/v3/MailingContact.php  | 30 +++++++++++++++---------------
 api/v3/Membership.php      |  4 ++--
 api/v3/Pledge.php          |  2 +-
 api/v3/Profile.php         |  6 +++---
 api/v3/utils.php           | 36 ++++++++++++++++++------------------
 12 files changed, 64 insertions(+), 64 deletions(-)

diff --git a/api/class.api.php b/api/class.api.php
index 77c1e986c8..21a4190b70 100644
--- a/api/class.api.php
+++ b/api/class.api.php
@@ -153,8 +153,8 @@ class civicrm_api3 {
   /**
    * Perform action.
    *
-   * @param $action
-   * @param $params
+   * @param string $action
+   * @param array $params
    *
    * @return bool
    */
@@ -171,8 +171,8 @@ class civicrm_api3 {
   /**
    * Call via rest.
    *
-   * @param $entity
-   * @param $action
+   * @param string $entity
+   * @param string $action
    * @param array $params
    *
    * @return \stdClass
@@ -228,7 +228,7 @@ class civicrm_api3 {
   /**
    * Call api function.
    *
-   * @param $entity
+   * @param string $entity
    * @param string $action
    * @param array $params
    *
@@ -298,8 +298,8 @@ class civicrm_api3 {
   /**
    * Get attribute.
    *
-   * @param $name
-   * @param null $value
+   * @param string $name
+   * @param mixed $value
    *
    * @return $this
    */
diff --git a/api/v3/Case.php b/api/v3/Case.php
index 5249010c45..21082e6330 100644
--- a/api/v3/Case.php
+++ b/api/v3/Case.php
@@ -131,8 +131,8 @@ function civicrm_api3_case_create($params) {
  * When creating a new case, run the xmlProcessor to get all necessary params/configuration
  *  for the new case, as cases use an xml file to store their configuration.
  *
- * @param $params
- * @param $caseBAO
+ * @param array $params
+ * @param CRM_Case_DAO_Case $caseBAO
  *
  * @throws \Exception
  */
@@ -762,8 +762,8 @@ function civicrm_api3_case_getList($params) {
 
 /**
  * Needed due to the above override
- * @param $params
- * @param $apiRequest
+ * @param array $params
+ * @param array $apiRequest
  */
 function _civicrm_api3_case_getlist_spec(&$params, $apiRequest) {
   require_once 'api/v3/Generic/Getlist.php';
diff --git a/api/v3/Contribution.php b/api/v3/Contribution.php
index e3d49c086c..6396535fb3 100644
--- a/api/v3/Contribution.php
+++ b/api/v3/Contribution.php
@@ -290,7 +290,7 @@ function _civicrm_api3_contribution_get_support_nonunique_returns($params) {
 /**
  * Support for supported output variables.
  *
- * @param $contribution
+ * @param array $contribution
  */
 function _civicrm_api3_contribution_add_supported_fields(&$contribution) {
   // These are output fields that are supported in our test contract.
@@ -329,7 +329,7 @@ function civicrm_api3_contribution_getcount($params) {
  * As of v4.4 we support multiple soft credit, so now contribution returns array with 'soft_credit' as key
  * but we still return first soft credit as a part of contribution array
  *
- * @param $contribution
+ * @param array $contribution
  */
 function _civicrm_api3_format_soft_credit(&$contribution) {
   if (!empty($contribution['soft_credit'])) {
diff --git a/api/v3/Extension.php b/api/v3/Extension.php
index ce46a5dfb4..0b654bf642 100644
--- a/api/v3/Extension.php
+++ b/api/v3/Extension.php
@@ -50,7 +50,7 @@ function civicrm_api3_extension_install($params) {
 
 /**
  * Spec function for getfields
- * @param $fields
+ * @param array $fields
  */
 function _civicrm_api3_extension_install_spec(&$fields) {
   $fields['keys'] = [
@@ -122,7 +122,7 @@ function civicrm_api3_extension_enable($params) {
 
 /**
  * Spec function for getfields
- * @param $fields
+ * @param array $fields
  */
 function _civicrm_api3_extension_enable_spec(&$fields) {
   _civicrm_api3_extension_install_spec($fields);
@@ -153,7 +153,7 @@ function civicrm_api3_extension_disable($params) {
 
 /**
  * Spec function for getfields
- * @param $fields
+ * @param array $fields
  */
 function _civicrm_api3_extension_disable_spec(&$fields) {
   _civicrm_api3_extension_install_spec($fields);
@@ -186,7 +186,7 @@ function civicrm_api3_extension_uninstall($params) {
 
 /**
  * Spec function for getfields
- * @param $fields
+ * @param array $fields
  */
 function _civicrm_api3_extension_uninstall_spec(&$fields) {
   _civicrm_api3_extension_install_spec($fields);
@@ -250,7 +250,7 @@ function civicrm_api3_extension_download($params) {
 
 /**
  * Spec function for getfields
- * @param $fields
+ * @param array $fields
  */
 function _civicrm_api3_extension_download_spec(&$fields) {
   $fields['key'] = [
@@ -305,7 +305,7 @@ function civicrm_api3_extension_refresh($params) {
 
 /**
  * Spec function for getfields
- * @param $fields
+ * @param array $fields
  */
 function _civicrm_api3_extension_refresh_spec(&$fields) {
   $fields['local'] = [
diff --git a/api/v3/Generic.php b/api/v3/Generic.php
index 34ba7db2a1..9188bcff50 100644
--- a/api/v3/Generic.php
+++ b/api/v3/Generic.php
@@ -454,8 +454,8 @@ function civicrm_api3_generic_getoptions($apiRequest) {
 /**
  * Provide metadata for this generic action
  *
- * @param $params
- * @param $apiRequest
+ * @param array $params
+ * @param array $apiRequest
  */
 function _civicrm_api3_generic_getoptions_spec(&$params, $apiRequest) {
   $params += [
diff --git a/api/v3/Generic/Getlist.php b/api/v3/Generic/Getlist.php
index 3d993c70b5..af8fb61c3b 100644
--- a/api/v3/Generic/Getlist.php
+++ b/api/v3/Generic/Getlist.php
@@ -246,9 +246,9 @@ function _civicrm_api3_generic_getlist_output($result, $request, $entity, $field
 /**
  * Common postprocess for getlist output
  *
- * @param $result
- * @param $request
- * @param $values
+ * @param array $result
+ * @param array $request
+ * @param array $values
  */
 function _civicrm_api3_generic_getlist_postprocess($result, $request, &$values) {
   $chains = [];
diff --git a/api/v3/Job.php b/api/v3/Job.php
index dd9a9ca1e7..4210e43a69 100644
--- a/api/v3/Job.php
+++ b/api/v3/Job.php
@@ -555,7 +555,7 @@ function civicrm_api3_job_process_batch_merge($params) {
 /**
  * Metadata for batch merge function.
  *
- * @param $params
+ * @param array $params
  */
 function _civicrm_api3_job_process_batch_merge_spec(&$params) {
   $params['rule_group_id'] = [
diff --git a/api/v3/MailingContact.php b/api/v3/MailingContact.php
index 4875e79340..2ef5194da7 100644
--- a/api/v3/MailingContact.php
+++ b/api/v3/MailingContact.php
@@ -84,13 +84,13 @@ function _civicrm_api3_mailing_contact_get_spec(&$params) {
  * Helper function for mailing contact queries.
  *
  * @param int $contactID
- * @param $offset
- * @param $limit
- * @param $selectFields
- * @param $fromClause
- * @param $whereClause
- * @param $sort
- * @param $getCount
+ * @param int $offset
+ * @param int $limit
+ * @param array|null $selectFields
+ * @param string|null $fromClause
+ * @param string|null $whereClause
+ * @param string|null $sort
+ * @param bool $getCount
  *
  * @return array
  */
@@ -196,10 +196,10 @@ LIMIT %2, %3
  * Get delivered mailing contacts.
  *
  * @param int $contactID
- * @param $offset
- * @param $limit
- * @param $sort
- * @param $getCount
+ * @param int $offset
+ * @param int $limit
+ * @param string|null $sort
+ * @param bool $getCount
  *
  * @return array
  */
@@ -237,10 +237,10 @@ AND        meb.id IS NULL
  * Get bounced mailing contact records.
  *
  * @param int $contactID
- * @param $offset
- * @param $limit
- * @param $sort
- * @param $getCount
+ * @param int $offset
+ * @param int $limit
+ * @param string|null $sort
+ * @param bool $getCount
  *
  * @return array
  */
diff --git a/api/v3/Membership.php b/api/v3/Membership.php
index c7a3b1d5e4..689f880ec4 100644
--- a/api/v3/Membership.php
+++ b/api/v3/Membership.php
@@ -250,7 +250,7 @@ function civicrm_api3_membership_get($params) {
  * @param array $params
  *   Parameters passed into get function.
  * @param int $membershipTypeId
- * @param $activeOnly
+ * @param bool $activeOnly
  *
  * @return array
  *   result for calling function
@@ -271,7 +271,7 @@ function _civicrm_api3_membership_get_customv2behaviour(&$params, $membershipTyp
  *
  * @param array $params
  *   Parameters passed into get function.
- * @param $membershipValues
+ * @param array $membershipValues
  * @param int $contactID
  *
  * @return array
diff --git a/api/v3/Pledge.php b/api/v3/Pledge.php
index 25f661502e..571924b193 100644
--- a/api/v3/Pledge.php
+++ b/api/v3/Pledge.php
@@ -18,7 +18,7 @@
 /**
  * Create or updates an Pledge.
  *
- * @param $params
+ * @param array $params
  *
  * @return array
  *   Array containing 'is_error' to denote success or failure and details of the created pledge
diff --git a/api/v3/Profile.php b/api/v3/Profile.php
index 742af495fa..a20bd48e1e 100644
--- a/api/v3/Profile.php
+++ b/api/v3/Profile.php
@@ -485,7 +485,7 @@ function _civicrm_api3_profile_getbillingpseudoprofile(&$params) {
  * @param int $profileID
  * @param int $optionsBehaviour
  *   0 = don't resolve, 1 = resolve non-aggressively, 2 = resolve aggressively - ie include country & state.
- * @param $is_flush
+ * @param bool $is_flush
  *
  * @return array|void
  */
@@ -623,7 +623,7 @@ function _civicrm_api3_order_by_weight($a, $b) {
  * Here we map the profile fields as stored in the uf_field table to their 'real entity'
  * we also return the profile fieldname
  *
- * @param $field
+ * @param array $field
  *
  * @return array
  */
@@ -716,7 +716,7 @@ function _civicrm_api3_profile_getProfileID($profileID) {
  *
  * e.g getfields response incl 'membership_type_id' - with api.aliases = 'membership_type'
  * returned array will include both as keys (with the same values)
- * @param $entity
+ * @param string $entity
  *
  * @return array
  */
diff --git a/api/v3/utils.php b/api/v3/utils.php
index 03a25ae1ec..1bbc77ef45 100644
--- a/api/v3/utils.php
+++ b/api/v3/utils.php
@@ -273,7 +273,7 @@ function civicrm_api3_create_success($values = 1, $params = [], $entity = NULL,
 /**
  * Load the DAO of the entity.
  *
- * @param $entity
+ * @param string $entity
  *
  * @return bool
  */
@@ -405,7 +405,7 @@ function _civicrm_api3_get_BAO($name) {
 /**
  * Recursive function to explode value-separated strings into arrays.
  *
- * @param $values
+ * @param array $values
  */
 function _civicrm_api3_separate_values(&$values) {
   $sp = CRM_Core_DAO::VALUE_SEPARATOR;
@@ -498,7 +498,7 @@ function _civicrm_api3_field_names($fields) {
  * Ideally this would be merged with _civicrm_get_query_object but we need to resolve differences in what the
  * 2 variants call
  *
- * @param $entity
+ * @param string $entity
  * @param array $params
  *   As passed into api get or getcount function.
  * @param array $additional_options
@@ -898,7 +898,7 @@ function _civicrm_api3_get_options_from_params($params, $queryObject = FALSE, $e
  *   Params array as passed into civicrm_api.
  * @param object $dao
  *   DAO object.
- * @param $entity
+ * @param string $entity
  *
  * @throws \API_Exception
  * @throws \CRM_Core_Exception
@@ -1068,8 +1068,8 @@ function _civicrm_api3_object_to_array(&$dao, &$values, $uniqueFields = FALSE) {
 /**
  * Wrapper for _civicrm_object_to_array when api supports unique fields.
  *
- * @param $dao
- * @param $values
+ * @param CRM_Core_DAO $dao
+ * @param array $values
  *
  * @return array
  */
@@ -1125,7 +1125,7 @@ function _civicrm_api3_custom_format_params($params, &$values, $extends, $entity
  * Format parameters for create action.
  *
  * @param array $params
- * @param $entity
+ * @param string $entity
  */
 function _civicrm_api3_format_params_for_create(&$params, $entity) {
   $nonGenericEntities = array_merge(['Contact'], CRM_Contact_BAO_ContactType::basicTypes(TRUE));
@@ -1401,7 +1401,7 @@ function _civicrm_api3_basic_delete($bao_name, &$params) {
  *
  * @param array $returnArray
  *   Array to append custom data too - generally $result[4] where 4 is the entity id.
- * @param $checkPermission
+ * @param bool $checkPermission
  * @param string $entity
  *   E.g membership, event.
  * @param int $entity_id
@@ -1505,7 +1505,7 @@ function _civicrm_api3_validate($entity, $action, $params) {
 
 /**
  * Used by the Validate API.
- * @param $fieldName
+ * @param string $fieldName
  * @param array $fieldInfo
  * @param string $entity
  * @param array $params
@@ -1705,7 +1705,7 @@ function _civicrm_api3_validate_date(&$params, &$fieldName, &$fieldInfo) {
  *
  * @param string $dateValue
  * @param string $fieldName
- * @param $fieldType
+ * @param int $fieldType
  *
  * @throws Exception
  * @return mixed
@@ -1876,7 +1876,7 @@ function _civicrm_api3_generic_replace_base_params($params) {
 /**
  * Returns fields allowable by api.
  *
- * @param $entity
+ * @param string $entity
  *   String Entity to query.
  * @param bool $unique
  *   Index by unique fields?.
@@ -1952,7 +1952,7 @@ function _civicrm_api_get_fields($entity, $unique = FALSE, &$params = []) {
  *
  * This is the same as the BAO function but fields are prefixed with 'custom_' to represent api params.
  *
- * @param $entity
+ * @param string $entity
  * @param array $params
  *
  * @return array
@@ -1996,8 +1996,8 @@ function _civicrm_api_get_custom_fields($entity, &$params) {
  *
  * Function also swaps unique fields for non-unique fields & vice versa.
  *
- * @param $apiRequest
- * @param $fields
+ * @param array $apiRequest
+ * @param array $fields
  */
 function _civicrm_api3_swap_out_aliases(&$apiRequest, $fields) {
   foreach ($fields as $field => $values) {
@@ -2118,7 +2118,7 @@ function _civicrm_api3_validate_integer(&$params, $fieldName, &$fieldInfo, $enti
 
 /**
  * Helper function to determine country_id given the myriad of values for country_id or country that are supported
- * @param $params
+ * @param array $params
  *
  * @return int|null
  */
@@ -2394,9 +2394,9 @@ function _civicrm_api3_api_match_pseudoconstant_value(&$value, $options, $fieldN
 /**
  * Returns the canonical name of a field.
  *
- * @param $entity
+ * @param string $entity
  *   api entity name (string should already be standardized - no camelCase).
- * @param $fieldName
+ * @param string $fieldName
  *   any variation of a field's name (name, unique_name, api.alias).
  *
  * @param string $action
@@ -2489,7 +2489,7 @@ function _civicrm_api3_field_value_check(&$params, $fieldName, $type = NULL) {
  * _civicrm_api3_basic_get but does not use DAO/BAO. This is useful for
  * small/mid-size data loaded from external JSON or XML documents.
  *
- * @param $entity
+ * @param string $entity
  * @param array $params
  *   API parameters.
  * @param array $records
-- 
2.25.1