From: Eileen McNaughton <eileen@fuzion.co.nz>
Date: Mon, 2 Feb 2015 05:22:07 +0000 (+1300)
Subject: some more comment fixes
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=61fe4988936f8bb28644451af665a141d6eb4c7b;p=civicrm-core.git

some more comment fixes
---

diff --git a/api/Exception.php b/api/Exception.php
index 8629359f21..406997be46 100644
--- a/api/Exception.php
+++ b/api/Exception.php
@@ -1,5 +1,6 @@
 <?php
 /**
+ * @file
  * File for the CiviCRM APIv3 API wrapper
  *
  * @package CiviCRM_APIv3
diff --git a/api/api.php b/api/api.php
index 9425c81057..3003f567c4 100644
--- a/api/api.php
+++ b/api/api.php
@@ -1,7 +1,8 @@
 <?php
 
 /**
- * File for the CiviCRM APIv3 API wrapper
+ * @file
+ * File for the CiviCRM APIv3 API wrapper.
  *
  * @package CiviCRM_APIv3
  * @subpackage API
diff --git a/api/v3/ActionSchedule.php b/api/v3/ActionSchedule.php
index e37f973213..5e7094b845 100644
--- a/api/v3/ActionSchedule.php
+++ b/api/v3/ActionSchedule.php
@@ -32,13 +32,13 @@
  * @subpackage API_ActionSchedule
  *
  * @copyright CiviCRM LLC (c) 2004-2014
- *
  */
 
 /**
- * Get CiviCRM Action Schedule details
- * {@getfields action_schedule_create}
+ * Get CiviCRM Action Schedule details.
+ *
  * @param array $params
+ *
  * @return array
  */
 function civicrm_api3_action_schedule_get($params) {
diff --git a/api/v3/Activity.php b/api/v3/Activity.php
index 2d006ce781..d140f2d94a 100644
--- a/api/v3/Activity.php
+++ b/api/v3/Activity.php
@@ -34,25 +34,18 @@
  * @subpackage API_Activity
  * @copyright CiviCRM LLC (c) 2004-2014
  * @version $Id: Activity.php 30486 2010-11-02 16:12:09Z shot $
- *
  */
 
 
 /**
- * Creates or updates an Activity. See the example for usage
+ * Creates or updates an Activity.
  *
  * @param array $params
- *   Associative array of property name/value.
- *                             pairs for the activity.
- * {@getfields activity_create}
+ *  Array per getfields documentation.
  *
  * @throws API_Exception
  * @return array
- *   Array containing 'is_error' to denote success or failure and details of the created activity
- *
- * @example ActivityCreate.php Standard create example
- * @example Activity/ContactRefCustomField.php Create example including setting a contact reference custom field
- * {@example ActivityCreate.php 0}
+ *   Array containing 'is_error' to denote success or failure and details of the created activity.
  */
 function civicrm_api3_activity_create($params) {
 
@@ -182,14 +175,17 @@ function civicrm_api3_activity_create($params) {
 }
 
 /**
- * Specify Meta data for create. Note that this data is retrievable via the getfields function
- * and is used for pre-filling defaults and ensuring mandatory requirements are met.
+ * Specify Meta data for create.
+ *
+ * Note that this data is retrievable via the getfields function and is used for pre-filling defaults and
+ * ensuring mandatory requirements are met.
+ *
  * @param array $params
- *   (reference) array of parameters determined by getfields.
+ *  Array of parameters determined by getfields.
  */
 function _civicrm_api3_activity_create_spec(&$params) {
 
-  //default for source_contact_id = currently logged in user
+  // Default for source_contact_id = currently logged in user.
   $params['source_contact_id']['api.default'] = 'user_contact_id';
 
   $params['status_id']['api.aliases'] = array('activity_status');
@@ -218,23 +214,18 @@ function _civicrm_api3_activity_create_spec(&$params) {
 }
 
 /**
- * Gets a CiviCRM activity according to parameters
+ * Gets a CiviCRM activity according to parameters.
  *
  * @param array $params
- *   Associative array of property name/value.
- *                             pairs for the activity.
+ *   Array per getfields documentation.
  *
  * @return array
- *
- *   {@getfields activity_get}
- * @example ActivityGet.php Basic example
- * @example Activity/DateTimeHigh.php Example get with date filtering
- * {@example ActivityGet.php 0}
  */
 function civicrm_api3_activity_get($params) {
   if (!empty($params['contact_id'])) {
     $activities = CRM_Activity_BAO_Activity::getContactActivity($params['contact_id']);
-    //BAO function doesn't actually return a contact ID - hack api for now & add to test so when api re-write happens it won't get missed
+    // BAO function doesn't actually return a contact ID - hack api for now & add to test so when api re-write
+    // happens it won't get missed.
     foreach ($activities as $key => $activityArray) {
       $activities[$key]['id'] = $key;
     }
@@ -253,13 +244,14 @@ function civicrm_api3_activity_get($params) {
 }
 
 /**
- * Given a list of activities, append any extra data requested about the activities
+ * Given a list of activities, append any extra data requested about the activities.
  *
  * NOTE: Called by civicrm-core and CiviHR
  *
  * @param array $params
  *   API request parameters.
  * @param array $activities
+ *
  * @return array
  *   new activities list
  */
@@ -319,16 +311,10 @@ function _civicrm_api3_activity_get_formatResult($params, $activities) {
  *
  * @param array $params
  *   Array holding 'id' of activity to be deleted.
- * {@getfields activity_delete}
  *
  * @throws API_Exception
- * @return void|CRM_Core_Error  An error if 'activityName or ID' is invalid,
- *                         permissions are insufficient, etc. or CiviCRM success array
- *
- *
- *
- * @example ActivityDelete.php Standard Delete Example
  *
+ * @return array
  */
 function civicrm_api3_activity_delete($params) {
 
@@ -341,7 +327,7 @@ function civicrm_api3_activity_delete($params) {
 }
 
 /**
- * Check for required params
+ * Check for required params.
  *
  * @param array $params
  *   Associated array of fields.
@@ -385,7 +371,7 @@ SELECT  count(*)
   FROM  civicrm_contact
  WHERE  id IN (' . implode(', ', $contactIds) . ' )';
     if (count($contactIds) != CRM_Core_DAO::singleValueQuery($sql)) {
-      throw new API_Exception('Invalid ' . ' Contact Id');
+      throw new API_Exception('Invalid Contact Id');
     }
   }
 
@@ -451,6 +437,8 @@ SELECT  count(*)
 }
 
 /**
+ * Get parameters for activity list.
+ *
  * @see _civicrm_api3_generic_getlist_params
  *
  * @param array $request
@@ -472,6 +460,8 @@ function _civicrm_api3_activity_getlist_params(&$request) {
 }
 
 /**
+ * Get output for activity list.
+ *
  * @see _civicrm_api3_generic_getlist_output
  *
  * @param array $result
diff --git a/api/v3/Batch.php b/api/v3/Batch.php
index dee694cd52..1d527b70b7 100644
--- a/api/v3/Batch.php
+++ b/api/v3/Batch.php
@@ -30,15 +30,10 @@
  *
  * @package CiviCRM_APIv3
  * @subpackage API_Batch
- *
  */
 
 /**
- * Save a Batch
- *
- * Allowed @params array keys are:
- * {@getfields batch_create}
- * @example BatchCreate.php
+ * Save a Batch.
  *
  * @param array $params
  *
diff --git a/api/v3/Case.php b/api/v3/Case.php
index 308b98d950..5454994394 100644
--- a/api/v3/Case.php
+++ b/api/v3/Case.php
@@ -434,7 +434,7 @@ function _civicrm_api3_case_read($caseId, $options) {
 }
 
 /**
- * Internal function to format create params for processing
+ * Internal function to format create params for processing.
  *
  * @param array $params
  */
@@ -448,7 +448,7 @@ function _civicrm_api3_case_format_params(&$params) {
     if (!$params['case_type_id']) {
       $caseTypeLabels = CRM_Case_PseudoConstant::caseType('title', FALSE);
       $params['case_type_id'] = array_search($params['case_type'], $caseTypeLabels);
-      $params['case_type'] = $caseTypes[$params['case_type_id']]; // label => name
+      $params['case_type'] = $caseTypes[$params['case_type_id']];
     }
   }
   elseif (empty($params['case_type'])) {
diff --git a/api/v3/CaseType.php b/api/v3/CaseType.php
index 3d00eca7af..29d3af56a3 100644
--- a/api/v3/CaseType.php
+++ b/api/v3/CaseType.php
@@ -32,7 +32,6 @@
  * @package CiviCRM_APIv3
  * @subpackage API_Case
  * @copyright CiviCRM LLC (c) 2004-2014
- *
  */
 
 /**
diff --git a/api/v3/Contact.php b/api/v3/Contact.php
index ceb42c52c4..3e33f35e78 100644
--- a/api/v3/Contact.php
+++ b/api/v3/Contact.php
@@ -139,7 +139,9 @@ function _civicrm_api3_contact_create_spec(&$params) {
 }
 
 /**
- * Retrieve one or more contacts, given a set of search params
+ * Retrieve one or more contacts, given a set of search params.
+ *
+ * @param array $params
  *
  * @return array
  *   API Result Array
@@ -152,6 +154,8 @@ function civicrm_api3_contact_get($params) {
 }
 
 /**
+ * Get count of contact.
+ *
  * @param array $params
  *
  * @return int
diff --git a/api/v3/CustomSearch.php b/api/v3/CustomSearch.php
index 3137c49ecf..55197d9c33 100644
--- a/api/v3/CustomSearch.php
+++ b/api/v3/CustomSearch.php
@@ -1,18 +1,14 @@
 <?php
 
 /**
- * Retrieve a CustomSearches
+ * Retrieve custom searches.
  *
  * FIXME This is a bare-minimum placeholder
  *
  * @param array $params
  *
- * {@example OptionValueGet.php 0}
- * @example OptionValueGet.php
- *
  * @return array
  *   details of found Option Values
- *   {@getfields OptionValue_get}
  */
 function civicrm_api3_custom_search_get($params) {
   require_once 'api/v3/OptionValue.php';
diff --git a/api/v3/DashboardContact.php b/api/v3/DashboardContact.php
index 86f39aacc5..f6c60ddabd 100644
--- a/api/v3/DashboardContact.php
+++ b/api/v3/DashboardContact.php
@@ -32,11 +32,10 @@
  * @subpackage API_ActionSchedule
  *
  * @copyright CiviCRM LLC (c) 2004-2014
- *
  */
 
 /**
- * Creates/Updates a new Dashboard Contact Entry
+ * Creates/Updates a new Dashboard Contact Entry.
  *
  * @param array $params
  *
diff --git a/api/v3/Entity.php b/api/v3/Entity.php
index 52ce682a1a..2621d17f45 100644
--- a/api/v3/Entity.php
+++ b/api/v3/Entity.php
@@ -1,8 +1,12 @@
 <?php
 
 /**
+ * Get list of deprecated entities.
+ *
  * @deprecated api notice
+ *
  * @param array $entities
+ *
  * @return array
  *   Array of deprecated api entities
  */
diff --git a/api/v3/File.php b/api/v3/File.php
index f99dd39359..a1a76ad823 100644
--- a/api/v3/File.php
+++ b/api/v3/File.php
@@ -36,11 +36,10 @@
  * @subpackage API_File
  * @copyright CiviCRM LLC (c) 2004-2014
  * $Id: $
- *
  */
 
 /**
- * Create a file
+ * Create a file.
  *
  * This API is used for creating a file
  *
diff --git a/api/v3/Generic.php b/api/v3/Generic.php
index 4de5a5db66..19863eabef 100644
--- a/api/v3/Generic.php
+++ b/api/v3/Generic.php
@@ -1,8 +1,9 @@
 <?php
 
 /**
- * Get information about fields for a given api request. Getfields information
- * is used for documentation, validation, default setting
+ * Get information about fields for a given api request.
+ *
+ * Getfields information is used for documentation, validation, default setting
  * We first query the scheme using the $dao->fields function & then augment
  * that information by calling the _spec functions that apply to the relevant function
  * Note that we use 'unique' field names as described in the xml/schema files
diff --git a/api/v3/Job.php b/api/v3/Job.php
index 93edc01400..b12d4ae515 100644
--- a/api/v3/Job.php
+++ b/api/v3/Job.php
@@ -100,13 +100,12 @@ function civicrm_api3_job_delete($params) {
  *   API Result Array
  */
 function civicrm_api3_job_execute($params) {
-  // @noinspection PhpUnusedParameterInspection
 
   $facility = new CRM_Core_JobManager();
   $facility->execute(FALSE);
 
-  // always creates success - results are handled elsewhere
-  return civicrm_api3_create_success();
+  // Always creates success - results are handled elsewhere.
+  return civicrm_api3_create_success(1, $params);
 }
 
 /**
@@ -400,8 +399,9 @@ function civicrm_api3_job_process_participant($params) {
 
 
 /**
- * This api checks and updates the status of all membership records for a given domain using the calc_membership_status and
- * update_contact_membership APIs.
+ * This api checks and updates the status of all membership records for a given domain.
+ *
+ * The function uses the calc_membership_status and update_contact_membership APIs.
  *
  * IMPORTANT:
  * Sending renewal reminders has been migrated from this job to the Scheduled Reminders function as of 4.3.
@@ -422,7 +422,7 @@ function civicrm_api3_job_process_membership($params) {
   $lock->release();
 
   if ($result['is_error'] == 0) {
-    return civicrm_api3_create_success($result['messages']);
+    return civicrm_api3_create_success($result['messages'], $params);
   }
   else {
     return civicrm_api3_create_error($result['messages']);
@@ -457,7 +457,6 @@ function civicrm_api3_job_process_respondent($params) {
  *
  * @return array
  *   API Result Array
- *
  */
 function civicrm_api3_job_process_batch_merge($params) {
   $rgid = CRM_Utils_Array::value('rgid', $params);
@@ -477,6 +476,8 @@ function civicrm_api3_job_process_batch_merge($params) {
 }
 
 /**
+ * Metadata for batch merge function.
+ *
  * @param $params
  */
 function _civicrm_api3_job_process_batch_merge_spec(&$params) {
@@ -501,14 +502,14 @@ function _civicrm_api3_job_process_batch_merge_spec(&$params) {
 }
 
 /**
- * Runs handlePaymentCron method in the specified payment processor
+ * Runs handlePaymentCron method in the specified payment processor.
  *
  * @param array $params
  *   Input parameters.
  *
- * Expected @params array keys are:
+ * Expected @params array keys are: INCORRECTLY DOCUMENTED AND SHOULD BE IN THE _spec function
+ * for retrieval via getfields.
  * {string  'processor_name' - the name of the payment processor, eg: Sagepay}
- *
  */
 function civicrm_api3_job_run_payment_cron($params) {
 
@@ -536,7 +537,9 @@ function civicrm_api3_job_run_payment_cron($params) {
 }
 
 /**
- * This api cleans up all the old session entries and temp tables. We recommend that sites run this on an hourly basis
+ * This api cleans up all the old session entries and temp tables.
+ *
+ * We recommend that sites run this on an hourly basis.
  *
  * @param array $params
  *   Sends in various config parameters to decide what needs to be cleaned.
@@ -568,26 +571,30 @@ function civicrm_api3_job_cleanup($params) {
 
 /**
  * Set expired relationships to disabled.
- * @param $params
+ *
+ * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */
 function civicrm_api3_job_disable_expired_relationships($params) {
-  /** @noinspection PhpUnusedParameterInspection */
   $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships();
   if (!$result) {
     throw new API_Exception('Failed to disable all expired relationships.');
   }
-  return civicrm_api3_create_success();
+  return civicrm_api3_create_success(1, $params);
 }
 
 /**
- * This api reloads all the smart groups. If the org has a large number of smart groups
- * it is recommended that they use the limit clause to limit the number of smart groups
- * evaluated on a per job basis. Might also help to increase the smartGroupCacheTimeout
- * and use the cache
+ * This api reloads all the smart groups.
+ *
+ * If the org has a large number of smart groups it is recommended that they use the limit clause
+ * to limit the number of smart groups evaluated on a per job basis.
+ *
+ * Might also help to increase the smartGroupCacheTimeout and use the cache.
  *
  * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */
diff --git a/api/v3/Location.php b/api/v3/Location.php
index 40fbdb6263..9f8ee7a661 100644
--- a/api/v3/Location.php
+++ b/api/v3/Location.php
@@ -1,7 +1,8 @@
 <?php
 
 /**
- *  Functions to inform caller that Location is obsolete and Address, Phone, Email, Website should be used
+ * Function to inform caller that Location is obsolete and Address, Phone, Email, Website should be used.
+ *
  * @param array $params
  * @return array
  */
diff --git a/api/v3/MailingComponent.php b/api/v3/MailingComponent.php
index 4e3634c82e..48230f808b 100644
--- a/api/v3/MailingComponent.php
+++ b/api/v3/MailingComponent.php
@@ -30,16 +30,10 @@
  *
  * @package CiviCRM_APIv3
  * @subpackage API_mailing_component
- *
  */
 
 /**
- * Save a mailing_component
- *
- * Allowed @params array keys are:
- * {@getfields mailing_component_create}
- * @example mailing_componentCreate.php
- *
+ * Save a mailing_component.
  * @param array $params
  *
  * @throws API_Exception
diff --git a/api/v3/MessageTemplate.php b/api/v3/MessageTemplate.php
index f676883f47..a030409a19 100644
--- a/api/v3/MessageTemplate.php
+++ b/api/v3/MessageTemplate.php
@@ -32,7 +32,10 @@
  */
 
 /**
+ * Create message template.
+ *
  * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */
diff --git a/api/v3/Note.php b/api/v3/Note.php
index 0b1e379f68..22a9a9adeb 100644
--- a/api/v3/Note.php
+++ b/api/v3/Note.php
@@ -33,11 +33,10 @@
  *
  * @copyright CiviCRM LLC (c) 2004-2014
  * @version $Id: Note.php 30879 2010-11-22 15:45:55Z shot $
- *
  */
 
 /**
- * Create Note
+ * Create Note.
  *
  * This API is used for creating a note.
  * Required parameters : entity_id AND note
diff --git a/api/v3/OptionGroup.php b/api/v3/OptionGroup.php
index a80e7f5bb5..cfe6ed7a35 100644
--- a/api/v3/OptionGroup.php
+++ b/api/v3/OptionGroup.php
@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * Get option groups.
+ *
  * @param array $params
  *
  * @return array
diff --git a/api/v3/PledgePayment.php b/api/v3/PledgePayment.php
index 638da98381..e36cd4840a 100644
--- a/api/v3/PledgePayment.php
+++ b/api/v3/PledgePayment.php
@@ -37,7 +37,7 @@
  */
 
 /**
- * Add or update a plege payment. Pledge Payment API doesn't actually add a pledge
+ * Add or update a pledge payment. Pledge Payment API doesn't actually add a pledge
  *  if the request is to 'create' and 'id' is not passed in
  * the oldest pledge with no associated contribution is updated
  *
diff --git a/api/v3/Setting.php b/api/v3/Setting.php
index d934a9fcfc..1db8a4f84c 100644
--- a/api/v3/Setting.php
+++ b/api/v3/Setting.php
@@ -32,7 +32,13 @@
  * @subpackage API_Settings
  * @copyright CiviCRM LLC (c) 2004-2014
  * @version $Id: Settings.php
+ */
+
+/**
+ * Get fields for setting api calls.
+ *
  * @param array $params
+ *
  * @return array
  */
 function civicrm_api3_setting_getfields($params) {
diff --git a/api/v3/utils.php b/api/v3/utils.php
index 68fd211b8c..08318765ea 100644
--- a/api/v3/utils.php
+++ b/api/v3/utils.php
@@ -33,11 +33,10 @@
  *
  * @copyright CiviCRM LLC (c) 2004-2014
  * @version $Id: utils.php 30879 2010-11-22 15:45:55Z shot $
- *
  */
 
 /**
- * Initialize CiviCRM - should be run at the start of each API function
+ * Initialize CiviCRM - should be run at the start of each API function.
  */
 function _civicrm_api3_initialize() {
   require_once 'CRM/Core/ClassLoader.php';
@@ -46,7 +45,7 @@ function _civicrm_api3_initialize() {
 }
 
 /**
- * Wrapper Function for civicrm_verify_mandatory to make it simple to pass either / or fields for checking
+ * Wrapper Function for civicrm_verify_mandatory to make it simple to pass either / or fields for checking.
  *
  * @param array $params
  *   Array of fields to check.
@@ -64,7 +63,7 @@ function civicrm_api3_verify_one_mandatory($params, $daoName = NULL, $keyoptions
 }
 
 /**
- * check mandatory fields are included
+ * Check mandatory fields are included.
  *
  * @param array $params
  *   Array of fields to check.
@@ -126,9 +125,11 @@ function civicrm_api3_verify_mandatory($params, $daoName = NULL, $keys = array()
 }
 
 /**
+ * Create error array.
  *
- * @param $msg
+ * @param string $msg
  * @param array $data
+ *
  * @return array
  */
 function civicrm_api3_create_error($msg, $data = array()) {
@@ -137,7 +138,8 @@ function civicrm_api3_create_error($msg, $data = array()) {
   // we will show sql to privileged user only (not sure of a specific
   // security hole here but seems sensible - perhaps should apply to the trace as well?)
   if (isset($data['sql']) && CRM_Core_Permission::check('Administer CiviCRM')) {
-    $data['debug_information'] = $data['sql']; // Isn't this redundant?
+    // Isn't this redundant?
+    $data['debug_information'] = $data['sql'];
   }
   else {
     unset($data['sql']);
@@ -261,7 +263,8 @@ function civicrm_api3_create_success($values = 1, $params = array(), $entity = N
 }
 
 /**
- * Load the DAO of the entity
+ * Load the DAO of the entity.
+ *
  * @param $entity
  * @return bool
  */
@@ -275,11 +278,13 @@ function _civicrm_api3_load_DAO($entity) {
 }
 
 /**
- * return the DAO of the function or Entity
+ * Return the DAO of the function or Entity.
+ *
  * @param string $name
  *   Either a function of the api (civicrm_{entity}_create or the entity name.
  *   return the DAO name to manipulate this function
  *   eg. "civicrm_api3_contact_create" or "Contact" will return "CRM_Contact_BAO_Contact"
+ *
  * @return mixed|string
  */
 function _civicrm_api3_get_DAO($name) {
@@ -343,11 +348,13 @@ function _civicrm_api3_get_DAO($name) {
 }
 
 /**
- * return the DAO of the function or Entity
+ * Return the DAO of the function or Entity.
+ *
  * @param string $name
  *   Is either a function of the api (civicrm_{entity}_create or the entity name.
  *   return the DAO name to manipulate this function
  *   eg. "civicrm_contact_create" or "Contact" will return "CRM_Contact_BAO_Contact"
+ *
  * @return mixed
  */
 function _civicrm_api3_get_BAO($name) {
@@ -366,7 +373,8 @@ function _civicrm_api3_get_BAO($name) {
 }
 
 /**
- *  Recursive function to explode value-separated strings into arrays
+ * Recursive function to explode value-separated strings into arrays.
+ *
  * @param $values
  */
 function _civicrm_api3_separate_values(&$values) {
@@ -376,7 +384,8 @@ function _civicrm_api3_separate_values(&$values) {
       _civicrm_api3_separate_values($value);
     }
     elseif (is_string($value)) {
-      if ($key == 'case_type_id') {// this is to honor the way case API was originally written
+      // This is to honor the way case API was originally written.
+      if ($key == 'case_type_id') {
         $value = trim(str_replace($sp, ',', $value), ',');
       }
       elseif (strpos($value, $sp) !== FALSE) {
@@ -387,12 +396,14 @@ function _civicrm_api3_separate_values(&$values) {
 }
 
 /**
- * This is a legacy wrapper for api_store_values which will check the suitable fields using getfields
- * rather than DAO->fields
+ * This is a legacy wrapper for api_store_values.
+ *
+ * It checks suitable fields using getfields rather than DAO->fields.
  *
- * Getfields has handling for how to deal with uniquenames which dao->fields doesn't
+ * Getfields has handling for how to deal with unique names which dao->fields doesn't
  *
  * Note this is used by BAO type create functions - eg. contribution
+ *
  * @param string $entity
  * @param array $params
  * @param array $values
@@ -403,6 +414,7 @@ function _civicrm_api3_filter_fields_for_bao($entity, &$params, &$values) {
   _civicrm_api3_store_values($fields, $params, $values);
 }
 /**
+ * Store values.
  *
  * @param array $fields
  * @param array $params
@@ -424,7 +436,9 @@ function _civicrm_api3_store_values(&$fields, &$params, &$values) {
 }
 
 /**
- * The API supports 2 types of get requestion. The more complex uses the BAO query object.
+ * Get function for query object api.
+ *
+ * The API supports 2 types of get request. The more complex uses the BAO query object.
  *  This is a generic function for those functions that call it
  *
  *  At the moment only called by contact we should extend to contribution &
@@ -433,6 +447,7 @@ function _civicrm_api3_store_values(&$fields, &$params, &$values) {
  *
  * 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 array $params
  *   As passed into api get or getcount function.
@@ -528,13 +543,15 @@ function _civicrm_api3_get_using_query_object($entity, $params, $additional_opti
 }
 
 /**
- * get dao query object based on input params
+ * Get dao query object based on input params.
+ *
  * Ideally this would be merged with _civicrm_get_using_query_object but we need to resolve differences in what the
  * 2 variants call
  *
  * @param array $params
  * @param string $mode
  * @param string $entity
+ *
  * @return array
  *   [CRM_Core_DAO|CRM_Contact_BAO_Query]
  */
@@ -569,7 +586,8 @@ function _civicrm_api3_get_query_object($params, $mode, $entity) {
 }
 
 /**
- * Function transfers the filters being passed into the DAO onto the params object
+ * Function transfers the filters being passed into the DAO onto the params object.
+ *
  * @param CRM_Core_DAO $dao
  * @param array $params
  * @param bool $unique
@@ -642,7 +660,8 @@ function _civicrm_api3_dao_set_filter(&$dao, $params, $unique = TRUE, $entity) {
       $dao->selectAdd($returnValue);
     }
 
-    $unmatchedFields = array_diff(// not already matched on the field names
+    // Not already matched on the field names.
+    $unmatchedFields = array_diff(
       array_keys($options['return']),
       $returnMatched
     );
@@ -659,7 +678,8 @@ function _civicrm_api3_dao_set_filter(&$dao, $params, $unique = TRUE, $entity) {
 }
 
 /**
- * Apply filters (e.g. high, low) to DAO object (prior to find)
+ * Apply filters (e.g. high, low) to DAO object (prior to find).
+ *
  * @param string $filterField
  *   Field name of filter.
  * @param string $filterValue
@@ -908,6 +928,8 @@ function _civicrm_api3_dao_to_array($dao, $params = NULL, $uniqueFields = TRUE,
 }
 
 /**
+ * Determine if custom fields need to be retrieved.
+ *
  * We currently retrieve all custom fields or none at this level so if we know the entity
  * && it can take custom fields & there is the string 'custom' in their return request we get them all, they are filtered on the way out
  * @todo filter so only required fields are queried
@@ -923,14 +945,14 @@ function _civicrm_api3_custom_fields_are_required($entity, $params) {
     return FALSE;
   }
   $options = _civicrm_api3_get_options_from_params($params);
-  //we check for possibility of 'custom' => 1 as well as specific custom fields
+  // We check for possibility of 'custom' => 1 as well as specific custom fields.
   $returnString = implode('', $options['return']) . implode('', array_keys($options['return']));
   if (stristr($returnString, 'custom')) {
     return TRUE;
   }
 }
 /**
- * Converts an object to an array
+ * Converts an object to an array.
  *
  * @param object $dao
  *   (reference) object to convert.