From b081365f52508bfd1fb0d3d15f3a0d48f5e9df12 Mon Sep 17 00:00:00 2001
From: Coleman Watts <coleman@civicrm.org>
Date: Thu, 5 Feb 2015 21:19:24 -0500
Subject: [PATCH] Api docblock cleanup.

---
 api/Exception.php                  |  1 -
 api/api.php                        |  7 +---
 api/v3/Acl.php                     |  4 --
 api/v3/AclRole.php                 |  1 -
 api/v3/ActionSchedule.php          |  9 ++---
 api/v3/Activity.php                |  3 +-
 api/v3/ActivityContact.php         |  4 +-
 api/v3/ActivityType.php            |  7 ++--
 api/v3/Address.php                 |  6 +--
 api/v3/Attachment.php              |  1 -
 api/v3/Batch.php                   |  3 +-
 api/v3/Campaign.php                |  7 ++--
 api/v3/Case.php                    | 17 +++------
 api/v3/CaseType.php                |  1 -
 api/v3/Constant.php                |  3 +-
 api/v3/Contact.php                 | 20 ++++------
 api/v3/ContactType.php             |  7 +++-
 api/v3/Contribution.php            | 12 +++---
 api/v3/ContributionPage.php        |  1 -
 api/v3/ContributionRecur.php       |  7 +---
 api/v3/ContributionSoft.php        |  4 +-
 api/v3/Country.php                 |  4 +-
 api/v3/CustomField.php             |  4 +-
 api/v3/CustomGroup.php             |  4 +-
 api/v3/CustomSearch.php            |  4 +-
 api/v3/CustomValue.php             |  6 +--
 api/v3/Dashboard.php               |  1 -
 api/v3/DashboardContact.php        |  4 +-
 api/v3/Domain.php                  |  6 +--
 api/v3/Email.php                   |  4 +-
 api/v3/EntityTag.php               |  4 +-
 api/v3/Event.php                   |  6 +--
 api/v3/Extension.php               |  3 --
 api/v3/File.php                    |  6 +--
 api/v3/FinancialAccount.php        |  1 -
 api/v3/FinancialType.php           |  1 -
 api/v3/Generic.php                 | 29 +++++++++++++++
 api/v3/Generic/Getactions.php      | 48 +++++++++++++-----------
 api/v3/Generic/Getlist.php         | 49 +++++++++++++-----------
 api/v3/Generic/Setvalue.php        | 30 +++++++++++++++
 api/v3/Generic/Update.php          |  4 ++
 api/v3/Grant.php                   | 14 +++----
 api/v3/Group.php                   | 12 +++---
 api/v3/GroupContact.php            | 60 +++++++++++++++++-------------
 api/v3/GroupNesting.php            |  8 ++--
 api/v3/GroupOrganization.php       |  4 +-
 api/v3/Im.php                      |  4 +-
 api/v3/Job.php                     |  9 ++---
 api/v3/LineItem.php                |  6 +--
 api/v3/LocBlock.php                |  1 -
 api/v3/LocationType.php            |  4 +-
 api/v3/MailSettings.php            |  3 +-
 api/v3/Mailing.php                 | 11 +++---
 api/v3/MailingAB.php               |  5 +--
 api/v3/MailingComponent.php        |  1 -
 api/v3/MailingContact.php          |  4 +-
 api/v3/MailingEventConfirm.php     |  3 +-
 api/v3/MailingEventQueue.php       |  3 +-
 api/v3/MailingEventResubscribe.php |  3 +-
 api/v3/MailingEventSubscribe.php   |  3 +-
 api/v3/MailingEventUnsubscribe.php |  3 +-
 api/v3/MailingGroup.php            |  1 -
 api/v3/MailingJob.php              |  3 +-
 api/v3/MailingRecipients.php       |  1 -
 api/v3/Membership.php              |  6 +--
 api/v3/MembershipBlock.php         |  4 +-
 api/v3/MembershipPayment.php       |  3 +-
 api/v3/MembershipStatus.php        |  5 +--
 api/v3/MembershipType.php          |  4 +-
 api/v3/MessageTemplate.php         |  6 +--
 api/v3/Note.php                    |  7 +---
 api/v3/OptionGroup.php             |  4 +-
 api/v3/OptionValue.php             |  4 +-
 api/v3/Participant.php             |  6 +--
 api/v3/ParticipantPayment.php      |  4 +-
 api/v3/ParticipantStatusType.php   |  5 +--
 api/v3/PaymentProcessor.php        |  4 +-
 api/v3/PaymentProcessorType.php    |  3 +-
 api/v3/Phone.php                   |  5 +--
 api/v3/Phone/Get.php               | 29 +++++++++++++++
 api/v3/Pledge.php                  |  4 --
 api/v3/PledgePayment.php           |  4 +-
 api/v3/Premium.php                 |  1 -
 api/v3/PriceField.php              |  6 +--
 api/v3/PriceFieldValue.php         |  6 +--
 api/v3/PriceSet.php                |  6 +--
 api/v3/PrintLabel.php              |  1 -
 api/v3/Product.php                 |  1 -
 api/v3/Profile.php                 |  1 -
 api/v3/Relationship.php            |  4 +-
 api/v3/RelationshipType.php        |  3 +-
 api/v3/ReportInstance.php          |  5 +--
 api/v3/ReportTemplate.php          |  5 +--
 api/v3/Setting.php                 |  3 +-
 api/v3/SmsProvider.php             |  3 +-
 api/v3/Survey.php                  | 13 ++++---
 api/v3/SurveyRespondant.php        |  3 +-
 api/v3/System.php                  | 10 ++---
 api/v3/SystemLog.php               |  2 -
 api/v3/Tag.php                     | 11 ++++--
 api/v3/UFField.php                 |  2 -
 api/v3/UFGroup.php                 |  6 +--
 api/v3/UFJoin.php                  |  4 +-
 api/v3/UFMatch.php                 |  4 +-
 api/v3/Website.php                 |  6 +--
 api/v3/WordReplacement.php         |  7 ++--
 api/v3/utils.php                   |  6 +--
 107 files changed, 346 insertions(+), 389 deletions(-)

diff --git a/api/Exception.php b/api/Exception.php
index 2bb9dcdd76..812bb603c0 100644
--- a/api/Exception.php
+++ b/api/Exception.php
@@ -4,7 +4,6 @@
  * File for the CiviCRM APIv3 API wrapper
  *
  * @package CiviCRM_APIv3
- * @subpackage API
  *
  * @copyright CiviCRM LLC (c) 2004-2014
  */
diff --git a/api/api.php b/api/api.php
index 6c263513e8..1ba09c7b3b 100644
--- a/api/api.php
+++ b/api/api.php
@@ -1,14 +1,9 @@
 <?php
 
 /**
- * @file
- * File for the CiviCRM APIv3 API wrapper.
+ * @file CiviCRM APIv3 API wrapper.
  *
  * @package CiviCRM_APIv3
- * @subpackage API
- *
- * @copyright CiviCRM LLC (c) 2004-2014
- * @version $Id: api.php 30486 2010-11-02 16:12:09Z shot $
  */
 
 /**
diff --git a/api/v3/Acl.php b/api/v3/Acl.php
index d1ee882ee9..f8d1df5e28 100644
--- a/api/v3/Acl.php
+++ b/api/v3/Acl.php
@@ -29,15 +29,11 @@
  * This api exposes CiviCRM acl.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_acl
  */
 
 /**
  * Save an acl.
  *
- * {@getfields acl_create}
- * @example aclCreate.php
- *
  * @param array $params
  *
  * @return array
diff --git a/api/v3/AclRole.php b/api/v3/AclRole.php
index 33d6c6fcaa..d4f5c95ae1 100644
--- a/api/v3/AclRole.php
+++ b/api/v3/AclRole.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM acl_role.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_acl_role
  */
 
 /**
diff --git a/api/v3/ActionSchedule.php b/api/v3/ActionSchedule.php
index 946318deb4..0a5083b87d 100644
--- a/api/v3/ActionSchedule.php
+++ b/api/v3/ActionSchedule.php
@@ -26,11 +26,9 @@
  */
 
 /**
- * File for the CiviCRM APIv3 for Scheduled Reminders
+ * This api exposes CiviCRM Scheduled Reminders.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_ActionSchedule
- *
  */
 
 /**
@@ -66,7 +64,7 @@ function civicrm_api3_action_schedule_create($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_action_schedule_create_spec(&$params) {
   $params['title']['api.required'] = TRUE;
@@ -78,8 +76,7 @@ function _civicrm_api3_action_schedule_create_spec(&$params) {
  * Delete an existing action_schedule.
  *
  * @param array $params
- *   Array containing id of the action_schedule.
- *   to be deleted
+ *   Array containing id of the action_schedule to be deleted.
  *
  * @return array
  *   API result array
diff --git a/api/v3/Activity.php b/api/v3/Activity.php
index f4521ea219..d3b43a2e28 100644
--- a/api/v3/Activity.php
+++ b/api/v3/Activity.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM activity.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Activity
  */
 
 
