From: eileenmcnaugton <eileen@fuzion.co.nz>
Date: Tue, 4 Aug 2015 01:24:31 +0000 (+1200)
Subject: towards more standardised fn comments:
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=00f8641b80affffeb16ee3199b92002145a666d7;p=civicrm-core.git

towards more standardised fn comments:
---

diff --git a/api/v3/Acl.php b/api/v3/Acl.php
index 3ba5527970..ff02263091 100644
--- a/api/v3/Acl.php
+++ b/api/v3/Acl.php
@@ -37,6 +37,7 @@
  * @param array $params
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_acl_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -48,7 +49,7 @@ function civicrm_api3_acl_create($params) {
  * @param array $params
  *
  * @return array
- *   Array of retrieved Acl property values.
+ *   API result array
  */
 function civicrm_api3_acl_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -60,7 +61,7 @@ function civicrm_api3_acl_get($params) {
  * @param array $params
  *
  * @return array
- *   Array of deleted values.
+ *   API result array
  */
 function civicrm_api3_acl_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/AclRole.php b/api/v3/AclRole.php
index 3fd3827f5c..d141111dd5 100644
--- a/api/v3/AclRole.php
+++ b/api/v3/AclRole.php
@@ -37,6 +37,7 @@
  * @param array $params
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_acl_role_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -48,7 +49,7 @@ function civicrm_api3_acl_role_create($params) {
  * @param array $params
  *
  * @return array
- *   Array of retrieved AclRole property values.
+ *   API result array
  */
 function civicrm_api3_acl_role_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -60,7 +61,7 @@ function civicrm_api3_acl_role_get($params) {
  * @param array $params
  *
  * @return array
- *   Array of deleted values.
+ *   API result array
  */
 function civicrm_api3_acl_role_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/ActionSchedule.php b/api/v3/ActionSchedule.php
index 44152465dc..1d56649110 100644
--- a/api/v3/ActionSchedule.php
+++ b/api/v3/ActionSchedule.php
@@ -37,6 +37,7 @@
  * @param array $params
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_action_schedule_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'ActionSchedule');
diff --git a/api/v3/Activity.php b/api/v3/Activity.php
index 1e6fbf22f4..cd6f3bbee1 100644
--- a/api/v3/Activity.php
+++ b/api/v3/Activity.php
@@ -40,7 +40,7 @@
  *
  * @throws API_Exception
  * @return array
- *   Array containing 'is_error' to denote success or failure and details of the created activity.
+ *   API result array
  */
 function civicrm_api3_activity_create($params) {
 
@@ -230,6 +230,7 @@ function _civicrm_api3_activity_create_spec(&$params) {
  *   Array per getfields documentation.
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_activity_get($params) {
   if (!empty($params['contact_id'])) {
@@ -325,6 +326,7 @@ function _civicrm_api3_activity_get_formatResult($params, $activities) {
  * @throws API_Exception
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_activity_delete($params) {
 
diff --git a/api/v3/ActivityContact.php b/api/v3/ActivityContact.php
index 36904b0de0..addc2008cc 100644
--- a/api/v3/ActivityContact.php
+++ b/api/v3/ActivityContact.php
@@ -62,7 +62,7 @@ function _civicrm_api3_activity_contact_create_spec(&$params) {
  * @param array $params
  *
  * @return array
- *   Api Result
+ *   API result array
  */
 function civicrm_api3_activity_contact_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -75,7 +75,7 @@ function civicrm_api3_activity_contact_delete($params) {
  *   An associative array of name/value pairs.
  *
  * @return array
- *   details of found tags else error
+ *   API result array
  */
 function civicrm_api3_activity_contact_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/Address.php b/api/v3/Address.php
index 7c95d30d38..dbea8c560e 100644
--- a/api/v3/Address.php
+++ b/api/v3/Address.php
@@ -38,6 +38,7 @@
  *   Array per getfields metadata.
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_address_create(&$params) {
   /**
@@ -123,7 +124,7 @@ function _civicrm_api3_address_get_spec(&$params) {
  *   Array per getfields metadata.
  *
  * @return array
- *   api result array
+ *   API result array
  */
 function civicrm_api3_address_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -136,7 +137,7 @@ function civicrm_api3_address_delete($params) {
  *   Array per getfields metadata.
  *
  * @return array
- *   details of found addresses else error
+ *   API result array
  */
 function civicrm_api3_address_get(&$params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params, TRUE, 'Address');
diff --git a/api/v3/CustomSearch.php b/api/v3/CustomSearch.php
index 14e4674672..88dc250efb 100644
--- a/api/v3/CustomSearch.php
+++ b/api/v3/CustomSearch.php
@@ -34,12 +34,10 @@
 /**
  * Retrieve custom searches.
  *
- * FIXME This is a bare-minimum placeholder
- *
  * @param array $params
  *
  * @return array
- *   details of found Option Values
+ *   API result array
  */
 function civicrm_api3_custom_search_get($params) {
   require_once 'api/v3/OptionValue.php';
@@ -55,6 +53,7 @@ function civicrm_api3_custom_search_get($params) {
  * @param array $params
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_custom_search_create($params) {
   require_once 'api/v3/OptionValue.php';
@@ -86,12 +85,12 @@ function _civicrm_api3_custom_search_create_spec(&$params) {
 }
 
 /**
- * Deletes an existing ReportTemplate.
+ * Deletes an existing CustomSearch.
  *
  * @param array $params
  *
  * @return array
- *   Api result
+ *   API result array
  */
 function civicrm_api3_custom_search_delete($params) {
   require_once 'api/v3/OptionValue.php';
diff --git a/api/v3/MembershipBlock.php b/api/v3/MembershipBlock.php
index b4b842c179..5242a50966 100644
--- a/api/v3/MembershipBlock.php
+++ b/api/v3/MembershipBlock.php
@@ -38,7 +38,7 @@
  *   An associative array of name/value property values of MembershipBlock.
  *
  * @return array
- *   newly created or updated membership block property values.
+ *   API result array
  */
 function civicrm_api3_membership_block_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -68,7 +68,7 @@ function _civicrm_api3_membership_block_create_spec(&$params) {
  * {getfields MembershipBlock_get}
  *
  * @return array
- *   api result array of all found membership block property values.
+ *   API result array
  */
 function civicrm_api3_membership_block_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -83,7 +83,7 @@ function civicrm_api3_membership_block_get($params) {
  * @param array $params
  *
  * @return array
- *   api result array
+ *   API result array
  */
 function civicrm_api3_membership_block_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/OpenID.php b/api/v3/OpenID.php
index 47a11e01af..e7b5591de3 100644
--- a/api/v3/OpenID.php
+++ b/api/v3/OpenID.php
@@ -37,6 +37,7 @@
  * @param array $params
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_open_i_d_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -60,7 +61,7 @@ function _civicrm_api3_open_i_d_create_spec(&$params) {
  * @param array $params
  *
  * @return array
- *   API result Array
+ *   API result array
  */
 function civicrm_api3_open_i_d_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -73,7 +74,7 @@ function civicrm_api3_open_i_d_delete($params) {
  *   An associative array of name/value pairs.
  *
  * @return array
- *   details of found OpenID
+ *   API result array
  */
 function civicrm_api3_open_i_d_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/OptionValue.php b/api/v3/OptionValue.php
index 356e5e6389..86b94c21c7 100644
--- a/api/v3/OptionValue.php
+++ b/api/v3/OptionValue.php
@@ -39,7 +39,7 @@
  * @param array $params
  *
  * @return array
- *   Details of found Option Values
+ *   API result array
  */
 function civicrm_api3_option_value_get($params) {
 
@@ -62,6 +62,7 @@ function civicrm_api3_option_value_get($params) {
  *
  * @throws API_Exception
  * @return array
+ *   API result array
  */
 function civicrm_api3_option_value_create($params) {
   $result = _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -100,7 +101,7 @@ function _civicrm_api3_option_value_create_spec(&$params) {
  * @param array $params
  *
  * @return array
- *   Api result
+ *   API result array
  */
 function civicrm_api3_option_value_delete($params) {
   // We will get the option group id before deleting so we can flush pseudoconstants.
diff --git a/api/v3/PaymentProcessor.php b/api/v3/PaymentProcessor.php
index 54ff1db80e..e7718589d9 100644
--- a/api/v3/PaymentProcessor.php
+++ b/api/v3/PaymentProcessor.php
@@ -37,6 +37,7 @@
  * @param array $params
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_payment_processor_create($params) {
   if (empty($params['id']) && empty($params['payment_instrument_id'])) {
@@ -68,7 +69,7 @@ function _civicrm_api3_payment_processor_create_spec(&$params) {
  * @param array $params
  *
  * @return array
- *   API result Array
+ *   API result array
  */
 function civicrm_api3_payment_processor_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -81,7 +82,7 @@ function civicrm_api3_payment_processor_delete($params) {
  *   Array of name/value pairs.
  *
  * @return array
- *   details of found PaymentProcessor
+ *   API result array
  */
 function civicrm_api3_payment_processor_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/Phone/Get.php b/api/v3/Phone/Get.php
index f72075eddd..e47b4b712b 100644
--- a/api/v3/Phone/Get.php
+++ b/api/v3/Phone/Get.php
@@ -42,7 +42,7 @@
  *   Array per getfields metadata.
  *
  * @return array
- *   details of found phones else error
+ *   API result array
  */
 function civicrm_api3_phone_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/ReportInstance.php b/api/v3/ReportInstance.php
index cbb7e8e5b5..66a19b965a 100644
--- a/api/v3/ReportInstance.php
+++ b/api/v3/ReportInstance.php
@@ -38,7 +38,7 @@
  *   Input parameters.
  *
  * @return array
- *   Details of found instances
+ *   API result array
  */
 function civicrm_api3_report_instance_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -50,6 +50,7 @@ function civicrm_api3_report_instance_get($params) {
  * @param array $params
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_report_instance_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -74,7 +75,7 @@ function _civicrm_api3_report_instance_create_spec(&$params) {
  * @param array $params
  *
  * @return array
- *   Api result
+ *   API result array
  */
 function civicrm_api3_report_instance_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/ReportTemplate.php b/api/v3/ReportTemplate.php
index bf0cea90d7..19add4e91d 100644
--- a/api/v3/ReportTemplate.php
+++ b/api/v3/ReportTemplate.php
@@ -34,12 +34,10 @@
 /**
  * Retrieve a report template.
  *
- * FIXME This is a bare-minimum placeholder
- *
  * @param array $params
  *
  * @return array
- *   details of found Option Values
+ *   API result array
  */
 function civicrm_api3_report_template_get($params) {
   require_once 'api/v3/OptionValue.php';
@@ -57,6 +55,7 @@ function civicrm_api3_report_template_get($params) {
  * @param array $params
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_report_template_create($params) {
   require_once 'api/v3/OptionValue.php';
@@ -95,7 +94,7 @@ function _civicrm_api3_report_template_create_spec(&$params) {
  * @param array $params
  *
  * @return array
- *   Api result
+ *   API result array
  */
 function civicrm_api3_report_template_delete($params) {
   require_once 'api/v3/OptionValue.php';
@@ -109,7 +108,7 @@ function civicrm_api3_report_template_delete($params) {
  *   Input parameters.
  *
  * @return array
- *   details of found instances
+ *   API result array
  */
 function civicrm_api3_report_template_getrows($params) {
   civicrm_api3_verify_one_mandatory($params, NULL, array('report_id', 'instance_id'));
@@ -177,6 +176,7 @@ function _civicrm_api3_report_template_getrows($params) {
  * @param array $params
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_report_template_getstatistics($params) {
   list($rows, $reportInstance, $metadata) = _civicrm_api3_report_template_getrows($params);
diff --git a/api/v3/Tag.php b/api/v3/Tag.php
index 21459c5dba..2ffe781ada 100644
--- a/api/v3/Tag.php
+++ b/api/v3/Tag.php
@@ -45,6 +45,7 @@
  *   Array per getfields metadata.
  *
  * @return array
+ *   API result array
  */
 function civicrm_api3_tag_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -86,7 +87,7 @@ function civicrm_api3_tag_delete($params) {
  *   Array per getfields metadata.
  *
  * @return array
- *   details of found tags else error
+ *   API result array
  */
 function civicrm_api3_tag_get($params) {
 
diff --git a/api/v3/Website.php b/api/v3/Website.php
index c808f580c4..5f2776c4be 100644
--- a/api/v3/Website.php
+++ b/api/v3/Website.php
@@ -37,7 +37,7 @@
  * @param array $params
  *
  * @return array
- *   API result array.
+ *   API result array
  * @todo convert to using basic create - BAO function non-std
  */
 function civicrm_api3_website_create($params) {
@@ -69,7 +69,7 @@ function _civicrm_api3_website_create_spec(&$params) {
  * @param array $params
  *
  * @return array
- *   API result
+ *   API result array
  * @throws \API_Exception
  */
 function civicrm_api3_website_delete($params) {
@@ -95,7 +95,7 @@ function civicrm_api3_website_delete($params) {
  * @param array $params
  *
  * @return array
- *   details of found websites
+ *   API result array
  */
 function civicrm_api3_website_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params, TRUE, 'Website');