From: Eileen McNaughton Date: Mon, 19 May 2014 02:56:50 +0000 (+1200) Subject: some comment block fixes X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=aa1b148111448caf4a1eba800abed5484291b609;p=civicrm-core.git some comment block fixes --- diff --git a/CRM/Core/Form.php b/CRM/Core/Form.php index ae09c486bd..0cbcedd990 100644 --- a/CRM/Core/Form.php +++ b/CRM/Core/Form.php @@ -1398,17 +1398,17 @@ class CRM_Core_Form extends HTML_QuickForm_Page { } } -/** - * Get contact if for a form object. Prioritise - * - cid in URL if 0 (on behalf on someoneelse) - * (@todo consider setting a variable if onbehalf for clarity of downstream 'if's - * - logged in user id if it matches the one in the cid in the URL - * - contact id validated from a checksum from a checksum - * - cid from the url if the caller has ACL permission to view - * - fallback is logged in user (or ? NULL if no logged in user) (@todo wouldn't 0 be more intuitive?) - * - * @return Ambigous |unknown - */ + /** + * Get contact if for a form object. Prioritise + * - cid in URL if 0 (on behalf on someoneelse) + * (@todo consider setting a variable if onbehalf for clarity of downstream 'if's + * - logged in user id if it matches the one in the cid in the URL + * - contact id validated from a checksum from a checksum + * - cid from the url if the caller has ACL permission to view + * - fallback is logged in user (or ? NULL if no logged in user) (@todo wouldn't 0 be more intuitive?) + * + * @return mixed NULL|integer + */ function getContactID() { $tempID = CRM_Utils_Request::retrieve('cid', 'Positive', $this); if(isset($this->_params) && isset($this->_params['select_contact_id'])) { diff --git a/api/Exception.php b/api/Exception.php index 48d89e7572..953fafdbe9 100644 --- a/api/Exception.php +++ b/api/Exception.php @@ -25,6 +25,13 @@ class API_Exception extends Exception const NOT_IMPLEMENTED = 'not-found'; private $extraParams = array(); + + /** + * @param string $message + * @param int $error_code + * @param array $extraParams + * @param Exception $previous + */ public function __construct($message, $error_code = 0, $extraParams = array(),Exception $previous = null) { if (is_numeric ($error_code)) // using int for error code "old way") $code = $error_code; @@ -35,14 +42,23 @@ class API_Exception extends Exception } // custom string representation of object + /** + * @return string + */ public function __toString() { return __CLASS__ . ": [{$this->code}]: {$this->message}\n"; } + /** + * @return array + */ public function getExtraParams() { return $this->extraParams; } + /** + * @return array + */ public function getErrorCodes(){ return array( 2000 => '$params was not an array', @@ -64,12 +80,22 @@ class API_Exception extends Exception class CiviCRM_API3_Exception extends Exception { private $extraParams = array(); + + /** + * @param string $message + * @param int $error_code + * @param array $extraParams + * @param Exception $previous + */ public function __construct($message, $error_code, $extraParams = array(),Exception $previous = null) { parent::__construct(ts($message)); $this->extraParams = $extraParams + array('error_code' => $error_code); } // custom string representation of object + /** + * @return string + */ public function __toString() { return __CLASS__ . ": [{$this->extraParams['error_code']}: {$this->message}\n"; } @@ -77,6 +103,10 @@ class CiviCRM_API3_Exception extends Exception public function getErrorCode() { return $this->extraParams['error_code']; } + + /** + * @return array + */ public function getExtraParams() { return $this->extraParams; } diff --git a/api/Wrapper.php b/api/Wrapper.php index 73bd8043ec..5693e7153c 100644 --- a/api/Wrapper.php +++ b/api/Wrapper.php @@ -1,5 +1,8 @@ $params); diff --git a/api/v3/Constant.php b/api/v3/Constant.php index 27552311b5..f7dcd5e276 100644 --- a/api/v3/Constant.php +++ b/api/v3/Constant.php @@ -128,6 +128,9 @@ function civicrm_api3_constant_get($params) { return civicrm_api3_create_error('Unknown civicrm constant or method not callable'); } +/** + * @param $params + */ function _civicrm_api3_constant_get_spec(&$params) { $params = (array diff --git a/api/v3/Contact.php b/api/v3/Contact.php index 438544a5ae..90729ff875 100644 --- a/api/v3/Contact.php +++ b/api/v3/Contact.php @@ -154,6 +154,11 @@ function civicrm_api3_contact_get($params) { return civicrm_api3_create_success($contacts, $params, 'contact'); } +/** + * @param $params + * + * @return int + */ function civicrm_api3_contact_getcount($params) { $options = array(); _civicrm_api3_contact_get_supportanomalies($params, $options); @@ -286,6 +291,17 @@ function civicrm_api3_contact_delete($params) { } +/** + * @param $params + * @param bool $dupeCheck + * @param bool $dupeErrorArray + * @param bool $obsoletevalue + * @param null $dedupeRuleGroupID + * + * @return null + * @throws API_Exception + * @throws CiviCRM_API3_Exception + */ function _civicrm_api3_contact_check_params( &$params, $dupeCheck = true, $dupeErrorArray = false, $obsoletevalue = true, $dedupeRuleGroupID = null ) { @@ -857,12 +873,21 @@ function civicrm_api3_contact_merge($params) { } } +/** + * @param $params + */ function _civicrm_api3_contact_proximity_spec(&$params) { $params['latitude']['api.required'] = 1; $params['longitude']['api.required'] = 1; $params['unit']['api.default'] = 'meter'; } +/** + * @param $params + * + * @return array + * @throws Exception + */ function civicrm_api3_contact_proximity($params) { $latitude = CRM_Utils_Array::value('latitude', $params); $longitude = CRM_Utils_Array::value('longitude', $params); diff --git a/api/v3/Contribution.php b/api/v3/Contribution.php index c1b9678380..5ef18c9086 100644 --- a/api/v3/Contribution.php +++ b/api/v3/Contribution.php @@ -403,6 +403,9 @@ function civicrm_api3_contribution_completetransaction(&$params) { } } +/** + * @param $params + */ function _civicrm_api3_contribution_completetransaction(&$params) { $params['id'] = array( 'title' => 'Contribution ID', diff --git a/api/v3/DashboardContact.php b/api/v3/DashboardContact.php index 0bb8ee893e..4df7815f4b 100644 --- a/api/v3/DashboardContact.php +++ b/api/v3/DashboardContact.php @@ -83,6 +83,11 @@ function _civicrm_api3_dashboard_contact_create_spec(&$params) { unset($params['version']); } +/** + * @param $params + * + * @return array|null + */ function _civicrm_api3_dashboard_contact_check_params(&$params) { $dashboard_id = CRM_Utils_Array::value('dashboard_id', $params); if ($dashboard_id) { diff --git a/api/v3/Event.php b/api/v3/Event.php index 478d28460e..93eb30c93e 100644 --- a/api/v3/Event.php +++ b/api/v3/Event.php @@ -220,6 +220,10 @@ function civicrm_api3_event_delete($params) { * @param int $event_id Id of the event to be updated * */ +/** + * @param $event + * @param $event_id + */ function _civicrm_api3_event_getisfull(&$event, $event_id) { $eventFullResult = CRM_Event_BAO_Participant::eventFull($event_id, 1); if (!empty($eventFullResult) && is_int($eventFullResult)) { diff --git a/api/v3/Generic/Getactions.php b/api/v3/Generic/Getactions.php index 9cfbbd67a9..e3520c13a2 100644 --- a/api/v3/Generic/Getactions.php +++ b/api/v3/Generic/Getactions.php @@ -26,6 +26,12 @@ +--------------------------------------------------------------------+ */ +/** + * @param $apiRequest + * + * @return array + * @throws API_Exception + */ function civicrm_api3_generic_getActions($apiRequest) { civicrm_api3_verify_mandatory($apiRequest, NULL, array('entity')); $mfp = \Civi\Core\Container::singleton()->get('magic_function_provider'); diff --git a/api/v3/Location.php b/api/v3/Location.php index d9a22ad8ba..45e81ccadf 100644 --- a/api/v3/Location.php +++ b/api/v3/Location.php @@ -9,10 +9,20 @@ function civicrm_api3_location_create($params) { return civicrm_api3_create_error("API (Location, Create) does not exist, use the Address/Phone/Email/Website API instead", array('obsoleted' => TRUE)); } +/** + * @param $params + * + * @return array + */ function civicrm_api3_location_get($params) { return civicrm_api3_create_error("API (Location, Get) does not exist, use the Address/Phone/Email/Website API instead", array('obsoleted' => TRUE)); } +/** + * @param $params + * + * @return array + */ function civicrm_api3_location_delete($params) { return civicrm_api3_create_error("API (Location, Delete) does not exist, use the Address/Phone/Email/Website API instead", array('obsoleted' => TRUE)); } diff --git a/api/v3/MailingContact.php b/api/v3/MailingContact.php index 6b5765c7a4..8e342e0c82 100644 --- a/api/v3/MailingContact.php +++ b/api/v3/MailingContact.php @@ -92,6 +92,19 @@ function _civicrm_api3_mailing_contact_get_spec(&$params) { ); } +/** + * @param $type + * @param $contactID + * @param $offset + * @param $limit + * @param $selectFields + * @param $fromClause + * @param $whereClause + * @param $sort + * @param $getCount + * + * @return array + */ function _civicrm_api3_mailing_contact_query( $type, $contactID, @@ -194,6 +207,15 @@ LIMIT %2, %3 return $results; } +/** + * @param $contactID + * @param $offset + * @param $limit + * @param $sort + * @param $getCount + * + * @return array + */ function _civicrm_api3_mailing_contact_get_delivered( $contactID, $offset, @@ -225,6 +247,15 @@ AND meb.id IS NULL ); } +/** + * @param $contactID + * @param $offset + * @param $limit + * @param $sort + * @param $getCount + * + * @return array + */ function _civicrm_api3_mailing_contact_get_bounced( $contactID, $offset, diff --git a/api/v3/MailingGroup.php b/api/v3/MailingGroup.php index 5fe96dd2f2..c042a393cf 100644 --- a/api/v3/MailingGroup.php +++ b/api/v3/MailingGroup.php @@ -86,6 +86,11 @@ function civicrm_api3_mailing_group_event_subscribe($params) { return civicrm_api('mailing_event_subscribe', 'create', $params); } +/** + * @param $params + * + * @return array + */ function civicrm_api3_mailing_group_getfields($params) { $dao = _civicrm_api3_get_DAO('Subscribe'); $d = new $dao(); diff --git a/api/v3/MessageTemplate.php b/api/v3/MessageTemplate.php index fcfd05fdcb..809db8fcbe 100644 --- a/api/v3/MessageTemplate.php +++ b/api/v3/MessageTemplate.php @@ -65,6 +65,9 @@ function civicrm_api3_message_template_delete($params) { return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params); } +/** + * @param $params + */ function _civicrm_api3_message_template_get_spec(&$params) { } diff --git a/api/v3/OptionGroup.php b/api/v3/OptionGroup.php index bfe9590ee9..27d0cb5708 100644 --- a/api/v3/OptionGroup.php +++ b/api/v3/OptionGroup.php @@ -1,5 +1,10 @@ $params['instance_id'], 'return' => 'report_id')); @@ -141,6 +148,11 @@ function _civicrm_api3_report_template_getrows($params) { return array($rows, $reportInstance, $metadata); } +/** + * @param $params + * + * @return array + */ function civicrm_api3_report_template_getstatistics($params) { list($rows, $reportInstance, $metadata) = _civicrm_api3_report_template_getrows($params); $stats = $reportInstance->statistics($rows);