From: Eileen McNaughton <eileen@fuzion.co.nz>
Date: Mon, 2 Feb 2015 07:05:45 +0000 (+1300)
Subject: api comment improvements
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=22242c8734d20099d181a6a7f28e982adfd96267;p=civicrm-core.git

api comment improvements
---

diff --git a/api/Exception.php b/api/Exception.php
index 8ec7eb3ae6..517755bae6 100644
--- a/api/Exception.php
+++ b/api/Exception.php
@@ -51,7 +51,8 @@ class API_Exception extends Exception {
   }
 
   /**
-   * custom string representation of object
+   * Custom string representation of object.
+   *
    * @return string
    */
   public function __toString() {
@@ -106,7 +107,8 @@ class CiviCRM_API3_Exception extends Exception {
   }
 
   /**
-   * custom string representation of object
+   * Custom string representation of object.
+   *
    * @return string
    */
   public function __toString() {
@@ -114,6 +116,8 @@ class CiviCRM_API3_Exception extends Exception {
   }
 
   /**
+   * Get error code.
+   *
    * @return mixed
    */
   public function getErrorCode() {
diff --git a/api/api.php b/api/api.php
index 5b0a76c1d6..c9b5fbe564 100644
--- a/api/api.php
+++ b/api/api.php
@@ -107,6 +107,8 @@ function civicrm_error($result) {
 }
 
 /**
+ * Get camel case version of entity or action name.
+ *
  * @param $entity
  *
  * @return string
@@ -116,7 +118,9 @@ function _civicrm_api_get_camel_name($entity) {
 }
 
 /**
- * Swap out any $values vars - ie. the value after $value is swapped for the parent $result
+ * Swap out any $values vars.
+ *
+ * Ie. the value after $value is swapped for the parent $result
  * 'activity_type_id' => '$value.testfield',
  * 'tag_id'  => '$value.api.tag.create.id',
  * 'tag1_id' => '$value.api.entity.create.0.id'
diff --git a/api/v3/ActivityType.php b/api/v3/ActivityType.php
index 6d2b4965a3..5affa0690c 100644
--- a/api/v3/ActivityType.php
+++ b/api/v3/ActivityType.php
@@ -106,7 +106,7 @@ function _civicrm_api3_activity_type_create_spec(&$params) {
  *
  * @param array $params
  *   Array including id of activity_type to delete.
-
+ *
  * @return array
  *   API result array
  *
diff --git a/api/v3/Address.php b/api/v3/Address.php
index 463490bd18..472e85fc0b 100644
--- a/api/v3/Address.php
+++ b/api/v3/Address.php
@@ -36,7 +36,7 @@
  */
 
 /**
- *  Add an Address for a contact.
+ * Add an Address for a contact.
  *
  * @param array $params
  *   Array per getfields metadata.
diff --git a/api/v3/Attachment.php b/api/v3/Attachment.php
index 70f9d74ae7..a77cc1adaf 100644
--- a/api/v3/Attachment.php
+++ b/api/v3/Attachment.php
@@ -70,7 +70,7 @@
  */
 
 /**
- * Adjust metadata for "create" action
+ * Adjust metadata for "create" action.
  *
  * @param array $spec
  *   List of fields.
@@ -85,9 +85,10 @@ function _civicrm_api3_attachment_create_spec(&$spec) {
 }
 
 /**
- * Create an attachment
+ * Create an attachment.
  *
  * @param array $params
+ *
  * @return array
  *   Array of newly created file property values.
  * @throws API_Exception validation errors
@@ -152,7 +153,7 @@ function civicrm_api3_attachment_create($params) {
 }
 
 /**
- * Adjust metadata for "create" action
+ * Adjust metadata for get action.
  *
  * @param array $spec
  *   List of fields.
@@ -179,6 +180,8 @@ function civicrm_api3_attachment_get($params) {
 }
 
 /**
+ * Adjust metadata for attachment delete action.
+ *
  * @param $spec
  */
 function _civicrm_api3_attachment_delete_spec(&$spec) {
@@ -191,7 +194,10 @@ function _civicrm_api3_attachment_delete_spec(&$spec) {
 }
 
 /**
+ * Delete attachment.
+ *
  * @param array $params
+ *
  * @return array
  * @throws API_Exception
  */
@@ -235,6 +241,8 @@ function civicrm_api3_attachment_delete($params) {
 }
 
 /**
+ * Attachment find helper.
+ *
  * @param array $params
  * @param int|null $id the user-supplied ID of the attachment record
  * @param array $file
@@ -242,6 +250,7 @@ function civicrm_api3_attachment_delete($params) {
  * @param array $entityFile
  *   The user-supplied values of the entity-file (entity_table, entity_id).
  * @param bool $isTrusted
+ *
  * @return CRM_Core_DAO
  * @throws API_Exception
  */
@@ -267,14 +276,14 @@ function __civicrm_api3_attachment_find($params, $id, $file, $entityFile, $isTru
   if ($id) {
     $select->where('cf.id = #id', array('#id' => $id));
   }
-  // recall: $file is filtered by parse_params
+  // Recall: $file is filtered by parse_params.
   foreach ($file as $key => $value) {
     $select->where('cf.!field = @value', array(
       '!field' => $key,
       '@value' => $value,
     ));
   }
-  // recall: $entityFile is filtered by parse_params
+  // Recall: $entityFile is filtered by parse_params.
   foreach ($entityFile as $key => $value) {
     $select->where('cef.!field = @value', array(
       '!field' => $key,
@@ -295,7 +304,10 @@ function __civicrm_api3_attachment_find($params, $id, $file, $entityFile, $isTru
 }
 
 /**
+ * Attachment parsing helper.
+ *
  * @param array $params
+ *
  * @return array (0 => int $id, 1 => array $file, 2 => array $entityFile, 3 => string $name, 4 => string $content,
  *    5 => string $moveFile, 6 => $isTrusted, 7 => bool $returnContent)
  *    - array $file: whitelisted fields that can pass through directly to civicrm_file
@@ -357,6 +369,8 @@ function _civicrm_api3_attachment_parse_params($params) {
 }
 
 /**
+ * Attachment result formatting helper.
+ *
  * @param CRM_Core_DAO_File $fileDao
  *   Maybe "File" or "File JOIN EntityFile".
  * @param CRM_Core_DAO_EntityFile $entityFileDao
@@ -398,6 +412,8 @@ function _civicrm_api3_attachment_format_result($fileDao, $entityFileDao, $retur
 }
 
 /**
+ * Attachment getfields helper.
+ *
  * @return array
  *   list of fields (indexed by name)
  */
diff --git a/api/v3/Constant.php b/api/v3/Constant.php
index 5e379c7e54..ac42c16533 100644
--- a/api/v3/Constant.php
+++ b/api/v3/Constant.php
@@ -93,9 +93,8 @@ function _civicrm_api3_constant_deprecation() {
  *    <li>worldRegion</li>
  *    <li>wysiwygEditor</li>
  *  </ul>
+ *
  * @return array
- * @example ConstantGet.php
- *  {@getfields constant_get}
  */
 function civicrm_api3_constant_get($params) {
 
diff --git a/api/v3/Contact.php b/api/v3/Contact.php
index 4a33a5fe5b..38b7b31ad5 100644
--- a/api/v3/Contact.php
+++ b/api/v3/Contact.php
@@ -46,7 +46,6 @@
  *
  * @return array
  *   API Result Array
- *
  */
 function civicrm_api3_contact_create($params) {
 
@@ -417,7 +416,6 @@ function _civicrm_api3_contact_update($params, $contactID = NULL) {
  *   Array per getfields metadata.
  *
  * @throws API_Exception
- *
  */
 function _civicrm_api3_greeting_format_params($params) {
   $greetingParams = array('', '_id', '_custom');
@@ -428,7 +426,7 @@ function _civicrm_api3_greeting_format_params($params) {
     }
 
     $formatParams = FALSE;
-    // unset display value from params.
+    // Unset display value from params.
     if (isset($params["{$key}{$greeting}_display"])) {
       unset($params["{$key}{$greeting}_display"]);
     }
@@ -951,6 +949,8 @@ WHERE     $whereClause
 
 
 /**
+ * Get parameters for getlist function.
+ *
  * @see _civicrm_api3_generic_getlist_params
  *
  * @param array $request
@@ -994,6 +994,8 @@ function _civicrm_api3_contact_getlist_params(&$request) {
 }
 
 /**
+ * Get output for getlist function.
+ *
  * @see _civicrm_api3_generic_getlist_output
  *
  * @param array $result
diff --git a/api/v3/Dashboard.php b/api/v3/Dashboard.php
index 9cc600bcda..2b820c68e4 100644
--- a/api/v3/Dashboard.php
+++ b/api/v3/Dashboard.php
@@ -58,10 +58,13 @@ function civicrm_api3_dashboard_create($params) {
 }
 
 /**
- * Specify Meta data for create. Note that this data is retrievable via the getfields function
+ * Specify Meta data for create.
+ *
+ * Note that this data is retrievable via the getfields function
  * and is used for pre-filling defaults and ensuring mandatory requirements are met.
+ *
  * @param array $params
- *   (reference) array of parameters determined by getfields.
+ *   array of parameters determined by getfields.
  */
 function _civicrm_api3_dashboard_create_spec(&$params) {
   unset($params['version']);
diff --git a/api/v3/Extension.php b/api/v3/Extension.php
index 6fd4a65a90..80fb704ec3 100644
--- a/api/v3/Extension.php
+++ b/api/v3/Extension.php
@@ -142,7 +142,7 @@ function civicrm_api3_extension_disable($params) {
 }
 
 /**
- * Uninstall an extension
+ * Uninstall an extension,
  *
  * @param array $params
  *   Input parameters.
diff --git a/api/v3/Group.php b/api/v3/Group.php
index d4fa3c26b3..0bbc164041 100644
--- a/api/v3/Group.php
+++ b/api/v3/Group.php
@@ -35,12 +35,7 @@
  */
 
 /**
- * create/update group
- *
- * This API is used to create new group or update any of the existing
- * In case of updating existing group, id of that particular group must
- * be in $params array. Either id or name is required field in the
- * $params array
+ * Create/update group.
  *
  * @param array $params
  *   Associative array of property.
@@ -48,8 +43,6 @@
  *
  * @return array
  *   API result array
- * @example GroupCreate.php
- * {@getfields group_create}
  */
 function civicrm_api3_group_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'Group');
@@ -69,7 +62,7 @@ function _civicrm_api3_group_create_spec(&$params) {
 }
 
 /**
- * Returns array of groups  matching a set of one or more group properties
+ * Returns array of groups matching a set of one or more group properties.
  *
  * @param array $params
  *   Array of one or more valid.
@@ -78,8 +71,6 @@ function _civicrm_api3_group_create_spec(&$params) {
  *
  * @return array
  *   Array of matching groups
- * @example GroupGet.php
- * {@getfields group_get}
  */
 function civicrm_api3_group_get($params) {
   $options = _civicrm_api3_get_options_from_params($params, TRUE, 'group', 'get');
@@ -95,10 +86,7 @@ function civicrm_api3_group_get($params) {
 }
 
 /**
- * delete an existing group
- *
- * This method is used to delete any existing group. id of the group
- * to be deleted is required field in $params array
+ * Delete an existing group.
  *
  * @param array $params
  *   Array containing id of the group.
@@ -106,9 +94,6 @@ function civicrm_api3_group_get($params) {
  *
  * @return array
  *   API result array
- * @example GroupDelete.php
- * {@getfields group_delete}
- *
  */
 function civicrm_api3_group_delete($params) {
 
diff --git a/api/v3/GroupContact.php b/api/v3/GroupContact.php
index 946df5baf5..6afb6c26e8 100644
--- a/api/v3/GroupContact.php
+++ b/api/v3/GroupContact.php
@@ -35,19 +35,19 @@
  *
  * @copyright CiviCRM LLC (c) 2004-2014
  * @version $Id: GroupContact.php 30171 2010-10-14 09:11:27Z mover $
- *
  */
 
 
 /**
- * This API will give list of the groups for particular contact
- * Particular status can be sent in params array
+ * This API will give list of the groups for particular contact.
+ *
+ * Particular status can be sent in params array.
+ *
  * If no status mentioned in params, by default 'added' will be used
  * to fetch the records
  *
  * @param array $params
  *   Name value pair of contact information.
- * {@getfields GroupContact_get}
  *
  * @return array
  *   list of groups, given contact subsribed to
@@ -70,7 +70,8 @@ function civicrm_api3_group_contact_get($params) {
 }
 
 /**
- * Add contact(s) to group(s)
+ * Add contact(s) to group(s).
+ *
  * @param array $params
  *   Input parameters.
  *
@@ -80,7 +81,6 @@ function civicrm_api3_group_contact_get($params) {
  * "contact_id.1" etc. (optional) : another contact to add<br>
  * "group_id.1" etc. (optional) : additional group to add contact(s) to<br>
  * "status" (optional) : one of "Added", "Pending" or "Removed" (default is "Added")
- * {@example GroupContactCreate.php 0}
  *
  * @return array
  *   Information about operation results
@@ -121,11 +121,12 @@ function civicrm_api3_group_contact_create($params) {
 }
 
 /**
+ * Delete group contact record.
  *
  * @param array $params
  *
  * @return array
- *   <type>
+ *
  * @deprecated
  */
 function civicrm_api3_group_contact_delete($params) {
diff --git a/api/v3/GroupNesting.php b/api/v3/GroupNesting.php
index 65640adcb4..9897ea4699 100644
--- a/api/v3/GroupNesting.php
+++ b/api/v3/GroupNesting.php
@@ -51,6 +51,7 @@ function civicrm_api3_group_nesting_get($params) {
 
 /**
  * Creates group nesting record for given parent and child id.
+ *
  * Parent and child groups need to exist.
  *
  * @param array $params
diff --git a/api/v3/LineItem.php b/api/v3/LineItem.php
index 8e3f152c1e..28214af7f5 100644
--- a/api/v3/LineItem.php
+++ b/api/v3/LineItem.php
@@ -27,7 +27,7 @@
 
 
 /**
- * File for the CiviCRM APIv3 group functions
+ * File for the CiviCRM APIv3 line item functions
  *
  * @package CiviCRM_APIv3
  * @subpackage API_LineItem
@@ -35,7 +35,7 @@
  */
 
 /**
- * Create or update a line_item
+ * Create or update a line_item.
  *
  * @param array $params
  *   Associative array of property.
@@ -81,7 +81,7 @@ function civicrm_api3_line_item_get($params) {
 }
 
 /**
- * delete an existing line_item
+ * Delete an existing line_item.
  *
  * This method is used to delete any existing line_item. id of the group
  * to be deleted is required field in $params array
diff --git a/api/v3/Mailing.php b/api/v3/Mailing.php
index 432a48dfb6..4d9a89ffef 100755
--- a/api/v3/Mailing.php
+++ b/api/v3/Mailing.php
@@ -39,6 +39,7 @@
  * Handle a create event.
  *
  * @param array $params
+ *
  * @return array API Success Array
  *    API Success Array
  * @throws \API_Exception
@@ -64,7 +65,10 @@ function civicrm_api3_mailing_create($params) {
 }
 
 /**
+ * Get mailing token.
+ *
  * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */
@@ -131,6 +135,8 @@ function civicrm_api3_mailing_get($params) {
 }
 
 /**
+ * Adjust metadata for mailing submit api function.
+ *
  * @param array $spec
  */
 function _civicrm_api3_mailing_submit_spec(&$spec) {
@@ -144,7 +150,10 @@ function _civicrm_api3_mailing_submit_spec(&$spec) {
 }
 
 /**
+ * Mailing submit.
+ *
  * @param array $params
+ *
  * @return array
  * @throws API_Exception
  */
@@ -210,7 +219,7 @@ function civicrm_api3_mailing_event_bounce($params) {
 }
 
 /**
- * Adjust Metadata for bounce_spec action
+ * Adjust Metadata for bounce_spec action.
  *
  * The metadata is used for setting defaults, documentation & validation.
  *
@@ -229,7 +238,8 @@ function _civicrm_api3_mailing_event_bounce_spec(&$params) {
 }
 
 /**
- * Handle a confirm event
+ * Handle a confirm event.
+ *
  * @deprecated
  *
  * @param array $params
@@ -250,7 +260,7 @@ function _civicrm_api3_mailing_deprecation() {
 }
 
 /**
- * Handle a reply event
+ * Handle a reply event.
  *
  * @param array $params
  *
@@ -277,7 +287,7 @@ function civicrm_api3_mailing_event_reply($params) {
 }
 
 /**
- * Adjust Metadata for event_reply action
+ * Adjust Metadata for event_reply action.
  *
  * The metadata is used for setting defaults, documentation & validation.
  *
@@ -296,7 +306,7 @@ function _civicrm_api3_mailing_event_reply_spec(&$params) {
 }
 
 /**
- * Handle a forward event
+ * Handle a forward event.
  *
  * @param array $params
  *
@@ -320,7 +330,7 @@ function civicrm_api3_mailing_event_forward($params) {
 }
 
 /**
- * Adjust Metadata for event_forward action
+ * Adjust Metadata for event_forward action.
  *
  * The metadata is used for setting defaults, documentation & validation.
  *
@@ -339,7 +349,7 @@ function _civicrm_api3_mailing_event_forward_spec(&$params) {
 }
 
 /**
- * Handle a click event
+ * Handle a click event.
  *
  * @param array $params
  *
@@ -365,7 +375,7 @@ function civicrm_api3_mailing_event_click($params) {
 }
 
 /**
- * Handle an open event
+ * Handle an open event.
  *
  * @param array $params
  *
@@ -390,7 +400,11 @@ function civicrm_api3_mailing_event_open($params) {
 }
 
 /**
+ * Preview mailing.
+ *
  * @param array $params
+ *   Array per getfields metadata.
+ *
  * @return array
  * @throws \API_Exception
  */
@@ -439,6 +453,8 @@ function civicrm_api3_mailing_preview($params) {
 }
 
 /**
+ * Adjust metadata for send test function.
+ *
  * @param array $spec
  */
 function _civicrm_api3_mailing_send_test_spec(&$spec) {
@@ -447,7 +463,10 @@ function _civicrm_api3_mailing_send_test_spec(&$spec) {
 }
 
 /**
+ * Send test mailing.
+ *
  * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  * @throws \CiviCRM_API3_Exception
@@ -536,7 +555,7 @@ function civicrm_api3_mailing_send_test($params) {
 }
 
 /**
- * Adjust Metadata for send_mail action
+ * Adjust Metadata for send_mail action.
  *
  * The metadata is used for setting defaults, documentation & validation.
  *
@@ -549,7 +568,10 @@ function _civicrm_api3_mailing_stats_spec(&$params) {
 }
 
 /**
+ * Function which needs to be explained.
+ *
  * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */
@@ -608,10 +630,13 @@ function civicrm_api3_mailing_stats($params) {
 }
 
 /**
- * Fix the reset dates on the email record based on when a mail was last delivered
+ * 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 array $params
+ *
  * @return array
  */
 function civicrm_api3_mailing_update_email_resetdate($params) {
diff --git a/api/v3/MailingEventSubscribe.php b/api/v3/MailingEventSubscribe.php
index 82cbf2509b..ea3c57326d 100644
--- a/api/v3/MailingEventSubscribe.php
+++ b/api/v3/MailingEventSubscribe.php
@@ -33,20 +33,17 @@
  * @subpackage API_MailerGroup
  * @copyright CiviCRM LLC (c) 2004-2014
  * $Id$
- *
  */
 
 /**
- * Subscribe from mailing group
+ * Subscribe from mailing group.
  *
  * @param array $params
- *   Associative array of property.
- *                       name/value pairs to insert in new 'survey'
+ *   Array per getfields metadata.
  *
  * @throws API_Exception
  * @return array
  *   api result array
- *   {@getfields mailing_event_subscribe_create}
  */
 function civicrm_api3_mailing_event_subscribe_create($params) {
   $email      = $params['email'];
diff --git a/api/v3/MailingEventUnsubscribe.php b/api/v3/MailingEventUnsubscribe.php
index 6404877fdc..1ce29ae3e4 100644
--- a/api/v3/MailingEventUnsubscribe.php
+++ b/api/v3/MailingEventUnsubscribe.php
@@ -33,17 +33,16 @@
  * @subpackage API_MailerGroup
  * @copyright CiviCRM LLC (c) 2004-2014
  * $Id$
- *
  */
 
 /**
- * Unsubscribe from mailing group
+ * Unsubscribe from mailing group.
  *
  * @param array $params
- *   Associative array of property.
- *                       name/value pairs to insert in new 'survey'
+ *   Array per getfields metadata.
  *
- * @return array  api result array {@getfields mailing_event_unsubscribe_create}
+ * @return array
+ *  Api result array
  */
 function civicrm_api3_mailing_event_unsubscribe_create($params) {
 
diff --git a/api/v3/MailingGroup.php b/api/v3/MailingGroup.php
index 407f0cafd5..8eb6673bd9 100644
--- a/api/v3/MailingGroup.php
+++ b/api/v3/MailingGroup.php
@@ -33,10 +33,11 @@
  * @subpackage API_MailerGroup
  * @copyright CiviCRM LLC (c) 2004-2014
  * $Id$
- *
  */
 
 /**
+ * Declare deprecated functions.
+ *
  * @deprecated api notice
  * @return string
  *   to indicate this entire api entity is deprecated
@@ -115,7 +116,10 @@ function civicrm_api3_mailing_group_get($params) {
 }
 
 /**
+ * Delete mailing group.
+ *
  * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */
@@ -125,6 +129,7 @@ function civicrm_api3_mailing_group_delete($params) {
 
 /**
  * @param array $params
+ *
  * @return array
  */
 function civicrm_api3_mailing_group_getfields($params) {
diff --git a/api/v3/MailingJob.php b/api/v3/MailingJob.php
index 617d9339a3..a8604a3efb 100644
--- a/api/v3/MailingJob.php
+++ b/api/v3/MailingJob.php
@@ -33,12 +33,13 @@
  * @subpackage API_Mailing
  * @copyright CiviCRM LLC (c) 2004-2014
  * $Id$
- *
  */
 
 /**
  * Handle creation of a Mailing Job for a Mailing.
+ *
  * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */
@@ -61,14 +62,13 @@ function _civicrm_api3_mailing_job_create_spec(&$params) {
 }
 
 /**
- * Returns array of Mailing Jobs  matching a set of one or more group properties
+ * Returns array of Mailing Jobs matching a set of one or more group properties.
  *
  * @param array $params
  *   Array of one or more valid.
  *
  * @return array
  *   API return Array of matching mailing jobs.
- *   {@getfields mailing_job_get}
  */
 function civicrm_api3_mailing_job_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -76,7 +76,9 @@ function civicrm_api3_mailing_job_get($params) {
 
 /**
  * Handle deletion of a Mailing Job for a Mailing.
+ *
  * @param array $params
+ *
  * @return array
  * @throws \API_Exception
  */
diff --git a/api/v3/MembershipStatus.php b/api/v3/MembershipStatus.php
index 9be467237d..3738d41ee4 100644
--- a/api/v3/MembershipStatus.php
+++ b/api/v3/MembershipStatus.php
@@ -112,11 +112,12 @@ function &civicrm_api3_membership_status_update($params) {
 }
 
 /**
- * Deletes an existing membership status
+ * Deletes an existing membership status.
  *
  * This API is used for deleting a membership status
  *
  * @param array $params
+ *
  * @return array
  */
 function civicrm_api3_membership_status_delete($params) {
@@ -126,7 +127,7 @@ function civicrm_api3_membership_status_delete($params) {
 }
 
 /**
- * Derives the Membership Status of a given Membership Reocrd
+ * Derives the Membership Status of a given Membership Record.
  *
  * This API is used for deriving Membership Status of a given Membership
  * record using the rules encoded in the membership_status table.
@@ -137,7 +138,6 @@ function civicrm_api3_membership_status_delete($params) {
  *
  * @return array
  *   Array of status id and status name
- * @public
  */
 function civicrm_api3_membership_status_calc($membershipParams) {
   if (!($membershipID = CRM_Utils_Array::value('membership_id', $membershipParams))) {
diff --git a/api/v3/Note.php b/api/v3/Note.php
index 20e6cb40e4..0322f11079 100644
--- a/api/v3/Note.php
+++ b/api/v3/Note.php
@@ -68,15 +68,14 @@ function _civicrm_api3_note_create_spec(&$params) {
 }
 
 /**
- * Deletes an existing note
+ * Deletes an existing note.
  *
  * This API is used for deleting a note
  *
  * @param array $params
  *   Including id of the note to be deleted.
- * {@getfields note_delete}
  *
- * @return null
+ * @return array
  */
 function civicrm_api3_note_delete($params) {
 
@@ -100,7 +99,7 @@ function civicrm_api3_note_get($params) {
 }
 
 /**
- * Adjust Metadata for Get action
+ * Adjust Metadata for Get action.
  *
  * The metadata is used for setting defaults, documentation & validation.
  *
@@ -112,10 +111,10 @@ function _civicrm_api3_note_get_spec(&$params) {
 }
 
 /**
- * Get all descendents of given note
+ * Get all descendants of given note.
  *
  * @param array $params
- *   Associative array; only required 'id' parameter is used.
+ *   array; only required 'id' parameter is used.
  *
  * @return array
  *   Nested associative array beginning with direct children of given note.
diff --git a/api/v3/Participant.php b/api/v3/Participant.php
index 0556d4f2c4..5a5ec3bf07 100644
--- a/api/v3/Participant.php
+++ b/api/v3/Participant.php
@@ -68,7 +68,7 @@ function civicrm_api3_participant_create($params) {
 }
 
 /**
- * Create a default participant line item
+ * Create a default participant line item.
  *
  * @todo this should be done in the BAO not the api
  *
diff --git a/api/v3/ParticipantPayment.php b/api/v3/ParticipantPayment.php
index 007254fee1..c2f36f5b28 100644
--- a/api/v3/ParticipantPayment.php
+++ b/api/v3/ParticipantPayment.php
@@ -33,7 +33,6 @@
  *
  * @copyright CiviCRM LLC (c) 2004-2014
  * @version $Id: Participant.php 30486 2010-11-02 16:12:09Z shot $
- *
  */
 
 /**
@@ -76,16 +75,12 @@ function _civicrm_api3_participant_payment_create_spec(&$params) {
 }
 
 /**
- * Deletes an existing Participant Payment
- *
- * This API is used for deleting a Participant Payment
+ * Deletes an existing Participant Payment.
  *
  * @param array $params
  *
  * @return array
  *   API result
- * @example ParticipantPaymentDelete.php
- * {@getfields ParticipantPayment_delete}
  */
 function civicrm_api3_participant_payment_delete($params) {
   $participant = new CRM_Event_BAO_ParticipantPayment();
@@ -93,16 +88,13 @@ function civicrm_api3_participant_payment_delete($params) {
 }
 
 /**
- * Retrieve one / all contribution(s) / participant(s) linked to a
- * contribution.
+ * Retrieve one or more participant payment records.
  *
  * @param array $params
  *   Input parameters.
  *
  * @return array
  *   array of properties, if error an array with an error id and error message
- * @example ParticipantPaymentGet
- * {@getfields ParticipantPayment_get}
  */
 function civicrm_api3_participant_payment_get($params) {
   return _civicrm_api3_basic_get('CRM_Event_DAO_ParticipantPayment', $params);
diff --git a/api/v3/PaymentProcessorType.php b/api/v3/PaymentProcessorType.php
index 708460ac53..138c42d457 100644
--- a/api/v3/PaymentProcessorType.php
+++ b/api/v3/PaymentProcessorType.php
@@ -33,15 +33,10 @@
  * @subpackage API_Contact
  * @copyright CiviCRM LLC (c) 2004-2014
  * $Id: PaymentProcessorType.php 30415 2010-10-29 12:02:47Z shot $
- *
- */
-
-/**
- * Include common API util functions
  */
 
 /**
- * create payment_processor type
+ * Create payment_processor type.
  *
  * @param array $params
  *   Associative array of property name/value pairs to insert in new payment_processor type.
@@ -90,7 +85,7 @@ function civicrm_api3_payment_processor_type_get($params) {
 }
 
 /**
- * Delete a payment_processor type delete
+ * Delete a payment_processor type delete.
  *
  * @param array $params
  *
diff --git a/api/v3/Phone.php b/api/v3/Phone.php
index 6939e3cf2f..8e30768cf5 100644
--- a/api/v3/Phone.php
+++ b/api/v3/Phone.php
@@ -36,13 +36,10 @@
  */
 
 /**
- *  Add an Phone for a contact
- *
- * Allowed @params array keys are:
- * {@getfields phone_create}
- * @example PhoneCreate.php
+ * Add an Phone for a contact.
  *
  * @param array $params
+ *   Array per getfields metadata.
  *
  * @return array
  *   Array of newly created phone property values.
@@ -67,14 +64,13 @@ function _civicrm_api3_phone_create_spec(&$params) {
 }
 
 /**
- * Deletes an existing Phone
+ * Delete an existing Phone.
  *
  * @param array $params
+ *   Array per getfields metadata.
  *
  * @return array
  *   Api Result
- *   {@getfields phone_delete}
- * @example PhoneDelete.php
  */
 function civicrm_api3_phone_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/Pledge.php b/api/v3/Pledge.php
index f03aec7373..dcbcf40335 100644
--- a/api/v3/Pledge.php
+++ b/api/v3/Pledge.php
@@ -36,15 +36,10 @@
  */
 
 /**
- * Include utility functions.
- */
-
-/**
- * Creates or updates an Pledge.
+ * Create or updates an Pledge.
  *
  * @return array
  *   Array containing 'is_error' to denote success or failure and details of the created pledge
- *
  */
 function civicrm_api3_pledge_create($params) {
   _civicrm_api3_pledge_format_params($params, TRUE);
@@ -55,15 +50,12 @@ function civicrm_api3_pledge_create($params) {
 }
 
 /**
- * Delete a pledge
+ * Delete a pledge.
  *
  * @param array $params
  *   Array included 'pledge_id' of pledge to delete.
  *
- * @return bool
- *   true if success, else false
- *   {@getfields pledge_delete}
- * @example PledgeDelete.php
+ * @return array
  */
 function civicrm_api3_pledge_delete($params) {
   if (CRM_Pledge_BAO_Pledge::deletePledge($params['id'])) {
@@ -77,6 +69,8 @@ function civicrm_api3_pledge_delete($params) {
 }
 
 /**
+ * Adjust metadata for pledge delete action.
+ *
  * @param array $params
  */
 function _civicrm_api3_pledge_delete_spec(&$params) {
@@ -85,7 +79,8 @@ function _civicrm_api3_pledge_delete_spec(&$params) {
 }
 
 /**
- * return field specification specific to get requests
+ * Adjust field specification specific to get requests.
+ *
  * @param array $params
  */
 function _civicrm_api3_pledge_get_spec(&$params) {
@@ -102,7 +97,8 @@ function _civicrm_api3_pledge_get_spec(&$params) {
 }
 
 /**
- * return field specification specific to get requests
+ * Adjust field specification specific to get requests.
+ *
  * @param array $params
  */
 function _civicrm_api3_pledge_create_spec(&$params) {
@@ -117,7 +113,7 @@ function _civicrm_api3_pledge_create_spec(&$params) {
 }
 
 /**
- * Retrieve a set of pledges, given a set of input params
+ * Retrieve a set of pledges, given a set of input params.
  *
  * @param array $params
  *   Input parameters. Use interrogate for possible fields.
@@ -142,14 +138,16 @@ function civicrm_api3_pledge_get($params) {
 }
 
 /**
- * Set default to not return test params
+ * Set default to not return test params.
  */
 function _civicrm_api3_pledge_get_defaults() {
   return array('pledge_test' => 0);
 }
 
 /**
- * Legacy function - I removed a bunch of stuff no longer required from here but it still needs
+ * Legacy function to format pledge parameters.
+ *
+ * I removed a bunch of stuff no longer required from here but it still needs
  * more culling
  * take the input parameter list as specified in the data model and
  * convert it into the same format that we use in QF and BAO object
diff --git a/api/v3/PriceSet.php b/api/v3/PriceSet.php
index 80f75b127e..6a9d356b6f 100644
--- a/api/v3/PriceSet.php
+++ b/api/v3/PriceSet.php
@@ -35,16 +35,14 @@
  */
 
 /**
- * Create or update a price_set
+ * Create or update a price_set.
  *
  * @param array $params
- *   Associative array of property.
+ *   array of property.
  *                       name/value pairs to insert in new 'price_set'
- * @example PriceSetCreate.php Std Create example
  *
  * @return array
  *   api result array
- *   {@getfields price_set_create}
  */
 function civicrm_api3_price_set_create($params) {
   $result = _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -77,7 +75,7 @@ function _civicrm_api3_price_set_create_spec(&$params) {
 }
 
 /**
- * Returns array of price_sets  matching a set of one or more group properties
+ * Returns array of price_sets matching a set of one or more group properties.
  *
  * @param array $params
  *   Array of one or more valid property_name=>value pairs. If $params is set.
@@ -85,7 +83,6 @@ function _civicrm_api3_price_set_create_spec(&$params) {
  *
  * @return array
  *   Array of matching price_sets
- *   {@getfields price_set_get}
  */
 function civicrm_api3_price_set_get($params) {
   // hack to make getcount work. - not sure the best approach here
@@ -102,7 +99,7 @@ function civicrm_api3_price_set_get($params) {
 }
 
 /**
- * delete an existing price_set
+ * Delete an existing price_set.
  *
  * This method is used to delete any existing price_set. id of the group
  * to be deleted is required field in $params array
@@ -113,7 +110,6 @@ function civicrm_api3_price_set_get($params) {
  *
  * @return array
  *   API result array
- *   {@getfields price_set_delete}
  */
 function civicrm_api3_price_set_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
diff --git a/api/v3/SurveyRespondant.php b/api/v3/SurveyRespondant.php
index 86da40035e..591007c23a 100644
--- a/api/v3/SurveyRespondant.php
+++ b/api/v3/SurveyRespondant.php
@@ -33,6 +33,8 @@
  */
 
 /**
+ * Notify caller of deprecated function.
+ *
  * @deprecated api notice
  * @return string
  *   to indicate this entire api entity is deprecated
@@ -44,8 +46,9 @@ function _civicrm_api3_survey_respondant_deprecation() {
 /**
  * Get the list of signatories
  * @deprecated - api currently not supported
+ *
  * @param array $params
- *   (reference ) input parameters.
+ *   input parameters.
  *
  * @return array
  */
diff --git a/api/v3/UFField.php b/api/v3/UFField.php
index be1dc78364..38790df841 100644
--- a/api/v3/UFField.php
+++ b/api/v3/UFField.php
@@ -121,7 +121,7 @@ function _civicrm_api3_uf_field_create_spec(&$params) {
 }
 
 /**
- * Returns array of uf groups (profiles)  matching a set of one or more group properties.
+ * Returns array of uf groups (profiles) matching a set of one or more group properties.
  *
  * @param array $params
  *   Array per getfields metadata.
@@ -158,7 +158,8 @@ function civicrm_api3_uf_field_delete($params) {
 }
 
 /**
- * field id accepted for backward compatibility - unset required on id
+ * Field id accepted for backward compatibility - unset required on id.
+ *
  * @param array $params
  */
 function _civicrm_api3_uf_field_delete_spec(&$params) {
diff --git a/api/v3/WordReplacement.php b/api/v3/WordReplacement.php
index 3a5bb451a7..2314361396 100644
--- a/api/v3/WordReplacement.php
+++ b/api/v3/WordReplacement.php
@@ -83,7 +83,6 @@ function _civicrm_api3_word_replacement_create_spec(&$params) {
  *
  * @return array
  *   API result array
- *
  */
 function civicrm_api3_word_replacement_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);