From: Eileen McNaughton <eileen@fuzion.co.nz>
Date: Mon, 12 Jan 2015 22:49:22 +0000 (+1300)
Subject: a few random comment fixes
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=645ee340d9b8d81fcce96e108abc4a8a24f134cc;p=civicrm-core.git

a few random comment fixes
---

diff --git a/CRM/Activity/Controller/Search.php b/CRM/Activity/Controller/Search.php
index 43f515369d..ca5f8cb3fc 100644
--- a/CRM/Activity/Controller/Search.php
+++ b/CRM/Activity/Controller/Search.php
@@ -47,6 +47,9 @@ class CRM_Activity_Controller_Search extends CRM_Core_Controller {
 
   /**
    * Class constructor
+   * @param null $title
+   * @param bool $modal
+   * @param int|mixed|null $action
    */
   public function __construct($title = NULL, $modal = TRUE, $action = CRM_Core_Action::NONE) {
 
diff --git a/CRM/Activity/Form/Activity.php b/CRM/Activity/Form/Activity.php
index b10b90cb23..1a9c9ce345 100644
--- a/CRM/Activity/Form/Activity.php
+++ b/CRM/Activity/Form/Activity.php
@@ -1148,6 +1148,8 @@ class CRM_Activity_Form_Activity extends CRM_Contact_Form_Task {
 
   /**
    * Shorthand for getting id by display name (makes code more readable)
+   * @param $displayName
+   * @return null|string
    */
   protected function _getIdByDisplayName($displayName) {
     return CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact',
@@ -1159,6 +1161,8 @@ class CRM_Activity_Form_Activity extends CRM_Contact_Form_Task {
 
   /**
    * Shorthand for getting display name by id (makes code more readable)
+   * @param $id
+   * @return null|string
    */
   protected function _getDisplayNameById($id) {
     return CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact',
diff --git a/CRM/Activity/Import/Controller.php b/CRM/Activity/Import/Controller.php
index e838df67b5..dbec3aa18d 100644
--- a/CRM/Activity/Import/Controller.php
+++ b/CRM/Activity/Import/Controller.php
@@ -36,6 +36,9 @@ class CRM_Activity_Import_Controller extends CRM_Core_Controller {
 
   /**
    * Class constructor
+   * @param null $title
+   * @param bool|int $action
+   * @param bool $modal
    */
   public function __construct($title = NULL, $action = CRM_Core_Action::NONE, $modal = TRUE) {
     parent::__construct($title, $modal);
diff --git a/CRM/Activity/Import/Field.php b/CRM/Activity/Import/Field.php
index b865151ab4..532b667f77 100644
--- a/CRM/Activity/Import/Field.php
+++ b/CRM/Activity/Import/Field.php
@@ -108,6 +108,7 @@ class CRM_Activity_Import_Field {
   /**
    * The value is in string format. convert the value to the type of this field
    * and set the field value with the appropriate type
+   * @param $value
    */
   public function setValue($value) {
     $this->_value = $value;
diff --git a/CRM/Activity/Import/Parser/Activity.php b/CRM/Activity/Import/Parser/Activity.php
index da723f0ec1..bf077530dc 100644
--- a/CRM/Activity/Import/Parser/Activity.php
+++ b/CRM/Activity/Import/Parser/Activity.php
@@ -56,6 +56,9 @@ class CRM_Activity_Import_Parser_Activity extends CRM_Activity_Import_Parser {
 
   /**
    * Class constructor
+   * @param $mapperKeys
+   * @param null $mapperLocType
+   * @param null $mapperPhoneType
    */
   public function __construct(&$mapperKeys, $mapperLocType = NULL, $mapperPhoneType = NULL) {
     parent::__construct();
diff --git a/CRM/Activity/StateMachine/Search.php b/CRM/Activity/StateMachine/Search.php
index d9713b8c29..3525c17356 100644
--- a/CRM/Activity/StateMachine/Search.php
+++ b/CRM/Activity/StateMachine/Search.php
@@ -42,6 +42,8 @@ class CRM_Activity_StateMachine_Search extends CRM_Core_StateMachine {
 
   /**
    * Class constructor
+   * @param object $controller
+   * @param \const|int $action
    */
   public function __construct($controller, $action = CRM_Core_Action::NONE) {
     parent::__construct($controller, $action);
diff --git a/CRM/Campaign/Form/Petition.php b/CRM/Campaign/Form/Petition.php
index 86ee1ccda2..973b6e29b9 100644
--- a/CRM/Campaign/Form/Petition.php
+++ b/CRM/Campaign/Form/Petition.php
@@ -253,6 +253,10 @@ class CRM_Campaign_Form_Petition extends CRM_Core_Form {
 
   /**
    * Global validation rules for the form
+   * @param $fields
+   * @param $files
+   * @param $form
+   * @return array|bool
    */
   public static function formRule($fields, $files, $form) {
     $errors = array();
diff --git a/CRM/Report/Form/Contribute/History.php b/CRM/Report/Form/Contribute/History.php
index fe8ee105af..9ae238833f 100644
--- a/CRM/Report/Form/Contribute/History.php
+++ b/CRM/Report/Form/Contribute/History.php
@@ -519,6 +519,7 @@ class CRM_Report_Form_Contribute_History extends CRM_Report_Form {
   }
 
   /**
+   * @param $sql
    * @param $rows
    */
   public function buildRows($sql, &$rows) {
diff --git a/api/class.api.php b/api/class.api.php
index 7112996141..8b2c2145ee 100644
--- a/api/class.api.php
+++ b/api/class.api.php
@@ -134,6 +134,9 @@ class civicrm_api3 {
 
   /**
    * Perform action
+   * @param $action
+   * @param $params
+   * @return bool
    */
   public function __call($action, $params) {
     // @TODO Check if it's a valid action.
@@ -147,6 +150,8 @@ class civicrm_api3 {
 
   /**
    *  As of PHP 5.3.0
+   * @param $name
+   * @param $arguments
    */
   public static function __callStatic($name, $arguments) {
     // Should we implement it ?
@@ -155,7 +160,10 @@ class civicrm_api3 {
 
   /**
    * Call via rest
-   * @return stdClass
+   * @param $entity
+   * @param $action
+   * @param array $params
+   * @return \stdClass
    */
   function remoteCall($entity, $action, $params = array()) {
     $fields = "key={$this->key}&api_key={$this->api_key}";
@@ -268,6 +276,8 @@ class civicrm_api3 {
   }
 
   /**
+   * @param $name
+   * @param null $value
    * @return $this
    */
   public function attr($name, $value = NULL) {
@@ -298,6 +308,7 @@ class civicrm_api3 {
   }
 
   /**
+   * @param $name
    * @return $this
    */
   public function __get($name) {
diff --git a/api/v3/ActionSchedule.php b/api/v3/ActionSchedule.php
index 2f5c4c929b..f9e6dc80ab 100644
--- a/api/v3/ActionSchedule.php
+++ b/api/v3/ActionSchedule.php
@@ -38,7 +38,8 @@
 /**
  * Get CiviCRM Action Schedule details
  * {@getfields action_schedule_create}
- *
+ * @param $params
+ * @return array
  */
 function civicrm_api3_action_schedule_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'action_schedule');
diff --git a/api/v3/CaseType.php b/api/v3/CaseType.php
index b24b7be45b..3d6508c7d9 100644
--- a/api/v3/CaseType.php
+++ b/api/v3/CaseType.php
@@ -90,8 +90,9 @@ function civicrm_api3_case_type_get($params) {
 /**
  * format definition
  *
- * @param $caseTypes
+ * @param array $result
  * @return mixed
+ * @throws \CRM_Core_Exception
  */
 function _civicrm_api3_case_type_get_formatResult(&$result) {
   foreach ($result['values'] as $key => $caseType) {
diff --git a/api/v3/Contact.php b/api/v3/Contact.php
index 0bdcffdeaf..7029bc5f71 100644
--- a/api/v3/Contact.php
+++ b/api/v3/Contact.php
@@ -560,7 +560,9 @@ function _civicrm_api3_greeting_format_params($params) {
  * @deprecated
  *
  * {@example ContactGetquick.php 0}
- *
+ * @param $params
+ * @return array
+ * @throws \API_Exception
  */
 function civicrm_api3_contact_getquick($params) {
   civicrm_api3_verify_mandatory($params, NULL, array('name'));
diff --git a/api/v3/Contribution.php b/api/v3/Contribution.php
index cdaa8f056a..fc73fe82d4 100644
--- a/api/v3/Contribution.php
+++ b/api/v3/Contribution.php
@@ -151,6 +151,7 @@ function _civicrm_api3_contribution_create_spec(&$params) {
  * The main purpose of the API is to provide integrators a level of stability not provided by
  * the core code or schema - this means we have to provide support for api calls (where possible)
  * across schema changes.
+ * @param $params
  */
 function _civicrm_api3_contribution_create_legacy_support_45(&$params) {
   //legacy soft credit handling - recommended approach is chaining
@@ -196,6 +197,7 @@ function civicrm_api3_contribution_delete($params) {
 
 /**
  * modify metadata. Legacy support for contribution_id
+ * @param $params
  */
 function _civicrm_api3_contribution_delete_spec(&$params) {
   $params['id']['api.aliases'] = array('contribution_id');
@@ -239,6 +241,7 @@ function civicrm_api3_contribution_get($params) {
  * This function is used to format the soft credit for backward compatibility
  * 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
  */
 function _civicrm_api3_format_soft_credit(&$contribution) {
   if (!empty($contribution['soft_credit'])) {
diff --git a/api/v3/CustomField.php b/api/v3/CustomField.php
index 86e507998a..13bd9d4dc7 100644
--- a/api/v3/CustomField.php
+++ b/api/v3/CustomField.php
@@ -262,6 +262,8 @@ SELECT count(*)
 
 /**
  * CRM-15191 - Hack to ensure the cache gets cleared after updating a custom field
+ * @param $params
+ * @return array
  */
 function civicrm_api3_custom_field_setvalue($params) {
   require_once 'api/v3/Generic/Setvalue.php';
diff --git a/api/v3/CustomGroup.php b/api/v3/CustomGroup.php
index 011d821c51..e089ed30a1 100644
--- a/api/v3/CustomGroup.php
+++ b/api/v3/CustomGroup.php
@@ -131,6 +131,8 @@ function civicrm_api3_custom_group_get($params) {
 
 /**
  * CRM-15191 - Hack to ensure the cache gets cleared after updating a custom group
+ * @param $params
+ * @return array
  */
 function civicrm_api3_custom_group_setvalue($params) {
   require_once 'api/v3/Generic/Setvalue.php';
diff --git a/api/v3/DashboardContact.php b/api/v3/DashboardContact.php
index da1b0fbe5c..bb3b1f5b39 100644
--- a/api/v3/DashboardContact.php
+++ b/api/v3/DashboardContact.php
@@ -108,6 +108,9 @@ function _civicrm_api3_dashboard_contact_check_params(&$params) {
  *
  * {@getfields dashboard_contact_delete}
  * @access public
+ * @param $params
+ * @return array
+ * @throws \API_Exception
  */
 function civicrm_api3_dashboard_contact_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/Domain.php b/api/v3/Domain.php
index 6265eace6c..5c74b5c929 100644
--- a/api/v3/Domain.php
+++ b/api/v3/Domain.php
@@ -40,6 +40,9 @@
  * Get CiviCRM domain details
  * {@getfields domain_create}
  * @example DomainGet.php
+ * @param $params
+ * @return array
+ * @throws \API_Exception
  */
 function civicrm_api3_domain_get($params) {
 
diff --git a/api/v3/Entity.php b/api/v3/Entity.php
index 1346b66aa0..5b70b6e5ee 100644
--- a/api/v3/Entity.php
+++ b/api/v3/Entity.php
@@ -20,6 +20,8 @@ function _civicrm_api3_entity_deprecation($entities) {
 
 /**
  *  Placeholder function. This should never be called, as it doesn't have any meaning
+ * @param $params
+ * @return array
  */
 function civicrm_api3_entity_create($params) {
   return civicrm_api3_create_error("API (Entity, Create) does not exist Creating a new entity means modifying the source code of civiCRM.");
@@ -27,6 +29,8 @@ function civicrm_api3_entity_create($params) {
 
 /**
  *  Placeholder function. This should never be called, as it doesn't have any meaning
+ * @param $params
+ * @return array
  */
 function civicrm_api3_entity_delete($params) {
   return civicrm_api3_create_error("API (Entity, Delete) does not exist Deleting an entity means modifying the source code of civiCRM.");
@@ -34,6 +38,8 @@ function civicrm_api3_entity_delete($params) {
 
 /**
  *  Placeholder function. This should never be called, as it doesn't have any meaning
+ * @param $params
+ * @return array
  */
 function civicrm_api3_entity_getfields($params) {
   // we return an empty array so it makes it easier to write generic getdefaults / required tests
diff --git a/api/v3/EntityTag.php b/api/v3/EntityTag.php
index ec5794da16..8aab901256 100644
--- a/api/v3/EntityTag.php
+++ b/api/v3/EntityTag.php
@@ -102,6 +102,7 @@ function civicrm_api3_entity_tag_delete($params) {
 
 /**
  * modify metadata
+ * @param $params
  */
 function _civicrm_api3_entity_tag_delete_spec(&$params) {
   // set as not required as tag_id also acceptable & no either/or std yet
diff --git a/api/v3/Event.php b/api/v3/Event.php
index 410e37068f..3a3251bc32 100644
--- a/api/v3/Event.php
+++ b/api/v3/Event.php
@@ -85,6 +85,7 @@ function _civicrm_api3_event_create_spec(&$params) {
  * The main purpose of the API is to provide integrators a level of stability not provided by
  * the core code or schema - this means we have to provide support for api calls (where possible)
  * across schema changes.
+ * @param $params
  */
 function _civicrm_api3_event_create_legacy_support_42(&$params) {
   if (!empty($params['payment_processor_id'])) {
@@ -171,6 +172,8 @@ function _civicrm_api3_event_get_spec(&$params) {
  * The main purpose of the API is to provide integrators a level of stability not provided by
  * the core code or schema - this means we have to provide support for api calls (where possible)
  * across schema changes.
+ * @param $event
+ * @param $event_id
  */
 function _civicrm_api3_event_get_legacy_support_42(&$event, $event_id) {
   if (!empty($event[$event_id]['payment_processor'])) {
@@ -186,17 +189,14 @@ function _civicrm_api3_event_get_legacy_support_42(&$event, $event_id) {
  *
  * This API is used for deleting a event
  *
- * @param array $paramsArray containing event_id to be deleted.
- *   Array containing event_id to be deleted.
+ * @param $params
+ * @return array
  *
- * @return boolean
- *   true if success, error otherwise
  * @access public
  *   note API has legacy support for 'event_id'
  *  {@getfields event_delete}
  */
 function civicrm_api3_event_delete($params) {
-
   return CRM_Event_BAO_Event::del($params['id']) ? civicrm_api3_create_success() : civicrm_api3_create_error(ts('Error while deleting event'));
 }
 /*
diff --git a/api/v3/File.php b/api/v3/File.php
index cacdb7a46f..b0867261e8 100644
--- a/api/v3/File.php
+++ b/api/v3/File.php
@@ -100,12 +100,8 @@ function civicrm_api3_file_get($params) {
  * This api is used for updating an existing file.
  * Required parameters : id of a file
  *
- * @param array $paramsAn array of name/value property values of civicrm_file.
- *   An array of name/value property values of civicrm_file.
- *
+ * @param array $params
  * @return array
- *   Array of updated file object property values
- * @access public
  */
 function civicrm_api3_file_update($params) {
 
diff --git a/api/v3/GroupContact.php b/api/v3/GroupContact.php
index fc66123908..1c01e9d6f3 100644
--- a/api/v3/GroupContact.php
+++ b/api/v3/GroupContact.php
@@ -139,6 +139,7 @@ function civicrm_api3_group_contact_delete($params) {
 
 /**
  * modify metadata
+ * @param $params
  */
 function _civicrm_api3_group_contact_delete_spec(&$params) {
   // set as not required no either/or std yet
@@ -228,6 +229,9 @@ function _civicrm_api3_group_contact_common($params, $op = 'Added') {
 
 /**
  * @deprecated - this should be part of create but need to know we aren't missing something
+ * @param $params
+ * @return bool
+ * @throws \API_Exception
  */
 function civicrm_api3_group_contact_update_status($params) {
 
diff --git a/api/v3/Mailing.php b/api/v3/Mailing.php
index 45102e5695..2a1119c219 100755
--- a/api/v3/Mailing.php
+++ b/api/v3/Mailing.php
@@ -583,6 +583,8 @@ function civicrm_api3_mailing_stats($params) {
  * Fix the reset dates on the email record based on when a mail was last delivered
  * We only consider mailings that were completed and finished in the last 3 to 7 days
  * Both the min and max days can be set via the params
+ * @param $params
+ * @return array
  */
 function civicrm_api3_mailing_update_email_resetdate($params) {
   CRM_Mailing_Event_BAO_Delivered::updateEmailResetDate(
diff --git a/api/v3/MailingAB.php b/api/v3/MailingAB.php
index 9615f081f1..bd825f5289 100755
--- a/api/v3/MailingAB.php
+++ b/api/v3/MailingAB.php
@@ -40,7 +40,6 @@
  * Handle a create mailing ab testing
  *
  * @param array $params
- * @param array $ids
  *
  * @return array
  *   API Success Array
@@ -53,7 +52,6 @@ function civicrm_api3_mailing_a_b_create($params) {
  * Handle a delete event.
  *
  * @param array $params
- * @param array $ids
  *
  * @return array
  *   API Success Array
diff --git a/api/v3/MailingJob.php b/api/v3/MailingJob.php
index 11f10779ab..eeaee7681e 100644
--- a/api/v3/MailingJob.php
+++ b/api/v3/MailingJob.php
@@ -38,6 +38,9 @@
 
 /**
  * Handle creation of a Mailing Job for a Mailing.
+ * @param $params
+ * @return array
+ * @throws \API_Exception
  */
 function civicrm_api3_mailing_job_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -74,6 +77,9 @@ function civicrm_api3_mailing_job_get($params, $ids = array()) {
 
 /**
  * Handle deletion of a Mailing Job for a Mailing.
+ * @param $params
+ * @return array
+ * @throws \API_Exception
  */
 function civicrm_api3_mailing_job_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/MessageTemplate.php b/api/v3/MessageTemplate.php
index 6bd144b6e9..d72c1ef8df 100644
--- a/api/v3/MessageTemplate.php
+++ b/api/v3/MessageTemplate.php
@@ -33,6 +33,9 @@
 
 /**
  * @access public
+ * @param $params
+ * @return array
+ * @throws \API_Exception
  */
 function civicrm_api3_message_template_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -94,6 +97,7 @@ function civicrm_api3_message_template_get($params) {
 
 /**
  * Sends a template.
+ * @param $params
  */
 function civicrm_api3_message_template_send($params) {
   CRM_Core_BAO_MessageTemplates::sendTemplate($params);
diff --git a/api/v3/Participant.php b/api/v3/Participant.php
index e19d028916..a1cb21aca2 100644
--- a/api/v3/Participant.php
+++ b/api/v3/Participant.php
@@ -77,6 +77,9 @@ function civicrm_api3_participant_create($params) {
 /**
  * @todo this should be done in the BAO not the api
  * Create a default participant line item
+ * @param $params
+ * @param $participant
+ * @throws \CiviCRM_API3_Exception
  */
 function _civicrm_api3_participant_createlineitem(&$params, $participant) {
   // it is possible that a fee level contains information about multiple
diff --git a/api/v3/PaymentProcessorType.php b/api/v3/PaymentProcessorType.php
index 6012a6a07c..1cdac8dd31 100644
--- a/api/v3/PaymentProcessorType.php
+++ b/api/v3/PaymentProcessorType.php
@@ -90,6 +90,8 @@ function _civicrm_api3_payment_processor_type_create_spec(&$params) {
  * @access  public
  * {@getfields PaymentProcessorType_get}
  * @example PaymentProcessorTypeGet.php
+ * @param $params
+ * @return array
  */
 function civicrm_api3_payment_processor_type_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/Pledge.php b/api/v3/Pledge.php
index cdc79d7cbc..958f38d305 100644
--- a/api/v3/Pledge.php
+++ b/api/v3/Pledge.php
@@ -96,6 +96,7 @@ function _civicrm_api3_pledge_delete_spec(&$params) {
 
 /**
  * return field specification specific to get requests
+ * @param $params
  */
 function _civicrm_api3_pledge_get_spec(&$params) {
   $params['next_pay_date'] = array(
@@ -112,6 +113,7 @@ function _civicrm_api3_pledge_get_spec(&$params) {
 
 /**
  * return field specification specific to get requests
+ * @param $params
  */
 function _civicrm_api3_pledge_create_spec(&$params) {
 
diff --git a/api/v3/Premium.php b/api/v3/Premium.php
index 46f7915616..348bab99cd 100644
--- a/api/v3/Premium.php
+++ b/api/v3/Premium.php
@@ -88,6 +88,7 @@ function civicrm_api3_premium_delete($params) {
 
 /**
  * return field specification specific to get requests
+ * @param $params
  */
 function _civicrm_api3_premium_get_spec(&$params) {
   $params['premiums_active']['api.aliases'] = array('is_active');
@@ -95,6 +96,7 @@ function _civicrm_api3_premium_get_spec(&$params) {
 
 /**
  * return field specification specific to create requests
+ * @param $params
  */
 function _civicrm_api3_premium_create_spec(&$params) {
   $params['premiums_active']['api.aliases'] = array('is_active');
diff --git a/api/v3/RelationshipType.php b/api/v3/RelationshipType.php
index 6d13a07b3d..aa72f13665 100644
--- a/api/v3/RelationshipType.php
+++ b/api/v3/RelationshipType.php
@@ -98,6 +98,8 @@ function _civicrm_api3_relationship_type_create_spec(&$params) {
  * @access  public
  * {@getfields RelationshipType_get}
  * @example RelationshipTypeGet.php
+ * @param $params
+ * @return array
  */
 function civicrm_api3_relationship_type_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/Setting.php b/api/v3/Setting.php
index ba35cdd866..0d0d3cdeb3 100644
--- a/api/v3/Setting.php
+++ b/api/v3/Setting.php
@@ -32,7 +32,8 @@
  * @subpackage API_Settings
  * @copyright CiviCRM LLC (c) 2004-2014
  * @version $Id: Settings.php
- *
+ * @param $params
+ * @return array
  */
 
 function civicrm_api3_setting_getfields($params) {
@@ -73,6 +74,7 @@ function civicrm_api3_setting_getfields($params) {
 
 /**
  * Alter metadata for getfields functions
+ * @param $params
  */
 function _civicrm_api3_setting_getfields_spec(&$params) {
   $params['filters'] = array('title' => 'Fields you wish to filter by e.g. array("group_name" => "CiviCRM Preferences")');
@@ -84,6 +86,10 @@ function _civicrm_api3_setting_getfields_spec(&$params) {
  * Return default values for settings. We will domain key this as it could vary by domain (ie. urls)
  * as we will be creating the option for a function rather than an value to be in the defaults
  * Note that is not in place as yet
+ * @param $params
+ * @return array
+ * @throws \CiviCRM_API3_Exception
+ * @throws \Exception
  */
 function civicrm_api3_setting_getdefaults(&$params) {
   $settings = civicrm_api3('setting', 'getfields', $params);
@@ -124,6 +130,9 @@ function _civicrm_api3_setting_getdefaults_spec(&$params) {
 
 /**
  * Revert settings to defaults
+ * @param $params
+ * @return array
+ * @throws \Exception
  */
 function civicrm_api3_setting_revert(&$params) {
   $defaults = civicrm_api('setting', 'getdefaults', $params);
@@ -146,6 +155,7 @@ function civicrm_api3_setting_revert(&$params) {
 
 /**
  * Alter metadata for getfields functions
+ * @param $params
  */
 function _civicrm_api3_setting_revert_spec(&$params) {
   $params['name'] = array('title' => 'Setting Name belongs to');
@@ -160,6 +170,10 @@ function _civicrm_api3_setting_revert_spec(&$params) {
 
 /**
  * Revert settings to defaults
+ * @param $params
+ * @return array
+ * @throws \CiviCRM_API3_Exception
+ * @throws \Exception
  */
 function civicrm_api3_setting_fill(&$params) {
   $defaults = civicrm_api3('setting', 'getdefaults', $params);
@@ -181,6 +195,7 @@ function civicrm_api3_setting_fill(&$params) {
 
 /**
  * Alter metadata for getfields functions
+ * @param $params
  */
 function _civicrm_api3_setting_fill_spec(&$params) {
   $params['name'] = array('title' => 'Setting Name belongs to');
@@ -331,6 +346,9 @@ function _civicrm_api3_setting_getvalue_spec(&$params) {
  * Really domain_id should always be set but doing an empty check because at the moment
  * using crm-editable will pass an id & default won't be applied
  * we did talk about id being a pseudonym for domain_id in this api so applying it here
+ * @param $params
+ * @return array
+ * @throws \Exception
  */
 function _civicrm_api3_setting_getDomainArray(&$params) {
   if (empty($params['domain_id']) && isset($params['id'])) {
diff --git a/api/v3/SurveyRespondant.php b/api/v3/SurveyRespondant.php
index 23288b93ff..31b900ef3a 100644
--- a/api/v3/SurveyRespondant.php
+++ b/api/v3/SurveyRespondant.php
@@ -81,6 +81,8 @@ function civicrm_api3_survey_respondant_get(&$params) {
 
 /**
  * @deprecated - api currently not supported
+ * @param $params
+ * @return array
  */
 function &civicrm_api3_survey_respondant_count($params) {
 
diff --git a/api/v3/UFField.php b/api/v3/UFField.php
index c9bd9027cf..122179e9b2 100644
--- a/api/v3/UFField.php
+++ b/api/v3/UFField.php
@@ -174,8 +174,10 @@ function civicrm_api3_uf_field_delete($params) {
 
   return civicrm_api3_create_success($result, $params);
 }
+
 /**
  * field id accepted for backward compatibility - unset required on id
+ * @param $params
  */
 function _civicrm_api3_uf_field_delete_spec(&$params) {
   // legacy support for field_id
diff --git a/api/v3/WordReplacement.php b/api/v3/WordReplacement.php
index 72e6f82fea..d019bd4cb9 100644
--- a/api/v3/WordReplacement.php
+++ b/api/v3/WordReplacement.php
@@ -39,7 +39,9 @@
 /**
  * Get CiviCRM Word Replacement details
  * {@getfields word_replacement_create}
- *
+ * @param $params
+ * @return array
+ * @throws \API_Exception
  */
 function civicrm_api3_word_replacement_get($params) {
   $bao = new CRM_Core_BAO_WordReplacement();
diff --git a/api/v3/utils.php b/api/v3/utils.php
index 087aa74c87..53076f73e6 100644
--- a/api/v3/utils.php
+++ b/api/v3/utils.php
@@ -135,11 +135,9 @@ function civicrm_api3_verify_mandatory($params, $daoName = NULL, $keys = array()
 
 /**
  *
+ * @param $msg
  * @param array $data
- *
- * @throws API_Exception
  * @return array
- *   <type>
  */
 function civicrm_api3_create_error($msg, $data = array()) {
   $data['is_error'] = 1;
@@ -272,6 +270,8 @@ function civicrm_api3_create_success($values = 1, $params = array(), $entity = N
 
 /**
  * Load the DAO of the entity
+ * @param $entity
+ * @return bool
  */
 function _civicrm_api3_load_DAO($entity) {
   $dao = _civicrm_api3_get_DAO($entity);
@@ -375,7 +375,7 @@ function _civicrm_api3_get_BAO($name) {
 
 /**
  *  Recursive function to explode value-separated strings into arrays
- *
+ * @param $values
  */
 function _civicrm_api3_separate_values(&$values) {
   $sp = CRM_Core_DAO::VALUE_SEPARATOR;
@@ -825,6 +825,9 @@ function _civicrm_api3_apply_options_to_dao(&$params, &$dao, $entity) {
 /**
  * build fields array. This is the array of fields as it relates to the given DAO
  * returns unique fields as keys by default but if set but can return by DB fields
+ * @param $bao
+ * @param bool $unique
+ * @return
  */
 function _civicrm_api3_build_fields_array(&$bao, $unique = TRUE) {
   $fields = $bao->fields();
@@ -958,6 +961,9 @@ 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
+ * @return array
  */
 function _civicrm_api3_object_to_array_unique_fields(&$dao, &$values) {
   return _civicrm_api3_object_to_array($dao, $values, TRUE);
@@ -1519,13 +1525,12 @@ function _civicrm_api3_getValidDate($dateValue, $fieldName, $fieldType) {
 /**
  * Validate foreign constraint fields being passed into API.
  *
- * @param array $params
- *   Params from civicrm_api.
+ * @param mixed $fieldValue
  * @param string $fieldName
  *   Uniquename of field being checked.
  * @param array $fieldInfo
  *   Array of fields from getfields function.
- * @throws Exception
+ * @throws \API_Exception
  */
 function _civicrm_api3_validate_constraint(&$fieldValue, &$fieldName, &$fieldInfo) {
   $dao = new $fieldInfo['FKClassName'];
@@ -1533,7 +1538,7 @@ function _civicrm_api3_validate_constraint(&$fieldValue, &$fieldName, &$fieldInf
   $dao->selectAdd();
   $dao->selectAdd('id');
   if (!$dao->find()) {
-    throw new Exception("$fieldName is not valid : " . $fieldValue);
+    throw new API_Exception("$fieldName is not valid : " . $fieldValue);
   }
 }
 
@@ -1713,6 +1718,9 @@ function _civicrm_api_get_fields($entity, $unique = FALSE, &$params = array()) {
 /**
  * Return an array of fields for a given entity - this is the same as the BAO function but
  * fields are prefixed with 'custom_' to represent api params
+ * @param $entity
+ * @param $params
+ * @return array
  */
 function _civicrm_api_get_custom_fields($entity, &$params) {
   $entity = _civicrm_api_get_camel_name($entity);
@@ -1742,8 +1750,11 @@ function _civicrm_api_get_custom_fields($entity, &$params) {
   }
   return $ret;
 }
+
 /**
  * Translate the custom field data_type attribute into a std 'type'
+ * @param $dataType
+ * @return
  */
 function _getStandardTypeFromCustomDataType($dataType) {
   $mapping = array(
@@ -1769,6 +1780,8 @@ function _getStandardTypeFromCustomDataType($dataType) {
  * If multiple aliases the last takes precedence
  *
  * Function also swaps unique fields for non-unique fields & vice versa.
+ * @param $apiRequest
+ * @param $fields
  */
 function _civicrm_api3_swap_out_aliases(&$apiRequest, $fields) {
   foreach ($fields as $field => $values) {
@@ -1972,10 +1985,11 @@ function _civicrm_api3_validate_string(&$params, &$fieldName, &$fieldInfo, $enti
 /**
  * Validate & swap out any pseudoconstants / options
  *
- * @param array $params: api parameters
- * @param string $entity: api entity name
- * @param string $fieldName: field name used in api call (not necessarily the canonical name)
- * @param array $fieldInfo: getfields meta-data
+ * @param mixed $fieldValue
+ * @param string $entity : api entity name
+ * @param string $fieldName : field name used in api call (not necessarily the canonical name)
+ * @param array $fieldInfo : getfields meta-data
+ * @throws \API_Exception
  */
 function _civicrm_api3_api_match_pseudoconstant(&$fieldValue, $entity, $fieldName, $fieldInfo) {
   $options = CRM_Utils_Array::value('options', $fieldInfo);