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

some more comment fixes
---

diff --git a/CRM/Core/BAO/Setting.php b/CRM/Core/BAO/Setting.php
index f42e66c6f9..14d45628ca 100644
--- a/CRM/Core/BAO/Setting.php
+++ b/CRM/Core/BAO/Setting.php
@@ -260,15 +260,14 @@ class CRM_Core_BAO_Setting extends CRM_Core_DAO_Setting {
   }
 
   /**
-   * Store multiple items in the setting table
+   * Store multiple items in the setting table.
    *
    * @param array $params
    *   (required) An api formatted array of keys and values.
-   * @param null $domains
+   * @param array $domains Array of domains to get settings for. Default is the current domain
    * @param $settingsToReturn
    *
-   * @domains array an array of domains to get settings for. Default is the current domain
-   * @return void
+   * @return array
    */
   public static function getItems(&$params, $domains = NULL, $settingsToReturn) {
     $originalDomain = CRM_Core_Config::domainID();
diff --git a/api/v3/Attachment.php b/api/v3/Attachment.php
index ccd87b143a..70f9d74ae7 100644
--- a/api/v3/Attachment.php
+++ b/api/v3/Attachment.php
@@ -365,6 +365,7 @@ function _civicrm_api3_attachment_parse_params($params) {
  *   Whether to return the full content of the file.
  * @param bool $isTrusted
  *   Whether the current request is trusted to perform file-specific operations.
+ *
  * @return array
  */
 function _civicrm_api3_attachment_format_result($fileDao, $entityFileDao, $returnContent, $isTrusted) {
diff --git a/api/v3/Campaign.php b/api/v3/Campaign.php
index 569867dae9..e33b2edc75 100644
--- a/api/v3/Campaign.php
+++ b/api/v3/Campaign.php
@@ -61,7 +61,7 @@ function _civicrm_api3_campaign_create_spec(&$params) {
 }
 
 /**
- * Returns array of campaigns  matching a set of one or more group properties
+ * Returns array of campaigns  matching a set of one or more group properties.
  *
  * @param array $params
  *   Array per getfields
@@ -74,7 +74,7 @@ function civicrm_api3_campaign_get($params) {
 }
 
 /**
- * delete an existing campaign
+ * Delete an existing campaign.
  *
  * This method is used to delete any existing campaign. id of the group
  * to be deleted is required field in $params array
diff --git a/api/v3/Case.php b/api/v3/Case.php
index fa1fee74be..308b98d950 100644
--- a/api/v3/Case.php
+++ b/api/v3/Case.php
@@ -268,7 +268,9 @@ SELECT DISTINCT case_id
 }
 
 /**
- * Deprecated. Use activity API instead
+ * Deprecated API.
+ *
+ * Use activity API instead.
  *
  * @param array $params
  *
@@ -283,6 +285,8 @@ function civicrm_api3_case_activity_create($params) {
 }
 
 /**
+ * Declare deprecated api functions.
+ *
  * @deprecated api notice
  * @return array
  *   Array of deprecated actions
diff --git a/api/v3/Contact.php b/api/v3/Contact.php
index 14618f8c29..ceb42c52c4 100644
--- a/api/v3/Contact.php
+++ b/api/v3/Contact.php
@@ -837,6 +837,8 @@ LIMIT    0, {$limit}
 }
 
 /**
+ * Declare deprecated api functions.
+ *
  * @deprecated api notice
  * @return array
  *   Array of deprecated actions
diff --git a/api/v3/Contribution.php b/api/v3/Contribution.php
index e97bff6c96..7f3265b3e2 100644
--- a/api/v3/Contribution.php
+++ b/api/v3/Contribution.php
@@ -197,10 +197,10 @@ function _civicrm_api3_contribution_delete_spec(&$params) {
 }
 
 /**
- * Retrieve a set of contributions, given a set of input params
+ * Retrieve a set of contributions.
  *
  * @param array $params
- *   (reference ) input parameters.
+ *  Input parameters.
  *
  * @return array
  *   Array of contributions, if error an array with an error id and error message
diff --git a/api/v3/Event.php b/api/v3/Event.php
index 84eee18804..ae02240f4a 100644
--- a/api/v3/Event.php
+++ b/api/v3/Event.php
@@ -34,18 +34,13 @@
  *
  * @copyright CiviCRM LLC (c) 2004-2014
  * @version $Id: Event.php 30964 2010-11-29 09:41:54Z shot $
- *
  */
 
 /**
- * Create a Event
- *
- * This API is used for creating a Event
+ * Create a Event.
  *
  * @param array $params
  *   Input parameters.
- *   Allowed @params array keys are:
- * {@getfields event_create}
  *
  * @return array
  *   API result Array.
@@ -81,10 +76,12 @@ function _civicrm_api3_event_create_spec(&$params) {
 }
 
 /**
- * Support for schema changes made in 4.2
+ * Support for schema changes made in 4.2.
+ *
  * 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 array $params
  */
 function _civicrm_api3_event_create_legacy_support_42(&$params) {
@@ -152,7 +149,7 @@ function civicrm_api3_event_get($params) {
 }
 
 /**
- * Adjust Metadata for Get action
+ * Adjust Metadata for Get action.
  *
  * The metadata is used for setting defaults, documentation & validation.
  *
@@ -164,12 +161,14 @@ function _civicrm_api3_event_get_spec(&$params) {
 }
 
 /**
- * Support for schema changes made in 4.2
+ * Support for schema changes made in 4.2.
+ *
  * 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
+ *
+ * @param array $event
+ * @param int $event_id
  */
 function _civicrm_api3_event_get_legacy_support_42(&$event, $event_id) {
   if (!empty($event[$event_id]['payment_processor'])) {
@@ -181,31 +180,28 @@ function _civicrm_api3_event_get_legacy_support_42(&$event, $event_id) {
 }
 
 /**
- * Deletes an existing event
+ * Delete an existing event.
  *
- * This API is used for deleting a event
+ * This API is used for deleting a event.
  *
  * @param array $params
+ *
  * @return array
  */
 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'));
 }
-/*
 
 /**
- * add 'is_full' & 'available_seats' to the return array. (this might be better in the BAO)
+ * Add 'is_full' & 'available_seats' to the return array.
+ *
+ * (this might be better in the BAO)
  * Default BAO function returns a string if full rather than a Bool - which is more appropriate to a form
  *
  * @param array $event
  *   Return array of the event.
  * @param int $event_id
  *   Id of the event to be updated.
- *
- */
-/**
- * @param $event
- * @param int $event_id
  */
 function _civicrm_api3_event_getisfull(&$event, $event_id) {
   $eventFullResult = CRM_Event_BAO_Participant::eventFull($event_id, 1);
@@ -220,6 +216,8 @@ function _civicrm_api3_event_getisfull(&$event, $event_id) {
 
 
 /**
+ * Get event list parameters.
+ *
  * @see _civicrm_api3_generic_getlist_params
  *
  * @param array $request
@@ -235,6 +233,8 @@ function _civicrm_api3_event_getlist_params(&$request) {
 }
 
 /**
+ * Get event list output.
+ *
  * @see _civicrm_api3_generic_getlist_output
  *
  * @param array $result
@@ -249,7 +249,13 @@ function _civicrm_api3_event_getlist_output($result, $request) {
       $data = array(
         'id' => $row[$request['id_field']],
         'label' => $row[$request['label_field']],
-        'description' => array(CRM_Core_Pseudoconstant::getLabel('CRM_Event_BAO_Event', 'event_type_id', $row['event_type_id'])),
+        'description' => array(
+          CRM_Core_Pseudoconstant::getLabel(
+            'CRM_Event_BAO_Event',
+            'event_type_id',
+            $row['event_type_id']
+          ),
+        ),
       );
       if (!empty($row['start_date'])) {
         $data['description'][0] .= ': ' . CRM_Utils_Date::customFormat($row['start_date']);
diff --git a/api/v3/Job.php b/api/v3/Job.php
index 3f922aacda..93edc01400 100644
--- a/api/v3/Job.php
+++ b/api/v3/Job.php
@@ -354,7 +354,7 @@ function civicrm_api3_job_fetch_bounces($params) {
 }
 
 /**
- * Job to get mail and create activities
+ * Job to get mail and create activities.
  *
  * @param array $params
  *
@@ -379,10 +379,10 @@ function civicrm_api3_job_fetch_activities($params) {
 }
 
 /**
- * Process participant statuses
+ * Process participant statuses.
  *
  * @param array $params
- *   (reference ) input parameters.
+ *  Input parameters.
  *
  * @return array
  *   array of properties, if error an array with an error id and error message
diff --git a/api/v3/MailingContact.php b/api/v3/MailingContact.php
index f58575e605..5ea8e89705 100644
--- a/api/v3/MailingContact.php
+++ b/api/v3/MailingContact.php
@@ -199,6 +199,8 @@ LIMIT %2, %3
 }
 
 /**
+ * Get delivered mailing contacts.
+ *
  * @param int $contactID
  * @param $offset
  * @param $limit
diff --git a/api/v3/Setting.php b/api/v3/Setting.php
index c1d6b9086a..d934a9fcfc 100644
--- a/api/v3/Setting.php
+++ b/api/v3/Setting.php
@@ -208,16 +208,13 @@ function _civicrm_api3_setting_fill_spec(&$params) {
 }
 
 /**
- * Create or update a setting
+ * Create or update a setting.
  *
  * @param array $params
- *   Associative array of setting.
- *                       name/value pairs + other vars as applicable - see getfields for more
- * @example SettingCreate.php Std Create example
+ *   Parameters as per getfields.
  *
  * @return array
  *   api result array
- *   {@getfields setting_create}
  */
 function civicrm_api3_setting_create($params) {
   $domains = _civicrm_api3_setting_getDomainArray($params);
@@ -245,15 +242,13 @@ function _civicrm_api3_setting_create_spec(&$params) {
 }
 
 /**
- * Returns array of settings matching input parameters
+ * Returns array of settings matching input parameters.
  *
  * @param array $params
- *   Array of one or more valid.
- *                       property_name=>value pairs.
+ *   Array of one or more valid property_name=>value pairs.
  *
  * @return array
  *   Array of matching settings
- *   {@getfields setting_get}
  */
 function civicrm_api3_setting_get($params) {
   $domains = _civicrm_api3_setting_getDomainArray($params);
diff --git a/api/v3/utils.php b/api/v3/utils.php
index 0e1cde62b9..68fd211b8c 100644
--- a/api/v3/utils.php
+++ b/api/v3/utils.php
@@ -146,7 +146,7 @@ function civicrm_api3_create_error($msg, $data = array()) {
 }
 
 /**
- * Format array in result output styple
+ * Format array in result output style.
  *
  * @param array|int $values values generated by API operation (the result)
  * @param array $params