a few random comment fixes

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) {
 

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',

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);

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;

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();

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);

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();

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) {

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) {

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');

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) {

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'));

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'])) {

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';

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';

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);

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) {
 

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

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

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'));
 }
 /*

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) {
 

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) {
 

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(

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

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);

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);

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

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);

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) {
 

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');

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);

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'])) {

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) {
 

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

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();

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.