From: eileenmcnaugton <eileen@fuzion.co.nz>
Date: Fri, 23 Oct 2015 05:02:15 +0000 (+1300)
Subject: comment fixes
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=70599df6b24c3f536ceb1dadc23e6823b580c558;p=civicrm-core.git

comment fixes
---

diff --git a/CRM/Activity/Page/Tab.php b/CRM/Activity/Page/Tab.php
index 77b218ddd3..3289477025 100644
--- a/CRM/Activity/Page/Tab.php
+++ b/CRM/Activity/Page/Tab.php
@@ -56,6 +56,11 @@ class CRM_Activity_Page_Tab extends CRM_Core_Page {
     $this->ajaxResponse['tabCount'] = CRM_Contact_BAO_Contact::getCountComponent('activity', $this->_contactId);
   }
 
+  /**
+   * Edit tab.
+   *
+   * @return mixed
+   */
   public function edit() {
     // used for ajax tabs
     $context = CRM_Utils_Request::retrieve('context', 'String', $this);
diff --git a/CRM/Activity/Tokens.php b/CRM/Activity/Tokens.php
index 1e7207ea61..c7643f70c9 100644
--- a/CRM/Activity/Tokens.php
+++ b/CRM/Activity/Tokens.php
@@ -55,6 +55,13 @@ class CRM_Activity_Tokens extends \Civi\Token\AbstractTokenSubscriber {
     ));
   }
 
+  /**
+   * Check is active.
+   *
+   * @param \Civi\Token\TokenProcessor $processor
+   *
+   * @return bool
+   */
   public function checkActive(\Civi\Token\TokenProcessor $processor) {
     // Extracted from scheduled-reminders code. See the class description.
     return
diff --git a/CRM/Contact/BAO/Query.php b/CRM/Contact/BAO/Query.php
index cc0c32fb06..e3a738bbfe 100644
--- a/CRM/Contact/BAO/Query.php
+++ b/CRM/Contact/BAO/Query.php
@@ -5291,6 +5291,15 @@ SELECT COUNT( conts.total_amount ) as cancel_count,
     }
   }
 
