Api docblock cleanup.

[civicrm-core.git] / api / v3 / Job.php

diff --git a/api/v3/Job.php b/api/v3/Job.php
index 93edc014001df4e9f6e1f5dc44b84497388573d4..1f554eda0ff58350104bfde214d9e63ec5722914 100644 (file)
--- a/api/v3/Job.php
+++ b/api/v3/Job.php
@@ -1,6 +1,4 @@
 <?php
-// $Id$
-
 /*
  +--------------------------------------------------------------------+
  | CiviCRM version 4.6                                                |
@@ -28,13 +26,9 @@
  */
 
 /**
- * new version of civicrm APIs. See blog post at
- * http://civicrm.org/node/131
+ * This api is used for triggering scheduled "cron" jobs.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Job
- * @copyright CiviCRM LLC (c) 2004-2014
- * $Id: Contact.php 30879 2010-11-22 15:45:55Z shot $
  */
 
 /**
@@ -43,7 +37,7 @@
  * The metadata is used for setting defaults, documentation & validation.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_job_create_spec(&$params) {
   $params['run_frequency']['api.required'] = 1;
@@ -100,20 +94,19 @@ function civicrm_api3_job_delete($params) {
  *   API Result Array
  */
 function civicrm_api3_job_execute($params) {
-  // @noinspection PhpUnusedParameterInspection
 
   $facility = new CRM_Core_JobManager();
   $facility->execute(FALSE);
 
-  // always creates success - results are handled elsewhere
-  return civicrm_api3_create_success();
+  // Always creates success - results are handled elsewhere.
+  return civicrm_api3_create_success(1, $params);
 }
 
 /**
  * Adjust Metadata for Execute action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_job_execute_spec(&$params) {
 }
@@ -190,7 +183,7 @@ function civicrm_api3_job_send_reminder($params) {
  * The metadata is used for setting defaults, documentation & validation.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_job_send_reminder(&$params) {
   //@todo this function will now take all fields in action_schedule as params
@@ -259,7 +252,7 @@ function civicrm_api3_job_update_greeting($params) {
  * The metadata is used for setting defaults, documentation & validation.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_job_update_greeting_spec(&$params) {
   $params['ct'] = array(
@@ -400,8 +393,9 @@ function civicrm_api3_job_process_participant($params) {
 
 
 /**
- * This api checks and updates the status of all membership records for a given domain using the calc_membership_status and
- * update_contact_membership APIs.
+ * This api checks and updates the status of all membership records for a given domain.
+ *
+ * The function uses the calc_membership_status and update_contact_membership APIs.
  *
  * IMPORTANT:
  * Sending renewal reminders has been migrated from this job to the Scheduled Reminders function as of 4.3.
@@ -422,7 +416,7 @@ function civicrm_api3_job_process_membership($params) {
   $lock->release();
 
   if ($result['is_error'] == 0) {
-    return civicrm_api3_create_success($result['messages']);
+    return civicrm_api3_create_success($result['messages'], $params);
   }
   else {
     return civicrm_api3_create_error($result['messages']);
@@ -457,7 +451,6 @@ function civicrm_api3_job_process_respondent($params) {
  *
  * @return array
  *   API Result Array
- *
  */
 function civicrm_api3_job_process_batch_merge($params) {
   $rgid = CRM_Utils_Array::value('rgid', $params);
@@ -477,6 +470,8 @@ function civicrm_api3_job_process_batch_merge($params) {
 }
 
 /**
+ * Metadata for batch merge function.
+ *
  * @param $params
  */
 function _civicrm_api3_job_process_batch_merge_spec(&$params) {
@@ -501,14 +496,14 @@ function _civicrm_api3_job_process_batch_merge_spec(&$params) {
 }
 
 /**
- * Runs handlePaymentCron method in the specified payment processor
+ * Runs handlePaymentCron method in the specified payment processor.
  *
  * @param array $params
  *   Input parameters.
  *
- * Expected @params array keys are:
+ * Expected @params array keys are: INCORRECTLY DOCUMENTED AND SHOULD BE IN THE _spec function
+ * for retrieval via getfields.
  * {string  'processor_name' - the name of the payment processor, eg: Sagepay}
- *
  */
 function civicrm_api3_job_run_payment_cron($params) {
 
@@ -536,7 +531,9 @@ function civicrm_api3_job_run_payment_cron($params) {
 }
 
 /**
- * This api cleans up all the old session entries and temp tables. We recommend that sites run this on an hourly basis
+ * This api cleans up all the old session entries and temp tables.
+ *
+ * We recommend that sites run this on an hourly basis.
  *
  * @param array $params
  *   Sends in various config parameters to decide what needs to be cleaned.
@@ -568,26 +565,30 @@ function civicrm_api3_job_cleanup($params) {
 
 /**
  * Set expired relationships to disabled.
- * @param $params
+ *
+ * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */
 function civicrm_api3_job_disable_expired_relationships($params) {
-  /** @noinspection PhpUnusedParameterInspection */
   $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships();
   if (!$result) {
     throw new API_Exception('Failed to disable all expired relationships.');
   }
-  return civicrm_api3_create_success();
+  return civicrm_api3_create_success(1, $params);
 }
 
 /**
- * This api reloads all the smart groups. If the org has a large number of smart groups
- * it is recommended that they use the limit clause to limit the number of smart groups
- * evaluated on a per job basis. Might also help to increase the smartGroupCacheTimeout
- * and use the cache
+ * This api reloads all the smart groups.
+ *
+ * If the org has a large number of smart groups it is recommended that they use the limit clause
+ * to limit the number of smart groups evaluated on a per job basis.
+ *
+ * Might also help to increase the smartGroupCacheTimeout and use the cache.
  *
  * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */