Merge pull request #9039 from totten/master-cleanup-phan

(NFC-ish) Multiple doc block cleanups
civicrm · Sep 17, 2016 · 6c65445 · 6c65445
2 parents b1af0c2 + 4b35017
commit 6c65445
Show file tree

Hide file tree

Showing 22 changed files with 53 additions and 45 deletions.
diff --git a/CRM/Batch/Form/Entry.php b/CRM/Batch/Form/Entry.php
@@ -263,7 +263,7 @@ public function buildQuickForm() {
    *   Posted values of the form.
    * @param array $files
    *   List of errors to be posted back to the form.
-   * @param array $self
+   * @param \CRM_Batch_Form_Entry $self
    *   Form object.
    *
    * @return array

diff --git a/CRM/Core/DAO.php b/CRM/Core/DAO.php
@@ -467,7 +467,7 @@ public function table() {
    *
    * @param bool $hook
    *
-   * @return $this
+   * @return CRM_Core_DAO
    */
   public function save($hook = TRUE) {
     if (!empty($this->id)) {

diff --git a/CRM/Core/Form.php b/CRM/Core/Form.php
@@ -67,16 +67,24 @@ class CRM_Core_Form extends HTML_QuickForm_Page {
   public $_defaults = array();
 
   /**
-   * The options passed into this form
+   * (QUASI-PROTECTED) The options passed into this form
+   *
+   * This field should marked `protected` and is not generally
+   * intended for external callers, but some edge-cases do use it.
+   *
    * @var mixed
    */
-  protected $_options = NULL;
+  public $_options = NULL;
 
   /**
-   * The mode of operation for this form
+   * (QUASI-PROTECTED) The mode of operation for this form
+   *
+   * This field should marked `protected` and is not generally
+   * intended for external callers, but some edge-cases do use it.
+   *
    * @var int
    */
-  protected $_action;
+  public $_action;
 
   /**
    * Available payment processors.

diff --git a/CRM/Event/Cart/BAO/Cart.php b/CRM/Event/Cart/BAO/Cart.php
@@ -11,7 +11,7 @@ class CRM_Event_Cart_BAO_Cart extends CRM_Event_Cart_DAO_Cart {
   /**
    * @param array $params
    *
-   * @return $this
+   * @return CRM_Event_Cart_BAO_Cart
    */
   public static function add(&$params) {
     $cart = new CRM_Event_Cart_BAO_Cart();
@@ -57,7 +57,7 @@ public function add_participant_to_cart($participant) {
   /**
    * @param array $params
    *
-   * @return $this
+   * @return CRM_Event_Cart_BAO_Cart
    * @throws Exception
    */
   public static function create($params) {

diff --git a/CRM/Extension/ClassLoader.php b/CRM/Extension/ClassLoader.php
@@ -73,7 +73,7 @@ public function __destruct() {
 
   /**
    * Registers this instance as an autoloader.
-   * @return $this
+   * @return CRM_Extension_ClassLoader
    */
   public function register() {
     // In pre-installation environments, don't bother with caching.

diff --git a/CRM/Report/Form.php b/CRM/Report/Form.php
@@ -88,7 +88,7 @@ class CRM_Report_Form extends CRM_Core_Form {
    *
    * @var array
    */
-  protected $_options = array();
+  public $_options = array();
 
   /**
    * By default most reports hide contact id.

diff --git a/CRM/Utils/Cache/Memcache.php b/CRM/Utils/Cache/Memcache.php
@@ -71,7 +71,7 @@ class CRM_Utils_Cache_Memcache implements CRM_Utils_Cache_Interface {
   /**
    * The actual memcache object.
    *
-   * @var resource
+   * @var Memcache
    */
   protected $_cache;
 

diff --git a/CRM/Utils/Cache/Memcached.php b/CRM/Utils/Cache/Memcached.php
@@ -72,7 +72,7 @@ class CRM_Utils_Cache_Memcached implements CRM_Utils_Cache_Interface {
   /**
    * The actual memcache object.
    *
-   * @var resource
+   * @var Memcached
    */
   protected $_cache;
 

diff --git a/CRM/Utils/SQL/Insert.php b/CRM/Utils/SQL/Insert.php
@@ -88,7 +88,7 @@ public function __construct($table) {
    *
    * @param array $columns
    *
-   * @return $this
+   * @return CRM_Utils_SQL_Insert
    * @throws \CRM_Core_Exception
    */
   public function columns($columns) {

diff --git a/CRM/Utils/SQL/Select.php b/CRM/Utils/SQL/Select.php
@@ -179,7 +179,7 @@ public function copy() {
    * @param CRM_Utils_SQL_Select $other
    * @param array|NULL $parts
    *   ex: 'joins', 'wheres'
-   * @return $this
+   * @return CRM_Utils_SQL_Select
    */
   public function merge($other, $parts = NULL) {
     if ($other === NULL) {
@@ -340,7 +340,7 @@ public function orderBy($exprs, $args = NULL) {
    * @param array|string $keys
    *   Key name, or an array of key-value pairs.
    * @param null|mixed $value
-   * @return $this
+   * @return \CRM_Utils_SQL_Select
    */
   public function param($keys, $value = NULL) {
     if ($this->mode === self::INTERPOLATE_AUTO) {
@@ -389,7 +389,7 @@ public function limit($limit, $offset = 0) {
    *   The name of the other table (which receives new data).
    * @param array $fields
    *   The fields to fill in the other table (in order).
-   * @return $this
+   * @return CRM_Utils_SQL_Select
    * @see insertIntoField
    */
   public function insertInto($table, $fields = array()) {
@@ -401,7 +401,7 @@ public function insertInto($table, $fields = array()) {
   /**
    * @param array $fields
    *   The fields to fill in the other table (in order).
-   * @return $this
+   * @return CRM_Utils_SQL_Select
    */
   public function insertIntoField($fields) {
     $fields = (array) $fields;
@@ -449,7 +449,7 @@ public function isEmpty($parts = NULL) {
    * In strict mode, unknown variables will generate exceptions.
    *
    * @param bool $strict
-   * @return $this
+   * @return CRM_Utils_SQL_Select
    */
   public function strict($strict = TRUE) {
     $this->strict = $strict;

diff --git a/Civi/API/ExternalBatch.php b/Civi/API/ExternalBatch.php
@@ -58,7 +58,7 @@ public function __construct($defaultParams = array()) {
    * @param string $entity
    * @param string $action
    * @param array $params
-   * @return $this
+   * @return ExternalBatch
    */
   public function addCall($entity, $action, $params = array()) {
     $params = array_merge($this->defaultParams, $params);

diff --git a/Civi/API/SelectQuery.php b/Civi/API/SelectQuery.php
@@ -318,7 +318,7 @@ public function run() {
 
   /**
    * @param \CRM_Utils_SQL_Select $sqlFragment
-   * @return $this
+   * @return SelectQuery
    */
   public function merge($sqlFragment) {
     $this->query->merge($sqlFragment);

diff --git a/Civi/ActionSchedule/Event/MappingRegisterEvent.php b/Civi/ActionSchedule/Event/MappingRegisterEvent.php
@@ -23,7 +23,7 @@ class MappingRegisterEvent extends Event {
    *
    * @param MappingInterface $mapping
    *   The new mapping.
-   * @return $this
+   * @return MappingRegisterEvent
    */
   public function register(MappingInterface $mapping) {
     $this->mappings[$mapping->getId()] = $mapping;

diff --git a/Civi/Core/Lock/LockManager.php b/Civi/Core/Lock/LockManager.php
@@ -107,7 +107,7 @@ public function getFactory($name) {
    * @param string|array $factory
    *   A callback. The callback should accept a $name parameter.
    *   Callbacks will be located using the resolver.
-   * @return $this
+   * @return LockManager
    * @see Resolver
    */
   public function register($pattern, $factory) {

diff --git a/Civi/Core/Paths.php b/Civi/Core/Paths.php
@@ -61,7 +61,7 @@ public function __construct() {
    *   Function which returns an array with keys:
    *    - path: string.
    *    - url: string.
-   * @return $this
+   * @return Paths
    */
   public function register($name, $factory) {
     $this->variableFactory[$name] = $factory;

diff --git a/Civi/Core/SettingsBag.php b/Civi/Core/SettingsBag.php
@@ -98,7 +98,7 @@ public function __construct($domainId, $contactId) {
    *
    * @param array $defaults
    *   Array(string $settingName => mixed $value).
-   * @return $this
+   * @return SettingsBag
    */
   public function loadDefaults($defaults) {
     $this->defaults = $defaults;
@@ -111,7 +111,7 @@ public function loadDefaults($defaults) {
    *
    * @param array $mandatory
    *   Array(string $settingName => mixed $value).
-   * @return $this
+   * @return SettingsBag
    */
   public function loadMandatory($mandatory) {
     $this->mandatory = $mandatory;
@@ -122,7 +122,7 @@ public function loadMandatory($mandatory) {
   /**
    * Load all explicit settings that apply to this domain or contact.
    *
-   * @return $this
+   * @return SettingsBag
    */
   public function loadValues() {
     // Note: Don't use DAO child classes. They require fields() which require
@@ -162,7 +162,7 @@ public function loadValues() {
    *
    * @param array $settings
    *   Array(string $settingName => mixed $settingValue).
-   * @return $this
+   * @return SettingsBag
    */
   public function add(array $settings) {
     foreach ($settings as $key => $value) {
@@ -251,7 +251,7 @@ public function hasExplict($key) {
    *
    * @param string $key
    *   The simple name of the setting.
-   * @return $this
+   * @return SettingsBag
    */
   public function revert($key) {
     // It might be better to DELETE (to avoid long-term leaks),
@@ -266,7 +266,7 @@ public function revert($key) {
    *   The simple name of the setting.
    * @param mixed $value
    *   The new, explicit value of the setting.
-   * @return $this
+   * @return SettingsBag
    */
   public function set($key, $value) {
     $this->setDb($key, $value);

diff --git a/Civi/Core/SettingsManager.php b/Civi/Core/SettingsManager.php
@@ -99,7 +99,7 @@ public function __construct($cache) {
    * Ensure that all defaults values are included with
    * all current and future bags.
    *
-   * @return $this
+   * @return SettingsManager
    */
   public function useDefaults() {
     if (!$this->useDefaults) {
@@ -130,7 +130,7 @@ public function useDefaults() {
    * If you call useMandatory multiple times, it will
    * re-scan the global $civicrm_setting.
    *
-   * @return $this
+   * @return SettingsManager
    */
   public function useMandatory() {
     $this->mandatory = NULL;
@@ -293,7 +293,7 @@ public static function parseMandatorySettings($civicrm_setting) {
   /**
    * Flush all in-memory and persistent caches related to settings.
    *
-   * @return $this
+   * @return SettingsManager
    */
   public function flush() {
     $this->mandatory = NULL;

diff --git a/Civi/Test/CiviEnvBuilder.php b/Civi/Test/CiviEnvBuilder.php
@@ -54,7 +54,7 @@ public function sqlFile($file) {
    *
    * @param string|array $names
    *   One or more extension names. You may use a wildcard '*'.
-   * @return $this
+   * @return CiviEnvBuilder
    */
   public function install($names) {
     return $this->addStep(new ExtensionsStep('install', $names));
@@ -66,7 +66,7 @@ public function install($names) {
    * @param string $dir
    *   The current test directory. We'll search for info.xml to
    *   see what this extension is.
-   * @return $this
+   * @return CiviEnvBuilder
    * @throws \CRM_Extension_Exception_ParseException
    */
   public function installMe($dir) {
@@ -78,7 +78,7 @@ public function installMe($dir) {
    *
    * @param string|array $names
    *   One or more extension names. You may use a wildcard '*'.
-   * @return $this
+   * @return CiviEnvBuilder
    */
   public function uninstall($names) {
     return $this->addStep(new ExtensionsStep('uninstall', $names));
@@ -90,7 +90,7 @@ public function uninstall($names) {
    * @param string $dir
    *   The current test directory. We'll search for info.xml to
    *   see what this extension is.
-   * @return $this
+   * @return CiviEnvBuilder
    * @throws \CRM_Extension_Exception_ParseException
    */
   public function uninstallMe($dir) {
@@ -165,7 +165,7 @@ protected function setSavedSignature($newSignature) {
    *   Forcibly execute the build, even if the configuration hasn't changed.
    *   This will slow-down the tests, but it may be appropriate for some very sloppy
    *   tests.
-   * @return $this
+   * @return CiviEnvBuilder
    */
   public function apply($force = FALSE) {
     $dbName = \Civi\Test::dsn('database');

diff --git a/Civi/Token/Event/TokenRegisterEvent.php b/Civi/Token/Event/TokenRegisterEvent.php
@@ -50,7 +50,7 @@ public function entity($entity) {
    *
    * @param array|string $paramsOrField
    * @param NULL|string $label
-   * @return $this
+   * @return TokenRegisterEvent
    */
   public function register($paramsOrField, $label = NULL) {
     if (is_array($paramsOrField)) {

diff --git a/Civi/Token/TokenProcessor.php b/Civi/Token/TokenProcessor.php
@@ -88,7 +88,7 @@ public function __construct($dispatcher, $context) {
    *   Ex: '<p>Hello {contact.name}</p>'.
    * @param string $format
    *   Ex: 'text/html'.
-   * @return $this
+   * @return TokenProcessor
    */
   public function addMessage($name, $value, $format) {
     $this->messages[$name] = array(
@@ -121,7 +121,7 @@ public function addRow() {
    *    - entity: string, e.g. "profile".
    *    - field: string, e.g. "viewUrl".
    *    - label: string, e.g. "Default Profile URL (View Mode)".
-   * @return $this
+   * @return TokenProcessor
    */
   public function addToken($params) {
     $key = $params['entity'] . '.' . $params['field'];

diff --git a/Civi/Token/TokenRow.php b/Civi/Token/TokenRow.php
@@ -71,7 +71,7 @@ public function __construct(TokenProcessor $tokenProcessor, $key) {
 
   /**
    * @param string $format
-   * @return $this
+   * @return TokenRow
    */
   public function format($format) {
     $this->format = $format;
@@ -84,7 +84,7 @@ public function format($format) {
    *
    * @param string|array $a
    * @param mixed $b
-   * @return $this
+   * @return TokenRow
    */
   public function context($a = NULL, $b = NULL) {
     if (is_array($a)) {
@@ -105,7 +105,7 @@ public function context($a = NULL, $b = NULL) {
    * @param string|array $a
    * @param string|array $b
    * @param mixed $c
-   * @return $this
+   * @return TokenRow
    */
   public function tokens($a = NULL, $b = NULL, $c = NULL) {
     if (is_array($a)) {
@@ -171,7 +171,7 @@ public function dbToken($tokenEntity, $tokenField, $baoName, $baoField, $fieldVa
    *
    * @param string $format
    *
-   * @return $this
+   * @return TokenRow
    */
   public function fill($format = NULL) {
     if ($format === NULL) {

diff --git a/api/v3/ReportTemplate.php b/api/v3/ReportTemplate.php
@@ -130,7 +130,7 @@ function _civicrm_api3_report_template_getrows($params) {
     $params['report_id'] = civicrm_api3('report_instance', 'getvalue', array('id' => $params['instance_id'], 'return' => 'report_id'));
   }
 
-  $class = civicrm_api3('option_value', 'getvalue', array(
+  $class = (string) civicrm_api3('option_value', 'getvalue', array(
     'option_group_name' => 'report_template',
     'return' => 'name',
     'value' => $params['report_id'],