+  /**
+   * Calculate date from age.
+   *
+   * @param string $asofDate
+   * @param int $age
+   * @param string $type
+   *
+   * @return string
+   */
   public static function calcDateFromAge($asofDate, $age, $type) {
     $date = new DateTime($asofDate);
     if ($type == "min") {
diff --git a/CRM/Contribute/Tokens.php b/CRM/Contribute/Tokens.php
index 2679f7a403..71f0926711 100644
--- a/CRM/Contribute/Tokens.php
+++ b/CRM/Contribute/Tokens.php
@@ -57,6 +57,11 @@ class CRM_Contribute_Tokens extends \Civi\Token\AbstractTokenSubscriber {
     );
   }
 
+  /**
+   * Get alias tokens.
+   *
+   * @return array
+   */
   protected function getAliasTokens() {
     return array(
       'id' => 'contribution_id',
diff --git a/CRM/Core/Exception.php b/CRM/Core/Exception.php
index 0e24e5f694..b80536dc8d 100644
--- a/CRM/Core/Exception.php
+++ b/CRM/Core/Exception.php
@@ -41,7 +41,9 @@ class CRM_Core_Exception extends PEAR_Exception {
   private $errorData = array();
 
   /**
-   * @param $message
+   * Class constructor.
+   *
+   * @param string $message
    * @param int $error_code
    * @param array $errorData
    * @param null $previous
@@ -52,20 +54,27 @@ class CRM_Core_Exception extends PEAR_Exception {
   }
 
   /**
-   * custom string representation of object.
+   * Custom string representation of object.
+   *
    * @return string
    */
   public function __toString() {
     return __CLASS__ . ": [{$this->errorData['error_code']}: {$this->message}\n";
   }
 
+  /**
+   * Get error code.
+   *
+   * @return mixed
+   */
   public function getErrorCode() {
     return $this->errorData['error_code'];
   }
 
   /**
-   * Return specific error information that can be used for more detailed
-   * error messages or translation.
+   * Return specific error information.
+   *
+   * (Can be used for more detailed error messages or translation.)
    *
    * This method may be overridden in child exception classes in order
    * to add functionality not present in PEAR_Exception and is a placeholder
diff --git a/CRM/Event/Tokens.php b/CRM/Event/Tokens.php
index 63fa6ed34d..48949e7be0 100644
--- a/CRM/Event/Tokens.php
+++ b/CRM/Event/Tokens.php
@@ -40,6 +40,9 @@
  */
 class CRM_Event_Tokens extends \Civi\Token\AbstractTokenSubscriber {
 
+  /**
+   * Class constructor.
+   */
   public function __construct() {
     parent::__construct('event', array(
       'event_type' => ts('Event Type'),
@@ -59,6 +62,13 @@ class CRM_Event_Tokens extends \Civi\Token\AbstractTokenSubscriber {
     ));
   }
 
+  /**
+   * Check something about being active.
+   *
+   * @param \Civi\Token\TokenProcessor $processor
+   *
+   * @return bool
+   */
   public function checkActive(\Civi\Token\TokenProcessor $processor) {
     // Extracted from scheduled-reminders code. See the class description.
     return
diff --git a/CRM/Member/Tokens.php b/CRM/Member/Tokens.php
index e17c4ca380..5c010e39fd 100644
--- a/CRM/Member/Tokens.php
+++ b/CRM/Member/Tokens.php
@@ -40,6 +40,9 @@
  */
 class CRM_Member_Tokens extends \Civi\Token\AbstractTokenSubscriber {
 
+  /**
+   * Class constructor.
+   */
   public function __construct() {
     parent::__construct('membership', array(
       'fee' => ts('Membership Fee'),
diff --git a/CRM/Report/Form/ActivitySummary.php b/CRM/Report/Form/ActivitySummary.php
index 13dc9acfaf..d31d5d8028 100644
--- a/CRM/Report/Form/ActivitySummary.php
+++ b/CRM/Report/Form/ActivitySummary.php
@@ -277,6 +277,11 @@ class CRM_Report_Form_ActivitySummary extends CRM_Report_Form {
     $this->_select = "SELECT " . implode(', ', $select) . " ";
   }
 
+  /**
+   * Generate from clause.
+   *
+   * @param bool|FALSE $durationMode
+   */
   public function from($durationMode = FALSE) {
     $activityContacts = CRM_Core_OptionGroup::values('activity_contacts', FALSE, FALSE, FALSE, NULL, 'name');
     $assigneeID = CRM_Utils_Array::key('Activity Assignees', $activityContacts);
@@ -334,6 +339,11 @@ class CRM_Report_Form_ActivitySummary extends CRM_Report_Form {
     }
   }
 
+  /**
+   * Generate where clause.
+   *
+   * @param bool|FALSE $durationMode
+   */
   public function where($durationMode = FALSE) {
     $optionGroupClause = '';
     if (!$durationMode) {
diff --git a/CRM/Report/Form/Contact/Relationship.php b/CRM/Report/Form/Contact/Relationship.php
index 2824d1d9ab..23bff4e533 100644
--- a/CRM/Report/Form/Contact/Relationship.php
+++ b/CRM/Report/Form/Contact/Relationship.php
@@ -44,6 +44,9 @@ class CRM_Report_Form_Contact_Relationship extends CRM_Report_Form {
   );
   public $_drilldownReport = array('contact/detail' => 'Link to Detail Report');
 
+  /**
+   * Class constructor.
+   */
   public function __construct() {
 
     $contact_type = CRM_Contact_BAO_ContactType::getSelectElements(FALSE, TRUE, '_');
diff --git a/CRM/Upgrade/Page/Upgrade.php b/CRM/Upgrade/Page/Upgrade.php
index e2626b5e71..1abf6554bb 100644
--- a/CRM/Upgrade/Page/Upgrade.php
+++ b/CRM/Upgrade/Page/Upgrade.php
@@ -37,6 +37,11 @@ class CRM_Upgrade_Page_Upgrade extends CRM_Core_Page {
     parent::preProcess();
   }
 
+  /**
+   * Run upgrade.
+   *
+   * @throws \Exception
+   */
   public function run() {
     // lets get around the time limit issue if possible for upgrades
     if (!ini_get('safe_mode')) {
diff --git a/CRM/Utils/Check/Message.php b/CRM/Utils/Check/Message.php
index dbaf7ed92b..70688ac9e3 100644
--- a/CRM/Utils/Check/Message.php
+++ b/CRM/Utils/Check/Message.php
@@ -66,6 +66,8 @@ class CRM_Utils_Check_Message {
   private $isVisible;
 
   /**
+   * Class constructor.
+   *
    * @param string $name
    *   Symbolic name for the check.
    * @param string $message
@@ -89,6 +91,8 @@ class CRM_Utils_Check_Message {
   }
 
   /**
+   * Get name.
+   *
    * @return string
    */
   public function getName() {
@@ -96,6 +100,8 @@ class CRM_Utils_Check_Message {
   }
 
   /**
+   * Get message.
+   *
    * @return string
    */
   public function getMessage() {
@@ -110,6 +116,8 @@ class CRM_Utils_Check_Message {
   }
 
   /**
+   * Get level.
+   *
    * @return string
    * @see Psr\Log\LogLevel
    */
@@ -126,7 +134,8 @@ class CRM_Utils_Check_Message {
   }
 
   /**
-   * Set optional additional help text
+   * Set optional additional help text.
+   *
    * @param string $help
    */
   public function addHelp($help) {
@@ -134,6 +143,8 @@ class CRM_Utils_Check_Message {
   }
 
   /**
+   * Convert to array.
+   *
    * @return array
    */
   public function toArray() {
@@ -150,10 +161,20 @@ class CRM_Utils_Check_Message {
     return $array;
   }
 
+  /**
+   * Getter for is visible.
+   *
+   * @return bool
+   */
   public function isVisible() {
     return $this->isVisible;
   }
 
+  /**
+   * Seter for is visible.
+   *
+   * @param bool $isVisible
+   */
   public function setVisible($isVisible) {
     $this->isVisible = $isVisible ? 1 : 0;
   }
diff --git a/CRM/Utils/Migrate/Export.php b/CRM/Utils/Migrate/Export.php
index 38d9edb0b3..f2230d7adc 100644
--- a/CRM/Utils/Migrate/Export.php
+++ b/CRM/Utils/Migrate/Export.php
@@ -50,6 +50,9 @@ class CRM_Utils_Migrate_Export {
    */
   protected $_xml;
 
+  /**
+   * Class constructor.
+   */
   public function __construct() {
     $this->_xml = array(
       'customGroup' => array(
diff --git a/CRM/Utils/Migrate/ImportJSON.php b/CRM/Utils/Migrate/ImportJSON.php
index 33ac324a22..ffaba2f85e 100644
--- a/CRM/Utils/Migrate/ImportJSON.php
+++ b/CRM/Utils/Migrate/ImportJSON.php
@@ -36,13 +36,18 @@ class CRM_Utils_Migrate_ImportJSON {
 
   protected $_saveMapping;
 
+  /**
+   * Class constructor.
+   */
   public function __construct() {
     $this->_lookupCache = array();
     $this->_saveMapping = array();
   }
 
   /**
-   * @param $file
+   * Run import.
+   *
+   * @param string $file
    */
   public function run($file) {
     $json = file_get_contents($file);
diff --git a/CRM/Utils/SQL/Insert.php b/CRM/Utils/SQL/Insert.php
index 5e13384e32..627473df14 100644
--- a/CRM/Utils/SQL/Insert.php
+++ b/CRM/Utils/SQL/Insert.php
@@ -61,6 +61,14 @@ class CRM_Utils_SQL_Insert {
     $this->rows = array();
   }
 
+  /**
+   * Get columns.
+   *
+   * @param array $columns
+   *
+   * @return $this
+   * @throws \CRM_Core_Exception
+   */
   public function columns($columns) {
     if ($this->columns !== NULL) {
       throw new CRM_Core_Exception("Column order already specified.");
@@ -70,7 +78,10 @@ class CRM_Utils_SQL_Insert {
   }
 
   /**
+   * Get rows.
+   *
    * @param array $rows
+   *
    * @return CRM_Utils_SQL_Insert
    */
   public function rows($rows) {
@@ -81,7 +92,10 @@ class CRM_Utils_SQL_Insert {
   }
 
   /**
+   * Get row.
+   *
    * @param array $row
+   *
    * @return CRM_Utils_SQL_Insert
    * @throws CRM_Core_Exception
    */
@@ -109,6 +123,7 @@ class CRM_Utils_SQL_Insert {
    * Use REPLACE INTO instead of INSERT INTO.
    *
    * @param bool $asReplace
+   *
    * @return CRM_Utils_SQL_Insert
    */
   public function usingReplace($asReplace = TRUE) {
@@ -117,7 +132,10 @@ class CRM_Utils_SQL_Insert {
   }
 
   /**
+   * Escape string.
+   *
    * @param string|NULL $value
+   *
    * @return string
    *   SQL expression, e.g. "it\'s great" (with-quotes) or NULL (without-quotes)
    */
@@ -126,6 +144,8 @@ class CRM_Utils_SQL_Insert {
   }
 
   /**
+   * Convert to SQL.
+   *
    * @return string
    *   SQL statement
    */
diff --git a/CRM/Utils/System.php b/CRM/Utils/System.php
index a19f229f4b..f9071770d1 100644
--- a/CRM/Utils/System.php
+++ b/CRM/Utils/System.php
@@ -169,8 +169,7 @@ class CRM_Utils_System {
   }
 
   /**
-   * If we are using a theming system, invoke theme, else just print the
-   * content.
+   * If we are using a theming system, invoke theme, else just print the content.
    *
    * @param string $content
    *   The content that will be themed.
@@ -194,6 +193,7 @@ class CRM_Utils_System {
    * Generate a query string if input is an array.
    *
    * @param array|string $query
+   *
    * @return string
    */
   public static function makeQueryString($query) {
@@ -224,6 +224,7 @@ class CRM_Utils_System {
    * @param bool $htmlize
    * @param bool $frontend
    * @param bool $forceBackend
+   *
    * @return string
    *   An HTML string containing a link to the given path.
    */
@@ -248,11 +249,13 @@ class CRM_Utils_System {
   }
 
   /**
-   * @param $text
-   * @param null $path
-   * @param null $query
+   * Get href.
+   *
+   * @param string $text
+   * @param string $path
+   * @param string|array $query
    * @param bool $absolute
-   * @param null $fragment
+   * @param string $fragment
    * @param bool $htmlize
    * @param bool $frontend
    * @param bool $forceBackend
@@ -268,6 +271,8 @@ class CRM_Utils_System {
   }
 
   /**
+   * Permission denied.
+   *
    * @return mixed
    */
   public static function permissionDenied() {
@@ -276,6 +281,8 @@ class CRM_Utils_System {
   }
 
   /**
+   * Log out.
+   *
    * @return mixed
    */
   public static function logout() {
@@ -284,7 +291,7 @@ class CRM_Utils_System {
   }
 
   /**
-   * this is a very drupal specific function for now.
+   * This is a very drupal specific function for now.
    */
   public static function updateCategories() {
     $config = CRM_Core_Config::singleton();
@@ -294,7 +301,7 @@ class CRM_Utils_System {
   }
 
   /**
-   * What menu path are we currently on. Called for the primary tpl
+   * What menu path are we currently on. Called for the primary tpl.
    *
    * @return string
    *   the current menu path
@@ -305,7 +312,7 @@ class CRM_Utils_System {
   }
 
   /**
-   * called from a template to compose a url.
+   * Called from a template to compose a url.
    *
    * @param array $params
    *   List of parameters.
@@ -345,7 +352,7 @@ class CRM_Utils_System {
   /**
    * Figures and sets the userContext.
    *
-   * Uses the referer if valid else uses the default.
+   * Uses the referrer if valid else uses the default.
    *
    * @param array $names
    *   Referrer should match any str in this array.
@@ -460,7 +467,7 @@ class CRM_Utils_System {
   /**
    * Append an additional breadcrumb tag to the existing breadcrumbs.
    *
-   * @param $breadCrumbs
+   * @param string $breadCrumbs
    */
   public static function appendBreadCrumb($breadCrumbs) {
     $config = CRM_Core_Config::singleton();
@@ -488,7 +495,7 @@ class CRM_Utils_System {
   /**
    * Determine the post URL for a form.
    *
-   * @param $action
+   * @param int $action
    *   The default action if one is pre-specified.
    *
    * @return string
@@ -528,6 +535,8 @@ class CRM_Utils_System {
   }
 
   /**
+   * Authenticate key.
+   *
    * @param bool $abort
    *   (optional) Whether to exit; defaults to true.
    *
@@ -573,9 +582,11 @@ class CRM_Utils_System {
   }
 
   /**
+   * Authenticate script.
+   *
    * @param bool $abort
-   * @param null $name
-   * @param null $pass
+   * @param string $name
+   * @param string $pass
    * @param bool $storeInSession
    * @param bool $loadCMSBootstrap
    * @param bool $requireKey
@@ -639,7 +650,7 @@ class CRM_Utils_System {
    * @param string $password
    *   The password.
    * @param bool $loadCMSBootstrap
-   * @param $realPath
+   * @param string $realPath
    *
    * @return false|array
    */
@@ -679,8 +690,9 @@ class CRM_Utils_System {
   /**
    * Determine whether a value is null-ish.
    *
-   * @param $value
+   * @param mixed $value
    *   The value to check for null.
+   *
    * @return bool
    */
   public static function isNull($value) {
@@ -707,6 +719,7 @@ class CRM_Utils_System {
    *   The credit card number to obscure.
    * @param int $keep
    *   (optional) The number of digits to preserve unmodified.
+   *
    * @return string
    *   The obscured credit card number.
    */
@@ -771,7 +784,9 @@ class CRM_Utils_System {
   }
 
   /**
-   * @param $title
+   * Do something no-one bothered to document.
+   *
+   * @param string $title
    *   (optional)
    *
    * @return mixed|string
@@ -791,9 +806,11 @@ class CRM_Utils_System {
   }
 
   /**
+   * Download something or other.
+   *
    * @param string $name
    * @param string $mimeType
-   * @param $buffer
+   * @param string $buffer
    * @param string $ext
    * @param bool $output
    * @param string $disposition
@@ -862,6 +879,7 @@ class CRM_Utils_System {
    *
    * @param string $url
    *   The URL to operate on.
+   *
    * @return string
    *   The fixed URL.
    */
@@ -927,6 +945,7 @@ class CRM_Utils_System {
    * @param string $separator
    * @param string $string
    * @param int $limit
+   *
    * @return string[]
    */
   public static function explode($separator, $string, $limit) {
@@ -938,6 +957,8 @@ class CRM_Utils_System {
   }
 
   /**
+   * Check url.
+   *
    * @param string $url
    *   The URL to check.
    * @param bool $addCookie
@@ -969,6 +990,7 @@ class CRM_Utils_System {
    * @param bool $abort
    *   (optional) Whether to fatally abort if the version requirement is not
    *   met. Defaults to TRUE.
+   *
    * @return bool
    *   Returns TRUE if the requirement is met, FALSE if the requirement is not
    *   met and we're not aborting due to the failed requirement. If $abort is
@@ -989,7 +1011,9 @@ class CRM_Utils_System {
   }
 
   /**
-   * @param $string
+   * Format wiki url.
+   *
+   * @param string $string
    * @param bool $encode
    *
    * @return string
@@ -1009,6 +1033,8 @@ class CRM_Utils_System {
   }
 
   /**
+   * Encode url.
+   *
    * @param string $url
    *
    * @return null|string
@@ -1493,6 +1519,11 @@ class CRM_Utils_System {
     return $config->userSystem->getLoggedInUfID();
   }
 
+  /**
+   * Get Base CMS url.
+   *
+   * @return mixed|string
+   */
   public static function baseCMSURL() {
     static $_baseURL = NULL;
     if (!$_baseURL) {
diff --git a/api/v3/Cxn.php b/api/v3/Cxn.php
index 430446c8ec..199d091634 100644
--- a/api/v3/Cxn.php
+++ b/api/v3/Cxn.php
@@ -103,6 +103,11 @@ function civicrm_api3_cxn_register($params) {
   return $result;
 }
 
+/**
+ * Adjust metadata for cxn unregister.
+ *
+ * @param array $spec
+ */
 function _civicrm_api3_cxn_unregister_spec(&$spec) {
   $daoFields = CRM_Cxn_DAO_Cxn::fields();
   $spec['cxn_guid'] = $daoFields['cxn_guid'];
@@ -167,6 +172,11 @@ function _civicrm_api3_cxn_parseCxnId($params) {
   return $cxnId;
 }
 
+/**
+ * Adjust metadata for cxn get action.
+ *
+ * @param array $spec
+ */
 function _civicrm_api3_cxn_get_spec(&$spec) {
   // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
   unset($spec['secret']);
diff --git a/api/v3/Mailing.php b/api/v3/Mailing.php
index 8dd5578752..7463032416 100755
--- a/api/v3/Mailing.php
+++ b/api/v3/Mailing.php
@@ -157,12 +157,25 @@ function _civicrm_api3_mailing_create_spec(&$params) {
   }
 }
 
+/**
+ * Adjust metadata for clone spec action.
+ *
+ * @param array $spec
+ */
 function _civicrm_api3_mailing_clone_spec(&$spec) {
   $mailingFields = CRM_Mailing_DAO_Mailing::fields();
   $spec['id'] = $mailingFields['id'];
   $spec['id']['api.required'] = 1;
 }
 
+/**
+ * Clone mailing.
+ *
+ * @param array $params
+ *
+ * @return array
+ * @throws \CiviCRM_API3_Exception
+ */
 function civicrm_api3_mailing_clone($params) {
   $BLACKLIST = array(
     'id',
diff --git a/api/v3/Setting.php b/api/v3/Setting.php
index 09e46fb663..2817f11643 100644
--- a/api/v3/Setting.php
+++ b/api/v3/Setting.php
@@ -144,6 +144,14 @@ function _civicrm_api3_setting_getdefaults_spec(&$params) {
   );
 }
 
+/**
+ * Get options for settings.
+ *
+ * @param array $params
+ *
+ * @return array
+ * @throws \API_Exception
+ */
 function civicrm_api3_setting_getoptions($params) {
   $specs = CRM_Core_BAO_Setting::getSettingSpecification();