Commit 645ee340 authored by Eileen McNaughton's avatar Eileen McNaughton

a few random comment fixes

parent 1e1fdcf6
......@@ -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) {
......
......@@ -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',
......
......@@ -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);
......
......@@ -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;
......
......@@ -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();
......
......@@ -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);
......
......@@ -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();
......
......@@ -519,6 +519,7 @@ class CRM_Report_Form_Contribute_History extends CRM_Report_Form {
}
/**
* @param $sql
* @param $rows
*/
public function buildRows($sql, &$rows) {
......
......@@ -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) {
......
......@@ -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');
......
......@@ -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) {
......
......@@ -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'));
......
......@@ -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'])) {
......
......@@ -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';
......
......@@ -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';
......
......@@ -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);
......
......@@ -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) {
......
......@@ -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
......
......@@ -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
......
......@@ -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'));
}
/*
......
......@@ -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) {
......
......@@ -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) {
......
......@@ -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(
......
......@@ -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
......
......@@ -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);
......
......@@ -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);
......
......@@ -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
......
......@@ -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);
......
......@@ -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) {
......
......@@ -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');
......
......@@ -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);
......
......@@ -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'])) {
......
......@@ -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) {
......
......@@ -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
......
......@@ -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();
......
......@@ -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.