@@ -242,7 +241,7 @@ function civicrm_api3_activity_get($params) {
 /**
  * Given a list of activities, append any extra data requested about the activities.
  *
- * NOTE: Called by civicrm-core and CiviHR
+ * @note Called by civicrm-core and CiviHR
  *
  * @param array $params
  *   API request parameters.
diff --git a/api/v3/ActivityContact.php b/api/v3/ActivityContact.php
index fc873f43d8..c030330935 100644
--- a/api/v3/ActivityContact.php
+++ b/api/v3/ActivityContact.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM activity contact.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_ActivityContact
- *
  */
 
 /**
@@ -51,7 +49,7 @@ function civicrm_api3_activity_contact_create($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_activity_contact_create_spec(&$params) {
   $params['contact_id']['api.required'] = 1;
diff --git a/api/v3/ActivityType.php b/api/v3/ActivityType.php
index 627cfd419e..ebcc8b040c 100644
--- a/api/v3/ActivityType.php
+++ b/api/v3/ActivityType.php
@@ -31,7 +31,6 @@
  * @deprecated
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Activity
  */
 
 /**
@@ -68,7 +67,7 @@ function civicrm_api3_activity_type_get($params) {
  * @return array
  *   created / updated activity type
  *
- * @deprecated - use option_value create
+ * @deprecated use option_value api
  */
 function civicrm_api3_activity_type_create($params) {
 
@@ -91,7 +90,7 @@ function civicrm_api3_activity_type_create($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_activity_type_create_spec(&$params) {
   $params['label']['api.required'] = 1;
@@ -109,7 +108,7 @@ function _civicrm_api3_activity_type_create_spec(&$params) {
  * @return array
  *   API result array
  *
- * @deprecated - we will introduce OptionValue Delete- plse consider helping with this if not done
+ * @deprecated use option_value api
  */
 function civicrm_api3_activity_type_delete($params) {
   return civicrm_api3_create_success(CRM_Core_BAO_OptionValue::del($params['id']), $params);
diff --git a/api/v3/Address.php b/api/v3/Address.php
index 0e554efedf..b3f644b256 100644
--- a/api/v3/Address.php
+++ b/api/v3/Address.php
@@ -26,11 +26,9 @@
  */
 
 /**
- * This api exposes CiviCRM address.
+ * This api exposes CiviCRM address records.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Address
- *
  */
 
 /**
@@ -89,7 +87,7 @@ function civicrm_api3_address_create(&$params) {
  * Adjust Metadata for Create action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_address_create_spec(&$params) {
   $params['location_type_id']['api.required'] = 1;
diff --git a/api/v3/Attachment.php b/api/v3/Attachment.php
index 078d0fada8..258c4525d2 100644
--- a/api/v3/Attachment.php
+++ b/api/v3/Attachment.php
@@ -79,7 +79,6 @@
  *    "check_permissions"==false)
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Attachment
  */
 
 /**
diff --git a/api/v3/Batch.php b/api/v3/Batch.php
index 84ab4051db..eb46526c7b 100644
--- a/api/v3/Batch.php
+++ b/api/v3/Batch.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM batch.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Batch
  */
 
 /**
@@ -50,7 +49,7 @@ function civicrm_api3_batch_create($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_batch_create_spec(&$params) {
   //@todo - the entity table field looks like it is not actually required & should probably be removed (or a description added if
diff --git a/api/v3/Campaign.php b/api/v3/Campaign.php
index 96260393ad..836f542774 100644
--- a/api/v3/Campaign.php
+++ b/api/v3/Campaign.php
@@ -26,10 +26,11 @@
  */
 
 /**
- * This api exposes CiviCRM campaign.
+ * This api exposes CiviCRM campaign records.
+ *
+ * @note Campaign component must be enabled.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Campaign
  */
 
 /**
@@ -53,7 +54,7 @@ function civicrm_api3_campaign_create($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_campaign_create_spec(&$params) {
   $params['title']['api.required'] = 1;
diff --git a/api/v3/Case.php b/api/v3/Case.php
index 4d756e9265..79dd0b6bfc 100644
--- a/api/v3/Case.php
+++ b/api/v3/Case.php
@@ -26,11 +26,10 @@
  */
 
 /**
- * This api exposes CiviCRM Case.
+ * This api exposes CiviCRM Case objects.
  * Developed by woolman.org
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Case
  */
 
 
@@ -38,6 +37,7 @@
  * Open a new case, add client and manager roles, and add standard timeline.
  *
  * @param array $params
+ * @code
  * //REQUIRED:
  * 'case_type_id' => int OR
  * 'case_type' => str (provide one or the other)
@@ -52,6 +52,7 @@
  * 'start_date' => str datestamp // defaults to: date('YmdHis')
  * 'duration' => int // in minutes
  * 'details' => str // html format
+ * @endcode
  *
  * @throws API_Exception
  * @return array
@@ -141,7 +142,7 @@ function _civicrm_api3_case_get_spec(&$params) {
  * Adjust Metadata for Create Action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_case_create_spec(&$params) {
   $params['contact_id']['api.aliases'] = array('client_id');
@@ -163,7 +164,7 @@ function _civicrm_api3_case_create_spec(&$params) {
  * Adjust Metadata for Update action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_case_update_spec(&$params) {
   $params['id']['api.required'] = 1;
@@ -173,7 +174,7 @@ function _civicrm_api3_case_update_spec(&$params) {
  * Adjust Metadata for Delete action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_case_delete_spec(&$params) {
   $params['id']['api.required'] = 1;
@@ -387,12 +388,6 @@ function civicrm_api3_case_delete($params) {
   }
 }
 
-/***********************************/
-/*                                 */
-/*     INTERNAL FUNCTIONS          */
-/*                                 */
-/***********************************/
-
 /**
  * Internal function to retrieve a case.
  *
diff --git a/api/v3/CaseType.php b/api/v3/CaseType.php
index 74f5b4d2fe..bd556ec65a 100644
--- a/api/v3/CaseType.php
+++ b/api/v3/CaseType.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM Case.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Case
  */
 
 /**
diff --git a/api/v3/Constant.php b/api/v3/Constant.php
index d11571f745..cdcf39eb5f 100644
--- a/api/v3/Constant.php
+++ b/api/v3/Constant.php
@@ -31,7 +31,6 @@
  * @deprecated
  *   The constant api is deprecated as of CiviCRM 4.4. Please use the getoptions api action instead.
  * @package CiviCRM_APIv3
- * @subpackage API_Constant
  */
 
 /**
@@ -53,7 +52,7 @@ function _civicrm_api3_constant_deprecation() {
  *
  * @param array $params
  *  Name of a public static method of
- *                  CRM_Core_PseudoConstant: one of
+ *  CRM_Core_PseudoConstant: one of
  *  <ul>
  *    <li>activityStatus</li>
  *    <li>activityType</li>
diff --git a/api/v3/Contact.php b/api/v3/Contact.php
index acd04d03b3..99fca5a0b0 100644
--- a/api/v3/Contact.php
+++ b/api/v3/Contact.php
@@ -29,12 +29,11 @@
  * This api exposes CiviCRM contacts.
  * Contacts are the main entity in CiviCRM and this api is more robust than most.
  *   - Get action allows all params supported by advanced search.
- *   - Create action allows creating several other entities at once (e.g. email).
+ *   - Create action allows creating several related entities at once (e.g. email).
  *   - Create allows checking for duplicate contacts.
  * Use getfields to list the full range of parameters and options supported by each action.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Contact
  */
 
 /**
@@ -114,7 +113,7 @@ function civicrm_api3_contact_create($params) {
  * Adjust Metadata for Create action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_contact_create_spec(&$params) {
   $params['contact_type']['api.required'] = 1;
@@ -165,7 +164,7 @@ function civicrm_api3_contact_getcount($params) {
  * Adjust Metadata for Get action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_contact_get_spec(&$params) {
   $params['contact_is_deleted']['api.default'] = 0;
@@ -852,14 +851,11 @@ function _civicrm_api3_contact_deprecation() {
  * Merges given pair of duplicate contacts.
  *
  * @param array $params
- *   Input parameters.
- *
- * Allowed @params array keys are:
- * {int     main_id     main contact id with whom merge has to happen}
- * {int     other_id    duplicate contact which would be deleted after merge operation}
- * {string  mode        helps decide how to behave when there are conflicts.
- *                      A 'safe' value skips the merge if there are no conflicts. Does a force merge otherwise.}
- * {boolean auto_flip   wether to let api decide which contact to retain and which to delete.}
+ *   Allowed array keys are:
+ *   -int main_id: main contact id with whom merge has to happen
+ *   -int other_id: duplicate contact which would be deleted after merge operation
+ *   -string mode: "safe" skips the merge if there are no conflicts. Does a force merge otherwise.
+ *   -boolean auto_flip: whether to let api decide which contact to retain and which to delete.
  *
  * @return array
  *   API Result Array
diff --git a/api/v3/ContactType.php b/api/v3/ContactType.php
index a14d833adb..6e4567493b 100644
--- a/api/v3/ContactType.php
+++ b/api/v3/ContactType.php
@@ -26,10 +26,13 @@
  */
 
 /**
- * This api exposes CiviCRM contact type.
+ * This api exposes CiviCRM contact types and sub-types.
+ *
+ * CiviCRM comes with 3 primary contact types - Individual, Organization & Household.
+ * Changing these is not advised, but sub_types can be created with this api.
+ * Pass 'parent_id' param to specify which base type a new sub_type extends.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Survey
  */
 
 /**
diff --git a/api/v3/Contribution.php b/api/v3/Contribution.php
index 3de323215a..1a2dff8fd4 100644
--- a/api/v3/Contribution.php
+++ b/api/v3/Contribution.php
@@ -26,11 +26,9 @@
  */
 
 /**
- * This api exposes CiviCRM Contribution.
+ * This api exposes CiviCRM Contribution records.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Contribute
- *
  */
 
 /**
@@ -73,7 +71,7 @@ function civicrm_api3_contribution_create(&$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_contribution_create_spec(&$params) {
   $params['contact_id']['api.required'] = 1;
@@ -245,7 +243,7 @@ function _civicrm_api3_format_soft_credit(&$contribution) {
  * 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_contribution_get_spec(&$params) {
   $params['contribution_test']['api.default'] = 0;
@@ -281,7 +279,7 @@ function _civicrm_api3_contribute_format_params($params, &$values) {
  * 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_contribution_transact_spec(&$params) {
   $fields = civicrm_api3('contribution', 'getfields', array('action' => 'create'));
@@ -360,7 +358,7 @@ function civicrm_api3_contribution_sendconfirmation($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_contribution_sendconfirmation_spec(&$params) {
   $params['id'] = array(
diff --git a/api/v3/ContributionPage.php b/api/v3/ContributionPage.php
index dd3f62571e..ddf9b344fb 100644
--- a/api/v3/ContributionPage.php
+++ b/api/v3/ContributionPage.php
@@ -30,7 +30,6 @@
  * This api exposes CiviCRM contribution pages.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_ContributionPage
  */
 
 /**
diff --git a/api/v3/ContributionRecur.php b/api/v3/ContributionRecur.php
index fa1c6b8c49..0133aba973 100644
--- a/api/v3/ContributionRecur.php
+++ b/api/v3/ContributionRecur.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM recurring contributions.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_ContributionRecur
  */
 
 /**
@@ -51,7 +50,7 @@ function civicrm_api3_contribution_recur_create($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_contribution_recur_create_spec(&$params) {
   $params['contact_id']['api.required'] = 1;
@@ -64,9 +63,7 @@ function _civicrm_api3_contribution_recur_create_spec(&$params) {
  * Returns array of contribution_recurs 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
- *                       as null, all contribution_recurs will be returned
+ *   Array of properties. If empty, all records will be returned.
  *
  * @return array
  *   API result Array of matching contribution_recurs
diff --git a/api/v3/ContributionSoft.php b/api/v3/ContributionSoft.php
index a54e364942..e678a49887 100644
--- a/api/v3/ContributionSoft.php
+++ b/api/v3/ContributionSoft.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM soft credit.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_ContributionSoft
- *
  */
 
 /**
@@ -52,7 +50,7 @@ function civicrm_api3_contribution_soft_create($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_contribution_soft_create_spec(&$params) {
   $params['contribution_id']['api.required'] = 1;
diff --git a/api/v3/Country.php b/api/v3/Country.php
index 649d679feb..fbbedb9539 100644
--- a/api/v3/Country.php
+++ b/api/v3/Country.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM country.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Country
- *
  */
 
 /**
@@ -53,7 +51,7 @@ function civicrm_api3_country_create($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_country_create_spec(&$params) {
   $params['name']['api.required'] = 1;
diff --git a/api/v3/CustomField.php b/api/v3/CustomField.php
index 5adbbef484..068258ce55 100644
--- a/api/v3/CustomField.php
+++ b/api/v3/CustomField.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM custom field.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_CustomField
- *
  */
 
 /**
@@ -76,7 +74,7 @@ function _civicrm_api3_custom_field_flush_static_caches() {
  * Adjust Metadata for Create action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_custom_field_create_spec(&$params) {
   $params['label']['api.required'] = 1;
diff --git a/api/v3/CustomGroup.php b/api/v3/CustomGroup.php
index 440850ba97..0774fa8bcd 100644
--- a/api/v3/CustomGroup.php
+++ b/api/v3/CustomGroup.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM custom group.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_CustomGroup
- *
  */
 
 /**
@@ -69,7 +67,7 @@ function civicrm_api3_custom_group_create($params) {
  * Adjust Metadata for Create action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_custom_group_create_spec(&$params) {
   $params['extends']['api.required'] = 1;
diff --git a/api/v3/CustomSearch.php b/api/v3/CustomSearch.php
index f54f04f474..1862a6329d 100644
--- a/api/v3/CustomSearch.php
+++ b/api/v3/CustomSearch.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM custom search.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_CustomSearch
- *
  */
 
 /**
@@ -77,7 +75,7 @@ function civicrm_api3_custom_search_create($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_custom_search_create_spec(&$params) {
   require_once 'api/v3/OptionValue.php';
diff --git a/api/v3/CustomValue.php b/api/v3/CustomValue.php
index 0e6912c3b7..f7ef22ff9a 100644
--- a/api/v3/CustomValue.php
+++ b/api/v3/CustomValue.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM custom value.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_CustomField
- *
  */
 
 
@@ -113,7 +111,7 @@ function civicrm_api3_custom_value_create($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_custom_value_create_spec(&$params) {
   $params['entity_id']['api.required'] = 1;
@@ -229,7 +227,7 @@ function civicrm_api3_custom_value_get($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_custom_value_get_spec(&$params) {
   $params['entity_id']['api.required'] = 1;
diff --git a/api/v3/Dashboard.php b/api/v3/Dashboard.php
index 08dbfa2c8c..88d0875d37 100644
--- a/api/v3/Dashboard.php
+++ b/api/v3/Dashboard.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM Dashboard.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Activity
  */
 
 
diff --git a/api/v3/DashboardContact.php b/api/v3/DashboardContact.php
index f66fcac802..f70c354d65 100644
--- a/api/v3/DashboardContact.php
+++ b/api/v3/DashboardContact.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM dashboard contacts.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_ActionSchedule
- *
  */
 
 /**
@@ -74,7 +72,7 @@ function civicrm_api3_dashboard_contact_get($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_dashboard_contact_create_spec(&$params) {
   unset($params['version']);
diff --git a/api/v3/Domain.php b/api/v3/Domain.php
index bd2e75083a..baa367524a 100644
--- a/api/v3/Domain.php
+++ b/api/v3/Domain.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM domain.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Domain
- *
  */
 
 /**
@@ -116,7 +114,7 @@ function civicrm_api3_domain_get($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_domain_get_spec(&$params) {
   $params['current_domain'] = array('title' => "get loaded domain");
@@ -140,7 +138,7 @@ function civicrm_api3_domain_create($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_domain_create_spec(&$params) {
   $params['domain_version'] = $params['version'];
diff --git a/api/v3/Email.php b/api/v3/Email.php
index c47b6a0694..3f03ffb265 100644
--- a/api/v3/Email.php
+++ b/api/v3/Email.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM email.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Email
- *
  */
 
 /**
@@ -52,7 +50,7 @@ function civicrm_api3_email_create($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_email_create_spec(&$params) {
   // TODO a 'clever' default should be introduced
diff --git a/api/v3/EntityTag.php b/api/v3/EntityTag.php
index 9e1255b47a..d3f7f97ccf 100644
--- a/api/v3/EntityTag.php
+++ b/api/v3/EntityTag.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM entity tag.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_EntityTag
- *
  */
 
 /**
@@ -66,7 +64,7 @@ function civicrm_api3_entity_tag_get($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_entity_tag_get_spec(&$params) {
   $params['entity_id']['api.aliases'] = array('contact_id');
diff --git a/api/v3/Event.php b/api/v3/Event.php
index 1c20472bb3..df09a5767d 100644
--- a/api/v3/Event.php
+++ b/api/v3/Event.php
@@ -30,8 +30,6 @@
  * This api exposes CiviCRM event.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Event
- *
  */
 
 /**
@@ -63,7 +61,7 @@ function civicrm_api3_event_create($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_event_create_spec(&$params) {
   $params['start_date']['api.required'] = 1;
@@ -152,7 +150,7 @@ function civicrm_api3_event_get($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_event_get_spec(&$params) {
   $params['financial_type_id']['api.aliases'] = array('contribution_type_id');
diff --git a/api/v3/Extension.php b/api/v3/Extension.php
index 79649f3645..2dfbe7728a 100644
--- a/api/v3/Extension.php
+++ b/api/v3/Extension.php
@@ -32,8 +32,6 @@ define('API_V3_EXTENSION_DELIMITER', ',');
  * This api exposes CiviCRM extension.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Extension
- *
  */
 
 /**
@@ -173,7 +171,6 @@ function civicrm_api3_extension_uninstall($params) {
  * @throws API_Exception
  * @return array
  *   API result
- * @example ExtensionDownload.php
  */
 function civicrm_api3_extension_download($params) {
   if (!array_key_exists('key', $params)) {
diff --git a/api/v3/File.php b/api/v3/File.php
index b3f3476114..b250075fd7 100644
--- a/api/v3/File.php
+++ b/api/v3/File.php
@@ -26,18 +26,18 @@
  */
 
 /**
- * This api allows minimal handling with the CiviCRM file DAO.
+ * This api is a simple wrapper of the CiviCRM file DAO.
+ *
  * Creating and updating files is a complex process and this api is usually insufficient.
  * Use the "Attachment" api instead for more robust file handling.
  *
  * @fixme no unit tests
  * @package CiviCRM_APIv3
- * @subpackage API_File
  */
 
 /**
  * Create a file record.
- * Note: This is only one of several steps needed to create a file in CiviCRM.
+ * @note This is only one of several steps needed to create a file in CiviCRM.
  * Use the "Attachment" api to better handle all steps.
  *
  * @param array $params
diff --git a/api/v3/FinancialAccount.php b/api/v3/FinancialAccount.php
index 0e46b887d6..b22581290e 100644
--- a/api/v3/FinancialAccount.php
+++ b/api/v3/FinancialAccount.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM financial_account.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_financial_account
  */
 
 /**
diff --git a/api/v3/FinancialType.php b/api/v3/FinancialType.php
index 571e1c9759..96e4deb660 100644
--- a/api/v3/FinancialType.php
+++ b/api/v3/FinancialType.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM financial_type.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_financial_type
  */
 
 /**
diff --git a/api/v3/Generic.php b/api/v3/Generic.php
index 4dc53d259d..635ad69b40 100644
--- a/api/v3/Generic.php
+++ b/api/v3/Generic.php
@@ -1,4 +1,33 @@
 <?php
+/*
+ +--------------------------------------------------------------------+
+ | CiviCRM version 4.6                                                |
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC (c) 2004-2014                                |
+ +--------------------------------------------------------------------+
+ | This file is a part of CiviCRM.                                    |
+ |                                                                    |
+ | CiviCRM is free software; you can copy, modify, and distribute it  |
+ | under the terms of the GNU Affero General Public License           |
+ | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
+ |                                                                    |
+ | CiviCRM is distributed in the hope that it will be useful, but     |
+ | WITHOUT ANY WARRANTY; without even the implied warranty of         |
+ | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
+ | See the GNU Affero General Public License for more details.        |
+ |                                                                    |
+ | You should have received a copy of the GNU Affero General Public   |
+ | License and the CiviCRM Licensing Exception along                  |
+ | with this program; if not, contact CiviCRM LLC                     |
+ | at info[AT]civicrm[DOT]org. If you have questions about the        |
+ | GNU Affero General Public License or the licensing of CiviCRM,     |
+ | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
+ +--------------------------------------------------------------------+
+ */
+
+/**
+ * @package CiviCRM_APIv3
+ */
 
 /**
  * Get information about fields for a given api request.
diff --git a/api/v3/Generic/Getactions.php b/api/v3/Generic/Getactions.php
index bdefaa0682..4c51e710cc 100644
--- a/api/v3/Generic/Getactions.php
+++ b/api/v3/Generic/Getactions.php
@@ -1,28 +1,32 @@
 <?php
 /*
  +--------------------------------------------------------------------+
-| CiviCRM version 4.6                                                |
-+--------------------------------------------------------------------+
-| Copyright CiviCRM LLC (c) 2004-2014                                |
-+--------------------------------------------------------------------+
-| This file is a part of CiviCRM.                                    |
-|                                                                    |
-| CiviCRM is free software; you can copy, modify, and distribute it  |
-| under the terms of the GNU Affero General Public License           |
-| Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
-|                                                                    |
-| CiviCRM is distributed in the hope that it will be useful, but     |
-| WITHOUT ANY WARRANTY; without even the implied warranty of         |
-| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
-| See the GNU Affero General Public License for more details.        |
-|                                                                    |
-| You should have received a copy of the GNU Affero General Public   |
-| License and the CiviCRM Licensing Exception along                  |
-| with this program; if not, contact CiviCRM LLC                     |
-| at info[AT]civicrm[DOT]org. If you have questions about the        |
-| GNU Affero General Public License or the licensing of CiviCRM,     |
-| see the CiviCRM license FAQ at http://civicrm.org/licensing        |
-+--------------------------------------------------------------------+
+ | CiviCRM version 4.6                                                |
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC (c) 2004-2014                                |
+ +--------------------------------------------------------------------+
+ | This file is a part of CiviCRM.                                    |
+ |                                                                    |
+ | CiviCRM is free software; you can copy, modify, and distribute it  |
+ | under the terms of the GNU Affero General Public License           |
+ | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
+ |                                                                    |
+ | CiviCRM is distributed in the hope that it will be useful, but     |
+ | WITHOUT ANY WARRANTY; without even the implied warranty of         |
+ | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
+ | See the GNU Affero General Public License for more details.        |
+ |                                                                    |
+ | You should have received a copy of the GNU Affero General Public   |
+ | License and the CiviCRM Licensing Exception along                  |
+ | with this program; if not, contact CiviCRM LLC                     |
+ | at info[AT]civicrm[DOT]org. If you have questions about the        |
+ | GNU Affero General Public License or the licensing of CiviCRM,     |
+ | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
+ +--------------------------------------------------------------------+
+ */
+
+/**
+ * @package CiviCRM_APIv3
  */
 
 /**
diff --git a/api/v3/Generic/Getlist.php b/api/v3/Generic/Getlist.php
index fd0669b0b6..8a388ef1cb 100644
--- a/api/v3/Generic/Getlist.php
+++ b/api/v3/Generic/Getlist.php
@@ -1,29 +1,34 @@
 <?php
 /*
  +--------------------------------------------------------------------+
-| CiviCRM version 4.6                                                |
-+--------------------------------------------------------------------+
-| Copyright CiviCRM LLC (c) 2004-2014                                |
-+--------------------------------------------------------------------+
-| This file is a part of CiviCRM.                                    |
-|                                                                    |
-| CiviCRM is free software; you can copy, modify, and distribute it  |
-| under the terms of the GNU Affero General Public License           |
-| Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
-|                                                                    |
-| CiviCRM is distributed in the hope that it will be useful, but     |
-| WITHOUT ANY WARRANTY; without even the implied warranty of         |
-| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
-| See the GNU Affero General Public License for more details.        |
-|                                                                    |
-| You should have received a copy of the GNU Affero General Public   |
-| License and the CiviCRM Licensing Exception along                  |
-| with this program; if not, contact CiviCRM LLC                     |
-| at info[AT]civicrm[DOT]org. If you have questions about the        |
-| GNU Affero General Public License or the licensing of CiviCRM,     |
-| see the CiviCRM license FAQ at http://civicrm.org/licensing        |
-+--------------------------------------------------------------------+
+ | CiviCRM version 4.6                                                |
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC (c) 2004-2014                                |
+ +--------------------------------------------------------------------+
+ | This file is a part of CiviCRM.                                    |
+ |                                                                    |
+ | CiviCRM is free software; you can copy, modify, and distribute it  |
+ | under the terms of the GNU Affero General Public License           |
+ | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
+ |                                                                    |
+ | CiviCRM is distributed in the hope that it will be useful, but     |
+ | WITHOUT ANY WARRANTY; without even the implied warranty of         |
+ | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
+ | See the GNU Affero General Public License for more details.        |
+ |                                                                    |
+ | You should have received a copy of the GNU Affero General Public   |
+ | License and the CiviCRM Licensing Exception along                  |
+ | with this program; if not, contact CiviCRM LLC                     |
+ | at info[AT]civicrm[DOT]org. If you have questions about the        |
+ | GNU Affero General Public License or the licensing of CiviCRM,     |
+ | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
+ +--------------------------------------------------------------------+
  */
+
+/**
+ * @package CiviCRM_APIv3
+ */
+
 /**
  * Generic api wrapper used for quicksearch and autocomplete.
  *
diff --git a/api/v3/Generic/Setvalue.php b/api/v3/Generic/Setvalue.php
index bf62d00bd1..fd2223ad9e 100644
--- a/api/v3/Generic/Setvalue.php
+++ b/api/v3/Generic/Setvalue.php
@@ -1,4 +1,34 @@
 <?php
+/*
+ +--------------------------------------------------------------------+
+ | CiviCRM version 4.6                                                |
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC (c) 2004-2014                                |
+ +--------------------------------------------------------------------+
+ | This file is a part of CiviCRM.                                    |
+ |                                                                    |
+ | CiviCRM is free software; you can copy, modify, and distribute it  |
+ | under the terms of the GNU Affero General Public License           |
+ | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
+ |                                                                    |
+ | CiviCRM is distributed in the hope that it will be useful, but     |
+ | WITHOUT ANY WARRANTY; without even the implied warranty of         |
+ | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
+ | See the GNU Affero General Public License for more details.        |
+ |                                                                    |
+ | You should have received a copy of the GNU Affero General Public   |
+ | License and the CiviCRM Licensing Exception along                  |
+ | with this program; if not, contact CiviCRM LLC                     |
+ | at info[AT]civicrm[DOT]org. If you have questions about the        |
+ | GNU Affero General Public License or the licensing of CiviCRM,     |
+ | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
+ +--------------------------------------------------------------------+
+ */
+
+/**
+ * @package CiviCRM_APIv3
+ */
+
 /**
  * Set a single value using the api.
  *
diff --git a/api/v3/Generic/Update.php b/api/v3/Generic/Update.php
index f8720865df..f9181dad62 100644
--- a/api/v3/Generic/Update.php
+++ b/api/v3/Generic/Update.php
@@ -25,6 +25,10 @@
  +--------------------------------------------------------------------+
  */
 
+/**
+ * @package CiviCRM_APIv3
+ */
+
 /**
  * Update function is basically a hack.
  *
diff --git a/api/v3/Grant.php b/api/v3/Grant.php
index 6ab0ce55c2..bb0468fbbd 100644
--- a/api/v3/Grant.php
+++ b/api/v3/Grant.php
@@ -26,10 +26,11 @@
  */
 
 /**
- * This api exposes CiviCRM grant.
+ * This api exposes CiviCRM grant records.
+ *
+ * @note Grant component must be enabled.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Grant
  */
 
 /**
@@ -51,7 +52,7 @@ function civicrm_api3_grant_create($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_grant_create_spec(&$params) {
   $params['grant_type_id']['api.required'] = 1;
@@ -72,13 +73,10 @@ function civicrm_api3_grant_get($params) {
 }
 
 /**
- * Delete an existing grant.
- *
- * This method is used to delete any existing grant. id of the grant
- * to be deleted is required field in $params array
+ * This method is used to delete an existing grant.
  *
  * @param array $params
- *   Array per getfields metadata.
+ *   Id of the grant to be deleted is required.
  *
  * @return array
  *   API Result Array
diff --git a/api/v3/Group.php b/api/v3/Group.php
index c16cdc0247..59ab73fcf4 100644
--- a/api/v3/Group.php
+++ b/api/v3/Group.php
@@ -26,10 +26,12 @@
  */
 
 /**
- * This api exposes CiviCRM group.
+ * This api exposes CiviCRM groups.
+ *
+ * This api is for creating/deleting groups or fetching a list of existing groups.
+ * To add/remove contacts to a group, use the groupContact api instead.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Group
  */
 
 /**
@@ -51,7 +53,7 @@ function civicrm_api3_group_create($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_group_create_spec(&$params) {
   $params['is_active']['api.default'] = 1;
@@ -62,9 +64,7 @@ function _civicrm_api3_group_create_spec(&$params) {
  * Returns array of groups 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
- *                       as null, all groups will be returned
+ *   Array of properties. If empty, all records will be returned.
  *
  * @return array
  *   Array of matching groups
diff --git a/api/v3/GroupContact.php b/api/v3/GroupContact.php
index 0a778333be..601efd2bc4 100644
--- a/api/v3/GroupContact.php
+++ b/api/v3/GroupContact.php
@@ -26,11 +26,18 @@
  */
 
 /**
- * This api exposes CiviCRM group contact.
+ * This api exposes CiviCRM group contacts.
  *
- * @package CiviCRM_APIv3
- * @subpackage API_Group
+ * This api is for adding/removing contacts from a group,
+ * or fetching a list of groups for a contact.
+ *
+ * Important note: This api does not fetch smart groups for a contact.
+ * To fetch all contacts in a smart group, use the contact api
+ * passing a contact_id and group_id.
+ *
+ * To create/delete groups, use the group api instead.
  *
+ * @package CiviCRM_APIv3
  */
 
 
@@ -68,21 +75,10 @@ function civicrm_api3_group_contact_get($params) {
 /**
  * Add contact(s) to group(s).
  *
- * @param array $params
- *   Input parameters.
- *
- * Allowed @params array keys are:<br>
- * "contact_id" (required) : first contact to add<br>
- * "group_id" (required): first group to add contact(s) to<br>
- * "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")
- *
- * @return array
- *   Information about operation results
- *
- *   On success, the return array will be structured as follows:
- *   <code>array(
+ * This api has a legacy/nonstandard signature.
+ * On success, the return array will be structured as follows:
+ * @code
+ * array(
  *   "is_error" => 0,
  *   "version"  => 3,
  *   "count"    => 3,
@@ -91,15 +87,28 @@ function civicrm_api3_group_contact_get($params) {
  *     "added"       => integer,
  *     "total_count" => integer
  *   )
- *   )</code>
+ * )
+ * @endcode
  *
- *   On failure, the return array will be structured as follows:
- *   <code>array(
+ * On failure, the return array will be structured as follows:
+ * @code
+ * array(
  *   'is_error' => 1,
  *   'error_message' = string,
  *   'error_data' = mixed or undefined
- *   )</code>
- *   {@getfields GroupContact_create}
+ * )
+ * @endcode
+ *
+ * @param array $params
+ *   Input parameters.
+ *   - "contact_id" (required) : first contact to add
+ *   - "group_id" (required): first group to add contact(s) to
+ *   - "contact_id.1" etc. (optional) : another contact to add
+ *   - "group_id.1" etc. (optional) : additional group to add contact(s) to
+ *   - "status" (optional) : one of "Added", "Pending" or "Removed" (default is "Added")
+ *
+ * @return array
+ *   Information about operation results
  */
 function civicrm_api3_group_contact_create($params) {
   // Nonstandard bao - doesn't accept ID as a param, so convert id to group_id + contact_id
@@ -157,12 +166,13 @@ function civicrm_api3_group_contact_pending($params) {
 /**
  * Group contact helper function.
  *
+ * @todo behaviour is highly non-standard - need to figure out how to make this 'behave'
+ *   & at the very least return IDs & details of the groups created / changed
+ *
  * @param array $params
  * @param string $op
  *
  * @return array
- * @todo behaviour is highly non-standard - need to figure out how to make this 'behave'
- * & at the very least return IDs & details of the groups created / changed
  */
 function _civicrm_api3_group_contact_common($params, $op = 'Added') {
 
diff --git a/api/v3/GroupNesting.php b/api/v3/GroupNesting.php
index ec537581f0..db88e2b268 100644
--- a/api/v3/GroupNesting.php
+++ b/api/v3/GroupNesting.php
@@ -28,9 +28,9 @@
 /**
  * This api exposes CiviCRM group nesting.
  *
- * @package CiviCRM_APIv3
- * @subpackage API_Group
+ * This defines parent/child relationships between nested groups.
  *
+ * @package CiviCRM_APIv3
  */
 
 /**
@@ -74,7 +74,7 @@ function civicrm_api3_group_nesting_create($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_group_nesting_create_spec(&$params) {
   $params['child_group_id']['api.required'] = 1;
@@ -85,8 +85,6 @@ function _civicrm_api3_group_nesting_create_spec(&$params) {
  * Removes specific nesting records.
  *
  * @param array $params
- *   Parameters array - allowed array keys include:.
- * {@getfields GroupNesting_delete}
  *
  * @return array
  *   API Success or fail array
diff --git a/api/v3/GroupOrganization.php b/api/v3/GroupOrganization.php
index 8f8800ff92..73a6437855 100644
--- a/api/v3/GroupOrganization.php
+++ b/api/v3/GroupOrganization.php
@@ -29,8 +29,6 @@
  * This api exposes the relationships between organizations and CiviCRM groups.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Group
- *
  */
 
 
@@ -73,7 +71,7 @@ function civicrm_api3_group_organization_create($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_group_organization_create_spec(&$params) {
   $params['organization_id']['api.required'] = 1;
diff --git a/api/v3/Im.php b/api/v3/Im.php
index 33aac88a6a..785102fd2f 100644
--- a/api/v3/Im.php
+++ b/api/v3/Im.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM IM.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_IM
- *
  */
 
 /**
@@ -51,7 +49,7 @@ function civicrm_api3_im_create($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_im_create_spec(&$params) {
   $params['contact_id']['api.required'] = 1;
diff --git a/api/v3/Job.php b/api/v3/Job.php
index 178d3c34e5..1f554eda0f 100644
--- a/api/v3/Job.php
+++ b/api/v3/Job.php
@@ -29,7 +29,6 @@
  * This api is used for triggering scheduled "cron" jobs.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Job
  */
 
 /**
@@ -38,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;
@@ -107,7 +106,7 @@ function civicrm_api3_job_execute($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) {
 }
@@ -184,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
@@ -253,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(
diff --git a/api/v3/LineItem.php b/api/v3/LineItem.php
index cf76affa90..d5ca8d62c7 100644
--- a/api/v3/LineItem.php
+++ b/api/v3/LineItem.php
@@ -30,7 +30,6 @@
  * This api exposes CiviCRM line item.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_LineItem
  */
 
 /**
@@ -53,7 +52,7 @@ function civicrm_api3_line_item_create($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_line_item_create_spec(&$params) {
   $params['entity_id']['api.required'] = 1;
@@ -84,8 +83,7 @@ function civicrm_api3_line_item_get($params) {
  * to be deleted is required field in $params array
  *
  * @param array $params
- *   Array containing id of the group.
- *   to be deleted
+ *   Array containing id of the group to be deleted.
  *
  * @return array
  *   API result array
diff --git a/api/v3/LocBlock.php b/api/v3/LocBlock.php
index 456b0826f0..ccd3633b72 100644
--- a/api/v3/LocBlock.php
+++ b/api/v3/LocBlock.php
@@ -30,7 +30,6 @@
  * This api exposes CiviCRM loc_block.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_LocBlock
  */
 
 /**
diff --git a/api/v3/LocationType.php b/api/v3/LocationType.php
index d64ab8a171..5293a445e8 100644
--- a/api/v3/LocationType.php
+++ b/api/v3/LocationType.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM location type.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_LocationType
- *
  */
 
 /**
@@ -56,7 +54,7 @@ function civicrm_api3_location_type_create($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_location_type_create_spec(&$params) {
   $params['is_active']['api.default'] = 1;
diff --git a/api/v3/MailSettings.php b/api/v3/MailSettings.php
index 88f39c1e74..c0c6e40849 100644
--- a/api/v3/MailSettings.php
+++ b/api/v3/MailSettings.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM mail settings.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_mail_settings
  */
 
 /**
@@ -51,7 +50,7 @@ function civicrm_api3_mail_settings_create($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_mail_settings_create_spec(&$params) {
 
diff --git a/api/v3/Mailing.php b/api/v3/Mailing.php
index c0ca279948..42347376b9 100755
--- a/api/v3/Mailing.php
+++ b/api/v3/Mailing.php
@@ -30,7 +30,6 @@
  * APIv3 functions for registering/processing mailing events.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Mailing
  */
 
 /**
@@ -101,7 +100,7 @@ function civicrm_api3_mailing_get_token($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_mailing_create_spec(&$params) {
   $params['created_id']['api.required'] = 1;
@@ -223,7 +222,7 @@ function civicrm_api3_mailing_event_bounce($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_mailing_event_bounce_spec(&$params) {
   $params['job_id']['api.required'] = 1;
@@ -293,7 +292,7 @@ function civicrm_api3_mailing_event_reply($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_mailing_event_reply_spec(&$params) {
   $params['job_id']['api.required'] = 1;
@@ -336,7 +335,7 @@ function civicrm_api3_mailing_event_forward($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_mailing_event_forward_spec(&$params) {
   $params['job_id']['api.required'] = 1;
@@ -561,7 +560,7 @@ function civicrm_api3_mailing_send_test($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_mailing_stats_spec(&$params) {
   $params['date']['api.default'] = 'now';
diff --git a/api/v3/MailingAB.php b/api/v3/MailingAB.php
index 8b73975ebb..5e9a124075 100755
--- a/api/v3/MailingAB.php
+++ b/api/v3/MailingAB.php
@@ -30,7 +30,6 @@
  * APIv3 functions for registering/processing mailing ab testing events.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_MailingAB
  */
 
 /**
@@ -74,7 +73,7 @@ function civicrm_api3_mailing_a_b_get($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_mailing_a_b_submit_spec(&$params) {
   $mailingFields = CRM_Mailing_DAO_Mailing::fields();
@@ -166,7 +165,7 @@ function civicrm_api3_mailing_a_b_submit($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_mailing_a_b_graph_stats_spec(&$params) {
   $params['criteria']['title'] = 'Criteria';
diff --git a/api/v3/MailingComponent.php b/api/v3/MailingComponent.php
index 93bfddab0e..3ff4c94085 100644
--- a/api/v3/MailingComponent.php
+++ b/api/v3/MailingComponent.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM mailing_component.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_mailing_component
  */
 
 /**
diff --git a/api/v3/MailingContact.php b/api/v3/MailingContact.php
index dd7fe72a94..7c61428709 100644
--- a/api/v3/MailingContact.php
+++ b/api/v3/MailingContact.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM contact and mailing.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_MailingContact
- *
  */
 
 /**
@@ -73,7 +71,7 @@ function _civicrm_api3_mailing_contact_getresults($params, $count) {
  * Adjust Metadata for Get action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_mailing_contact_get_spec(&$params) {
   $params['contact_id']['api.required'] = 1;
diff --git a/api/v3/MailingEventConfirm.php b/api/v3/MailingEventConfirm.php
index 9864bb9cd1..66d354f923 100644
--- a/api/v3/MailingEventConfirm.php
+++ b/api/v3/MailingEventConfirm.php
@@ -30,7 +30,6 @@
  * APIv3 functions for registering/processing mailing group events.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_MailerGroup
  */
 
 /**
@@ -63,7 +62,7 @@ function civicrm_api3_mailing_event_confirm_create($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_mailing_event_confirm_create_spec(&$params) {
   $params['contact_id']['api.required'] = 1;
diff --git a/api/v3/MailingEventQueue.php b/api/v3/MailingEventQueue.php
index 6e15045df8..0451abe9cf 100644
--- a/api/v3/MailingEventQueue.php
+++ b/api/v3/MailingEventQueue.php
@@ -29,7 +29,6 @@
  * APIv3 functions for registering/processing mailing group events.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_MailerGroup
  */
 
 /**
@@ -83,7 +82,7 @@ function civicrm_api3_mailing_event_queue_delete($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_mailing_event_queue_create_spec(&$params) {
   $params['job_id']['api.required'] = 1;
diff --git a/api/v3/MailingEventResubscribe.php b/api/v3/MailingEventResubscribe.php
index 64a3659db6..52963e6553 100644
--- a/api/v3/MailingEventResubscribe.php
+++ b/api/v3/MailingEventResubscribe.php
@@ -30,7 +30,6 @@
  * APIv3 functions for registering/processing mailing group events.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_MailerGroup
  */
 
 /**
@@ -66,7 +65,7 @@ function civicrm_api3_mailing_event_resubscribe_create($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_mailing_event_resubscribe_create_spec(&$params) {
   $params['event_queue_id']['api.required'] = 1;
diff --git a/api/v3/MailingEventSubscribe.php b/api/v3/MailingEventSubscribe.php
index 564ecb3376..ac82084461 100644
--- a/api/v3/MailingEventSubscribe.php
+++ b/api/v3/MailingEventSubscribe.php
@@ -30,7 +30,6 @@
  * APIv3 functions for registering/processing mailing group events.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_MailerGroup
  */
 
 /**
@@ -78,7 +77,7 @@ function civicrm_api3_mailing_event_subscribe_create($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_mailing_event_subscribe_create_spec(&$params) {
   $params['email']['api.required'] = 1;
diff --git a/api/v3/MailingEventUnsubscribe.php b/api/v3/MailingEventUnsubscribe.php
index f6667587e5..322f9263b5 100644
--- a/api/v3/MailingEventUnsubscribe.php
+++ b/api/v3/MailingEventUnsubscribe.php
@@ -30,7 +30,6 @@
  * APIv3 functions for registering/processing mailing group events.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_MailerGroup
  */
 
 /**
@@ -73,7 +72,7 @@ function civicrm_api3_mailing_event_unsubscribe_create($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_mailing_event_unsubscribe_create_spec(&$params) {
   $params['job_id']['api.required'] = 1;
diff --git a/api/v3/MailingGroup.php b/api/v3/MailingGroup.php
index beb3f1374b..5633e5876c 100644
--- a/api/v3/MailingGroup.php
+++ b/api/v3/MailingGroup.php
@@ -30,7 +30,6 @@
  *
  * @deprecated
  * @package CiviCRM_APIv3
- * @subpackage API_MailerGroup
  */
 
 /**
diff --git a/api/v3/MailingJob.php b/api/v3/MailingJob.php
index 649c311387..fa25329aed 100644
--- a/api/v3/MailingJob.php
+++ b/api/v3/MailingJob.php
@@ -30,7 +30,6 @@
  * APIv3 functions for registering/processing mailing jobs.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Mailing
  */
 
 /**
@@ -51,7 +50,7 @@ function civicrm_api3_mailing_job_create($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_mailing_job_create_spec(&$params) {
   $params['status']['api.default'] = 'Scheduled';
diff --git a/api/v3/MailingRecipients.php b/api/v3/MailingRecipients.php
index 6b39269b05..7dc5d770a7 100644
--- a/api/v3/MailingRecipients.php
+++ b/api/v3/MailingRecipients.php
@@ -29,7 +29,6 @@
  * APIv3 functions for registering/processing mailing recipients.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Mailing
  */
 
 
diff --git a/api/v3/Membership.php b/api/v3/Membership.php
index 3951239c31..3152a1b0a4 100644
--- a/api/v3/Membership.php
+++ b/api/v3/Membership.php
@@ -30,8 +30,6 @@
  * This api exposes CiviCRM membership contact.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Membership
- *
  */
 
 /**
@@ -143,7 +141,7 @@ function civicrm_api3_membership_create($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_membership_create_spec(&$params) {
   $params['contact_id']['api.required'] = 1;
@@ -166,7 +164,7 @@ function _civicrm_api3_membership_create_spec(&$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_membership_get_spec(&$params) {
   $params['membership_type_id']['api.aliases'] = array('membership_type');
diff --git a/api/v3/MembershipBlock.php b/api/v3/MembershipBlock.php
index 77cade9fdf..75f4c5e2e8 100644
--- a/api/v3/MembershipBlock.php
+++ b/api/v3/MembershipBlock.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM membership block.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Membership
- *
  */
 
 /**
@@ -52,7 +50,7 @@ function civicrm_api3_membership_block_create($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_membership_block_create_spec(&$params) {
   $params['is_active']['api.default'] = TRUE;
diff --git a/api/v3/MembershipPayment.php b/api/v3/MembershipPayment.php
index 3eb49d0421..1da954fc33 100644
--- a/api/v3/MembershipPayment.php
+++ b/api/v3/MembershipPayment.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM membership contribution link.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Membership
  * @todo delete function doesn't exist
  */
 
@@ -52,7 +51,7 @@ function civicrm_api3_membership_payment_create($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_membership_payment_create_spec(&$params) {
   $params['membership_id']['api.required'] = 1;
diff --git a/api/v3/MembershipStatus.php b/api/v3/MembershipStatus.php
index 42c5172d44..8ed1b6864b 100644
--- a/api/v3/MembershipStatus.php
+++ b/api/v3/MembershipStatus.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM membership status.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Membership
- *
  */
 
 /**
@@ -56,7 +54,6 @@ function civicrm_api3_membership_status_create($params) {
  *
  * @return array
  *   Array of all found membership status property values.
- *   {@getfields MembershipStatus_get}
  */
 function civicrm_api3_membership_status_get($params) {
   return _civicrm_api3_basic_get('CRM_Member_BAO_MembershipStatus', $params);
@@ -66,7 +63,7 @@ function civicrm_api3_membership_status_get($params) {
  * Update an existing membership status.
  *
  * This api is used for updating an existing membership status.
- * Required parameters : id of a membership status
+ * Required parameters: id of a membership status
  *
  * @param array $params
  *   Array of name/value property values of civicrm_membership_status.
diff --git a/api/v3/MembershipType.php b/api/v3/MembershipType.php
index 5442b5610c..f1d49a2537 100644
--- a/api/v3/MembershipType.php
+++ b/api/v3/MembershipType.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM membership type.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Membership
- *
  */
 
 /**
@@ -52,7 +50,7 @@ function civicrm_api3_membership_type_create($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_membership_type_create_spec(&$params) {
   // todo could set default here probably
diff --git a/api/v3/MessageTemplate.php b/api/v3/MessageTemplate.php
index 26c4805fcb..1623a5ba85 100644
--- a/api/v3/MessageTemplate.php
+++ b/api/v3/MessageTemplate.php
@@ -27,7 +27,7 @@
 /**
  * This api exposes CiviCRM message_template.
  *
- * @package CiviCRM_SEPA
+ * @package CiviCRM_APIv3
  */
 
 /**
@@ -48,7 +48,7 @@ function civicrm_api3_message_template_create($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_message_template_create_spec(&$params) {
   $params['msg_title']['api.required'] = 1;
@@ -108,7 +108,7 @@ function civicrm_api3_message_template_send($params) {
  * validation.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_message_template_send_spec(&$params) {
   $params['messageTemplateID']['api.required'] = 1;
diff --git a/api/v3/Note.php b/api/v3/Note.php
index 86fe2ee0bc..d689fdefcb 100644
--- a/api/v3/Note.php
+++ b/api/v3/Note.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM note.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Note
- *
  */
 
 /**
@@ -41,7 +39,6 @@
  *
  * @param array $params
  *   An associative array of name/value property values of civicrm_note.
- * {@getfields note_create}
  *
  * @return array
  *   API result array
@@ -56,7 +53,7 @@ function civicrm_api3_note_create($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_note_create_spec(&$params) {
   $params['entity_table']['api.default'] = "civicrm_contact";
@@ -102,7 +99,7 @@ function civicrm_api3_note_get($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_note_get_spec(&$params) {
   $params['entity_table']['api.default'] = "civicrm_contact";
diff --git a/api/v3/OptionGroup.php b/api/v3/OptionGroup.php
index c65ffee5e3..e7d793709a 100644
--- a/api/v3/OptionGroup.php
+++ b/api/v3/OptionGroup.php
@@ -30,8 +30,6 @@
  * Each group contains option values.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_OptionValue
- *
  */
 
 /**
@@ -63,7 +61,7 @@ function civicrm_api3_option_group_create($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_option_group_create_spec(&$params) {
   $params['name']['api.unique'] = 1;
diff --git a/api/v3/OptionValue.php b/api/v3/OptionValue.php
index 37977cf046..a47e8ebed5 100644
--- a/api/v3/OptionValue.php
+++ b/api/v3/OptionValue.php
@@ -30,8 +30,6 @@
  * Values are grouped by "OptionGroup"
  *
  * @package CiviCRM_APIv3
- * @subpackage API_OptionValue
- *
  */
 
 /**
@@ -86,7 +84,7 @@ function civicrm_api3_option_value_create($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_option_value_create_spec(&$params) {
   $params['is_active']['api.default'] = 1;
diff --git a/api/v3/Participant.php b/api/v3/Participant.php
index 3e84c789d0..654fb59d1d 100644
--- a/api/v3/Participant.php
+++ b/api/v3/Participant.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM participant.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Participant
- *
  */
 
 /**
@@ -137,7 +135,7 @@ function _civicrm_api3_participant_createlineitem(&$params, $participant) {
  * 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_participant_create_spec(&$params) {
   $params['status_id']['api.default'] = "1";
@@ -180,7 +178,7 @@ function civicrm_api3_participant_get($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_participant_get_spec(&$params) {
   $params['participant_test']['api.default'] = 0;
diff --git a/api/v3/ParticipantPayment.php b/api/v3/ParticipantPayment.php
index 70d2ac8e9c..92a47adbaf 100644
--- a/api/v3/ParticipantPayment.php
+++ b/api/v3/ParticipantPayment.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM participant payments.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Participant
- *
  */
 
 /**
@@ -65,7 +63,7 @@ function civicrm_api3_participant_payment_create($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_participant_payment_create_spec(&$params) {
   $params['participant_id']['api.required'] = 1;
diff --git a/api/v3/ParticipantStatusType.php b/api/v3/ParticipantStatusType.php
index 8436457684..23a4a74a13 100644
--- a/api/v3/ParticipantStatusType.php
+++ b/api/v3/ParticipantStatusType.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM participant status options.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Event
  */
 
 /**
@@ -53,9 +52,7 @@ function civicrm_api3_participant_status_type_create($params) {
  * Returns array of participant_statuses 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
- *                       as null, all participant_statuses will be returned
+ *   Array of properties. If empty, all records will be returned.
  *
  * @return array
  *   Array of matching participant_statuses
diff --git a/api/v3/PaymentProcessor.php b/api/v3/PaymentProcessor.php
index 6ca6365098..54cdcabb87 100644
--- a/api/v3/PaymentProcessor.php
+++ b/api/v3/PaymentProcessor.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM PaymentProcessor.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_PaymentProcessor
- *
  */
 
 /**
@@ -51,7 +49,7 @@ function civicrm_api3_payment_processor_create($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_payment_processor_create_spec(&$params) {
   $params['payment_processor_type_id']['api.required'] = 1;
diff --git a/api/v3/PaymentProcessorType.php b/api/v3/PaymentProcessorType.php
index 34035ef1c4..1e62e72144 100644
--- a/api/v3/PaymentProcessorType.php
+++ b/api/v3/PaymentProcessorType.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM payment processor types.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Contact
  */
 
 /**
@@ -60,7 +59,7 @@ function civicrm_api3_payment_processor_type_create($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_payment_processor_type_create_spec(&$params) {
   $params['billing_mode']['api.required'] = 1;
diff --git a/api/v3/Phone.php b/api/v3/Phone.php
index 291b603c50..599ee8ce7c 100644
--- a/api/v3/Phone.php
+++ b/api/v3/Phone.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM phone.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Phone
- *
  */
 
 /**
@@ -52,7 +50,7 @@ function civicrm_api3_phone_create($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_phone_create_spec(&$params) {
   $params['contact_id']['api.required'] = 1;
@@ -78,5 +76,4 @@ function civicrm_api3_phone_delete($params) {
  *  civicrm_api('Phone','Get') to retrieve one or more phones is implemented by
  *  function civicrm_api3_phone_get ($params) into the file Phone/Get.php
  *  Could have been implemented here in this file too, but we moved it to illustrate the feature with a real usage.
- *
  */
diff --git a/api/v3/Phone/Get.php b/api/v3/Phone/Get.php
index afa99b2f7a..35f9c628f5 100644
--- a/api/v3/Phone/Get.php
+++ b/api/v3/Phone/Get.php
@@ -1,4 +1,33 @@
 <?php
+/*
+ +--------------------------------------------------------------------+
+ | CiviCRM version 4.6                                                |
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC (c) 2004-2014                                |
+ +--------------------------------------------------------------------+
+ | This file is a part of CiviCRM.                                    |
+ |                                                                    |
+ | CiviCRM is free software; you can copy, modify, and distribute it  |
+ | under the terms of the GNU Affero General Public License           |
+ | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
+ |                                                                    |
+ | CiviCRM is distributed in the hope that it will be useful, but     |
+ | WITHOUT ANY WARRANTY; without even the implied warranty of         |
+ | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
+ | See the GNU Affero General Public License for more details.        |
+ |                                                                    |
+ | You should have received a copy of the GNU Affero General Public   |
+ | License and the CiviCRM Licensing Exception along                  |
+ | with this program; if not, contact CiviCRM LLC                     |
+ | at info[AT]civicrm[DOT]org. If you have questions about the        |
+ | GNU Affero General Public License or the licensing of CiviCRM,     |
+ | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
+ +--------------------------------------------------------------------+
+ */
+
+/**
+ * @package CiviCRM_APIv3
+ */
 
 /**
  * Retrieve one or more phones.
diff --git a/api/v3/Pledge.php b/api/v3/Pledge.php
index 5205c3f445..18e1acbed4 100644
--- a/api/v3/Pledge.php
+++ b/api/v3/Pledge.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM Pledge.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Pledge
- *
  */
 
 /**
@@ -121,8 +119,6 @@ function _civicrm_api3_pledge_create_spec(&$params) {
  *
  * @return array
  *   array of pledges, if error an array with an error id and error message
- *   {@getfields pledge_get}
- * @example PledgeGet.php
  */
 function civicrm_api3_pledge_get($params) {
   $mode = CRM_Contact_BAO_Query::MODE_PLEDGE;
diff --git a/api/v3/PledgePayment.php b/api/v3/PledgePayment.php
index ffae5a08ae..7e39ff987c 100644
--- a/api/v3/PledgePayment.php
+++ b/api/v3/PledgePayment.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM Pledge payment.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Pledge_Payment
- *
  */
 
 /**
@@ -81,7 +79,7 @@ function civicrm_api3_pledge_payment_create($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_pledge_payment_create_spec(&$params) {
   $params['pledge_id']['api.required'] = 1;
diff --git a/api/v3/Premium.php b/api/v3/Premium.php
index fdf91aa76d..52827ccc1e 100644
--- a/api/v3/Premium.php
+++ b/api/v3/Premium.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM premium.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_premium
  */
 
 /**
diff --git a/api/v3/PriceField.php b/api/v3/PriceField.php
index d6bd9e7d77..e63a28cb79 100644
--- a/api/v3/PriceField.php
+++ b/api/v3/PriceField.php
@@ -30,7 +30,6 @@
  * This api exposes CiviCRM price set fields.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_PriceField
  */
 
 /**
@@ -52,7 +51,7 @@ function civicrm_api3_price_field_create($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_price_field_create_spec(&$params) {
   $params['label']['api.required'] = TRUE;
@@ -79,8 +78,7 @@ function civicrm_api3_price_field_get($params) {
  * to be deleted is required field in $params array
  *
  * @param array $params
- *   Array containing id of the group.
- *   to be deleted
+ *   Array containing id of the group to be deleted.
  *
  * @return array
  *   API result array
diff --git a/api/v3/PriceFieldValue.php b/api/v3/PriceFieldValue.php
index 9161af4870..a22cf7b3e3 100644
--- a/api/v3/PriceFieldValue.php
+++ b/api/v3/PriceFieldValue.php
@@ -30,7 +30,6 @@
  * This api exposes CiviCRM price sets.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_PriceFieldValue
  */
 
 /**
@@ -62,7 +61,7 @@ function civicrm_api3_price_field_value_create($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_price_field_value_create_spec(&$params) {
   $params['price_field_id']['api.required'] = TRUE;
@@ -92,8 +91,7 @@ function civicrm_api3_price_field_value_get($params) {
  * to be deleted is required field in $params array
  *
  * @param array $params
- *   Array containing id of the group.
- *   to be deleted
+ *   Array containing id of the group to be deleted.
  *
  * @return array
  *   API result array.
diff --git a/api/v3/PriceSet.php b/api/v3/PriceSet.php
index be20e0557b..15061c4b92 100644
--- a/api/v3/PriceSet.php
+++ b/api/v3/PriceSet.php
@@ -30,7 +30,6 @@
  * This api exposes CiviCRM price sets.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_PriceSet
  */
 
 /**
@@ -66,7 +65,7 @@ function civicrm_api3_price_set_create($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_price_set_create_spec(&$params) {
   $params['title']['api.required'] = TRUE;
@@ -103,8 +102,7 @@ function civicrm_api3_price_set_get($params) {
  * to be deleted is required field in $params array
  *
  * @param array $params
- *   Array containing id of the group.
- *   to be deleted
+ *   Array containing id of the group to be deleted.
  *
  * @return array
  *   API result array
diff --git a/api/v3/PrintLabel.php b/api/v3/PrintLabel.php
index c71d037fb7..7090991ce3 100644
--- a/api/v3/PrintLabel.php
+++ b/api/v3/PrintLabel.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM print_label.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_print_label
  */
 
 /**
diff --git a/api/v3/Product.php b/api/v3/Product.php
index 47c7545e27..56a767da29 100644
--- a/api/v3/Product.php
+++ b/api/v3/Product.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM product.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_product
  */
 
 /**
diff --git a/api/v3/Profile.php b/api/v3/Profile.php
index 3532e5dbd0..5c4b21764e 100644
--- a/api/v3/Profile.php
+++ b/api/v3/Profile.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM activity profile.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_ActivityProfile
  */
 
 /**
diff --git a/api/v3/Relationship.php b/api/v3/Relationship.php
index f0b0437171..b4e20a2558 100644
--- a/api/v3/Relationship.php
+++ b/api/v3/Relationship.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM relationships.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Relationship
- *
  */
 
 /**
@@ -53,7 +51,7 @@ function civicrm_api3_relationship_create($params) {
  * Adjust Metadata for Create action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  */
 function _civicrm_api3_relationship_create_spec(&$params) {
   $params['contact_id_a']['api.required'] = 1;
diff --git a/api/v3/RelationshipType.php b/api/v3/RelationshipType.php
index 18afe90fbb..d4f3c39ec2 100644
--- a/api/v3/RelationshipType.php
+++ b/api/v3/RelationshipType.php
@@ -29,7 +29,6 @@
  * This api exposes CiviCRM relationship types.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Contact
  */
 
 /**
@@ -75,7 +74,7 @@ function civicrm_api3_relationship_type_create($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_relationship_type_create_spec(&$params) {
   $params['contact_type_a']['api.required'] = 1;
diff --git a/api/v3/ReportInstance.php b/api/v3/ReportInstance.php
index e13d66f4ee..53a9423287 100644
--- a/api/v3/ReportInstance.php
+++ b/api/v3/ReportInstance.php
@@ -28,8 +28,7 @@
 /**
  * This api exposes CiviCRM report instances.
  *
- * @package CiviCRM_APIv3_Core
- * @subpackage API_Report
+ * @package CiviCRM_APIv3
  */
 
 /**
@@ -63,7 +62,7 @@ function civicrm_api3_report_instance_create($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_report_instance_create_spec(&$params) {
   $params['report_id']['api.required'] = 1;
diff --git a/api/v3/ReportTemplate.php b/api/v3/ReportTemplate.php
index 0e85821ef6..1c21ded0b4 100644
--- a/api/v3/ReportTemplate.php
+++ b/api/v3/ReportTemplate.php
@@ -28,8 +28,7 @@
 /**
  * This api exposes CiviCRM report templates.
  *
- * @package CiviCRM_APIv3_Core
- * @subpackage API_Report
+ * @package CiviCRM_APIv3
  */
 
 /**
@@ -78,7 +77,7 @@ function civicrm_api3_report_template_create($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_report_template_create_spec(&$params) {
   require_once 'api/v3/OptionValue.php';
diff --git a/api/v3/Setting.php b/api/v3/Setting.php
index a8343612a2..53a39dfbc5 100644
--- a/api/v3/Setting.php
+++ b/api/v3/Setting.php
@@ -28,8 +28,7 @@
 /**
  * This api exposes CiviCRM configuration settings.
  *
- * @package CiviCRM_APIv3_Core
- * @subpackage API_Settings
+ * @package CiviCRM_APIv3
  */
 
 /**
diff --git a/api/v3/SmsProvider.php b/api/v3/SmsProvider.php
index 95e4a96fc8..2be88fba14 100644
--- a/api/v3/SmsProvider.php
+++ b/api/v3/SmsProvider.php
@@ -26,10 +26,9 @@
  */
 
 /**
- * This api exposes CiviCRM sms_provider.
+ * This api exposes CiviCRM sms_provider records.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_sms_provider
  */
 
 /**
diff --git a/api/v3/Survey.php b/api/v3/Survey.php
index a6e1858e1f..9bd314aed3 100644
--- a/api/v3/Survey.php
+++ b/api/v3/Survey.php
@@ -26,10 +26,13 @@
  */
 
 /**
- * This api exposes CiviCRM survey.
+ * This api exposes CiviCRM survey/petition records.
+ *
+ * @note Campaign component must be enabled.
+ * @note There is no "petition" api.
+ * Surveys and petitions are the same basic object and this api is used for both.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Survey
  */
 
 
@@ -52,7 +55,7 @@ function civicrm_api3_survey_create($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_survey_create_spec(&$params) {
   $params['title']['api.required'] = 1;
@@ -62,9 +65,7 @@ function _civicrm_api3_survey_create_spec(&$params) {
  * Returns array of surveys  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
- *                       as null, all surveys will be returned
+ *   Array of properties. If empty, all records will be returned.
  *
  * @return array
  *   API result Array of matching surveys
diff --git a/api/v3/SurveyRespondant.php b/api/v3/SurveyRespondant.php
index f6bdd31e49..e834e2b1de 100644
--- a/api/v3/SurveyRespondant.php
+++ b/api/v3/SurveyRespondant.php
@@ -28,8 +28,9 @@
 /**
  * This api exposes CiviCRM Survey Respondant.
  *
+ * @deprecated - api currently not supported
+ *
  * @package CiviCRM_APIv3
- * @subpackage API_Survey
  */
 
 /**
diff --git a/api/v3/System.php b/api/v3/System.php
index e306cc1cd9..661e0caf34 100644
--- a/api/v3/System.php
+++ b/api/v3/System.php
@@ -26,11 +26,11 @@
  */
 
 /**
- * This api exposes CiviCRM system.
+ * This api exposes CiviCRM system functionality.
  *
- * @package CiviCRM_APIv3
- * @subpackage API_Domain
+ * Includes caching, logging, and checking system functionality.
  *
+ * @package CiviCRM_APIv3
  */
 
 /**
@@ -57,7 +57,7 @@ function civicrm_api3_system_flush($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_system_flush_spec(&$params) {
   $params['triggers'] = array('title' => 'rebuild triggers (boolean)');
@@ -79,7 +79,7 @@ function _civicrm_api3_system_check_spec(&$spec) {
 }
 
 /**
- * System.Check API.
+ * System Check API.
  *
  * @param array $params
  *
diff --git a/api/v3/SystemLog.php b/api/v3/SystemLog.php
index d7ff704455..3aef1ab364 100644
--- a/api/v3/SystemLog.php
+++ b/api/v3/SystemLog.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM SystemLog.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_SystemLog
- *
  */
 
 /**
diff --git a/api/v3/Tag.php b/api/v3/Tag.php
index e366f1063b..8c0567b27b 100644
--- a/api/v3/Tag.php
+++ b/api/v3/Tag.php
@@ -26,15 +26,18 @@
  */
 
 /**
- * This api exposes CiviCRM tag.
+ * This api exposes CiviCRM tags.
  *
- * @package CiviCRM_APIv3
- * @subpackage API_Tag
+ * Tags are used to classify CRM entities (including Contacts, Groups and Actions).
  *
+ * @note this api is for working with tags themselves. To add/remove tags from
+ * a contact or other entity, use the EntityTag api.
+ *
+ * @package CiviCRM_APIv3
  */
 
 /**
- * Add a Tag.
+ * Create or update a tag.
  *
  * Tags are used to classify CRM entities (including Contacts, Groups and Actions).
  *
diff --git a/api/v3/UFField.php b/api/v3/UFField.php
index 2d5c55ed86..b29527f5dc 100644
--- a/api/v3/UFField.php
+++ b/api/v3/UFField.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM profile field.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_UF
- *
  */
 
 /**
diff --git a/api/v3/UFGroup.php b/api/v3/UFGroup.php
index 300ce89fb6..209fcada12 100644
--- a/api/v3/UFGroup.php
+++ b/api/v3/UFGroup.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM profile group.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_UF
- *
  */
 
 /**
@@ -67,9 +65,7 @@ function civicrm_api3_uf_group_create($params) {
  * Returns array of uf groups (profiles) 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
- *                       as null, all surveys will be returned
+ *   Array of properties. If empty, all records will be returned.
  *
  * @return array
  *   Array of matching profiles
diff --git a/api/v3/UFJoin.php b/api/v3/UFJoin.php
index 9245725845..4964225e6a 100644
--- a/api/v3/UFJoin.php
+++ b/api/v3/UFJoin.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM user framework join.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_UF
- *
  */
 
 /**
@@ -53,7 +51,7 @@ function civicrm_api3_uf_join_create($params) {
  * Adjust Metadata for Create action.
  *
  * @param array $params
- *   Array or parameters determined by getfields.
+ *   Array of parameters determined by getfields.
  *
  * @todo - suspect module, weight don't need to be required - need to test
  */
diff --git a/api/v3/UFMatch.php b/api/v3/UFMatch.php
index 776b5eff36..795d9e8365 100644
--- a/api/v3/UFMatch.php
+++ b/api/v3/UFMatch.php
@@ -29,8 +29,6 @@
  * This api exposes CiviCRM user framework match.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_UF
- *
  */
 
 /**
@@ -63,7 +61,7 @@ function civicrm_api3_uf_match_create($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_uf_match_create_spec(&$params) {
   $params['contact_id']['api.required'] = 1;
diff --git a/api/v3/Website.php b/api/v3/Website.php
index 4075573e4e..8ce2cfc0b2 100644
--- a/api/v3/Website.php
+++ b/api/v3/Website.php
@@ -26,11 +26,9 @@
  */
 
 /**
- * This api exposes CiviCRM website.
+ * This api exposes CiviCRM website records.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_Website
- *
  */
 
 /**
@@ -57,7 +55,7 @@ function civicrm_api3_website_create($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_website_create_spec(&$params) {
   $params['contact_id']['api.required'] = 1;
diff --git a/api/v3/WordReplacement.php b/api/v3/WordReplacement.php
index e4aad58bcc..1398c82fa0 100644
--- a/api/v3/WordReplacement.php
+++ b/api/v3/WordReplacement.php
@@ -28,9 +28,10 @@
 /**
  * This api exposes CiviCRM word replacement.
  *
- * @package CiviCRM_APIv3
- * @subpackage API_WordReplacement
+ * Word-replacements are used to globally alter strings in the CiviCRM UI.
+ * Note that the original source string is always English, regardless of language settings.
  *
+ * @package CiviCRM_APIv3
  */
 
 /**
@@ -67,7 +68,7 @@ function civicrm_api3_word_replacement_create($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_word_replacement_create_spec(&$params) {
   unset($params['version']);
diff --git a/api/v3/utils.php b/api/v3/utils.php
index ffe7f8d873..988016a1f3 100644
--- a/api/v3/utils.php
+++ b/api/v3/utils.php
@@ -26,11 +26,9 @@
  */
 
 /**
- * File for CiviCRM APIv3 utilitity functions
+ * CiviCRM APIv3 utility functions.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_utils
- *
  */
 
 /**
@@ -1635,7 +1633,7 @@ function _civicrm_api3_validate_unique_key(&$params, &$fieldName) {
  * Replace the old set of entities (matching some given keys) with a new set of
  * entities (matching the same keys).
  *
- * Note: This will verify that 'values' is present, but it does not directly verify
+ * @note This will verify that 'values' is present, but it does not directly verify
  * any other parameters.
  *
  * @param string $entity
-- 
2.25.1