refs #4126 added some documentation and removed some unused methods

4 files changed, 150 insertions, 35 deletions

diff --git a/core/Settings/Manager.php b/core/Settings/Manager.php
index 3e5c77c237..5c4a1f8174 100644
--- a/core/Settings/Manager.php
+++ b/core/Settings/Manager.php
@@ -12,7 +12,7 @@
 namespace Piwik\Settings;
 
 /**
- * Settings manager
+ * Settings manager.
  *
  * @package Piwik
  * @subpackage Settings
@@ -22,6 +22,10 @@ class Manager
     private static $settings = array();
 
     /**
+     * Returns all available plugin settings. A plugin has to specify a file named `settings.php` containing a class
+     * named `Settings` that extends `Piwik\Plugin\Settings` in order to be considered as a plugin setting. Otherwise
+     * the settings for a plugin won't be available.
+     *
      * @return \Piwik\Plugin\Settings[]
      */
     public static function getAllPluginSettings()
@@ -41,6 +45,11 @@ class Manager
         return static::$settings;
     }
 
+    /**
+     * Removes all settings made for a specific plugin. Useful while uninstalling a plugin.
+     *
+     * @param string $pluginName
+     */
     public static function cleanupPluginSettings($pluginName)
     {
         $settings = self::getPluginSettingsClass($pluginName);
@@ -50,14 +59,9 @@ class Manager
         }
     }
 
-    public static function cleanupUserSettings($userLogin)
-    {
-        foreach (static::getAllPluginSettings() as $setting) {
-            $setting->removeAllSettingsForUser($userLogin);
-        }
-    }
-
     /**
+     * Detects whether there are plugin settings available that the current user can change.
+     *
      * @return bool
      */
     public static function hasPluginSettingsForCurrentUser()
@@ -75,7 +79,10 @@ class Manager
     }
 
     /**
-     * @param $pluginName
+     * Tries to find a settings class for the specified plugin name. Returns null in case the plugin does not specify
+     * any settings, an instance of the settings class otherwise.
+     *
+     * @param string $pluginName
      * @return \Piwik\Plugin\Settings|null
      */
     private static function getPluginSettingsClass($pluginName)
diff --git a/core/Settings/Setting.php b/core/Settings/Setting.php
index 4cc443b532..43bbd49149 100644
--- a/core/Settings/Setting.php
+++ b/core/Settings/Setting.php
@@ -15,23 +15,113 @@ use Piwik\Piwik;
 use Piwik\Plugin\Settings;
 
 /**
- * Settings manager
+ * Base setting class. Extend this class to define your own type of setting.
  *
  * @package Piwik
  * @subpackage Settings
  */
 abstract class Setting
 {
-    public $type            = Settings::TYPE_STRING;
-    public $field           = Settings::FIELD_TEXT;
+    /**
+     * Defines the PHP type of the setting. Before the value is saved it will be cased depending on this setting.
+     *
+     * @var string
+     */
+    public $type = Settings::TYPE_STRING;
+
+    /**
+     * Defines which field type should be displayed on the setting page.
+     *
+     * @var string
+     */
+    public $field = Settings::FIELD_TEXT;
+
+    /**
+     * An array of field attributes that will be added as HTML attributes to the HTML form field.
+     * Example: `array('size' => 3)`. Please note the attributes will be escaped for security.
+     * @var array
+     */
     public $fieldAttributes = array();
-    public $fieldOptions    = null;
+
+    /**
+     * Defines available options in case you want to give the user the possibility to select a value (in a select
+     * field). For instance `array('nb_visits' => 'Visits', 'nb_actions' => 'Actions')`.
+     * In case field options are set and you do not specify a validator, a validator will be automatically added
+     * to check the set value is one of the defined array keys. An error will be triggered in case a user tries to
+     * save a value that is not allowed.
+     *
+     * @var null|array
+     */
+    public $fieldOptions = null;
+
+    /**
+     * Defines an introduction that will be displayed as a text block above the setting.
+     * @var null|string
+     */
     public $introduction    = null;
+
+    /**
+     * Defines a description that will be displayed underneath the setting title. It should be just a short description
+     * what the setting is about.
+     * @var null|string
+     */
     public $description     = null;
+
+    /**
+     * The inline help will be displayed in a separate help box next to the setting and can contain some further
+     * explanations about the setting. For instance if only some specific characters are allowed to can explain them
+     * here.
+     * @var null|string
+     */
     public $inlineHelp      = null;
-    public $filter          = null;
+
+    /**
+     * If a closure is set, the closure will be executed before a new value is saved. In case a user tries to save an
+     * invalid value just throw an exception containing a useful message. Example:
+     * ```
+     * function ($value, Setting $setting) {
+     *     if ($value > 60) {
+     *         throw new \Exception('Value has to be at <= 60 as an hour has only 60 minutes');
+     *     }
+     * }
+     * ```
+     *
+     * @var null|\Closure
+     */
     public $validate        = null;
+
+    /**
+     * You can define a filter closure that is executed after a value is validated. In case you define a value, the
+     * property `$type` has no effect. That means the value won't be casted to the specified type. It is on your own to
+     * cast or format the value on your needs. Make sure to return a value at the end of the function as this value
+     * will be saved. Example:
+     * ```
+     * function ($value, Setting $setting) {
+     *     if ($value > 30) {
+     *         $value = 30;
+     *     }
+     *
+     *     return (int) $value;
+     * }
+     * ```
+     *
+     * @var null|\Closure
+     */
+    public $filter          = null;
+
+    /**
+     * Defines the default value for this setting that will be used in case the user has not specified a value so far.
+     * The default value won't be casted so make sure to define an appropriate value.
+     *
+     * @var mixed
+     */
     public $defaultValue    = null;
+
+    /**
+     * Defines the title of the setting which will be visible to the user. For instance `Refresh Interval`
+     *
+     * @var string
+     */
     public $title           = '';
 
     protected $key;
@@ -43,10 +133,17 @@ abstract class Setting
         return $this->displayedForCurrentUser;
     }
 
+    /**
+     * Creates a new setting.
+     *
+     * @param string $name    The name of the setting, only alnum characters are allowed. For instance `refreshInterval`
+     * @param string $title   The title of the setting which will be visible to the user. For instance `Refresh Interval`
+     *
+     * @throws \Exception     In case the name contains invalid characters.
+     */
     public function __construct($name, $title)
     {
         if (!ctype_alnum($name)) {
-            // TODO escape name?
             $msg = sprintf('The setting name %s is not valid. Only alpha and numerical characters are allowed', $name);
             throw new \Exception($msg);
         }
@@ -61,11 +158,6 @@ abstract class Setting
         return $this->name;
     }
 
-    public function getTitle()
-    {
-        return $this->title;
-    }
-
     /**
      * Returns the key under which property name the setting will be stored.
      *
@@ -76,11 +168,6 @@ abstract class Setting
         return $this->key;
     }
 
-    public function hasKey($key)
-    {
-        return $key == $this->getKey();
-    }
-
     public function getDefaultType($field)
     {
         $defaultTypes = array(
diff --git a/core/Settings/SystemSetting.php b/core/Settings/SystemSetting.php
index f9ce5614fb..facca5b588 100644
--- a/core/Settings/SystemSetting.php
+++ b/core/Settings/SystemSetting.php
@@ -14,10 +14,13 @@ namespace Piwik\Settings;
 use Piwik\Piwik;
 
 /**
- * System Setting.
+ * System wide setting. Only the super user can change this kind of settings and the value of the setting effects all
+ * users.
  *
  * @package Piwik
  * @subpackage Settings
+ *
+ * @api
  */
 class SystemSetting extends Setting
 {
@@ -25,7 +28,7 @@ class SystemSetting extends Setting
     {
         parent::__construct($name, $title);
 
-        $this->displayedForCurrentUser = !Piwik::isUserIsAnonymous();
+        $this->displayedForCurrentUser = Piwik::isUserIsSuperUser();
     }
 
 }
diff --git a/core/Settings/UserSetting.php b/core/Settings/UserSetting.php
index 7ff3aaf399..c207e2e805 100644
--- a/core/Settings/UserSetting.php
+++ b/core/Settings/UserSetting.php
@@ -14,15 +14,23 @@ use Piwik\Common;
 use Piwik\Piwik;
 
 /**
- * Per User Setting.
+ * Per user setting. Each user will be able to change this setting but each user can set a different value. That means
+ * a changed value does not effect any other users.
  *
  * @package Piwik
  * @subpackage Settings
+ *
+ * @api
  */
 class UserSetting extends Setting
 {
     private $userLogin = null;
 
+    /**
+     * @param string $name
+     * @param string $title
+     * @param null|string $userLogin  Defaults to the current user login.
+     */
     public function __construct($name, $title, $userLogin = null)
     {
         parent::__construct($name, $title);
@@ -32,13 +40,6 @@ class UserSetting extends Setting
         $this->displayedForCurrentUser = !Piwik::isUserIsAnonymous();
     }
 
-    public function hasKey($key, $userLogin = null)
-    {
-        $thisKey = $this->buildUserSettingName($key, $userLogin);
-
-        return ($key == $thisKey);
-    }
-
     private function buildUserSettingName($name, $userLogin = null)
     {
         if (empty($userLogin)) {
@@ -58,14 +59,31 @@ class UserSetting extends Setting
         return $name . $appendix;
     }
 
+    /**
+     * Sets (overwrites) the userLogin.
+     *
+     * @param $userLogin
+     */
     public function setUserLogin($userLogin)
     {
         $this->userLogin = $userLogin;
         $this->key       = $this->buildUserSettingName($this->name, $userLogin);
     }
 
+    /**
+     * Remove all stored settings of the given userLogin. This is important to cleanup all settings for a user once he
+     * is deleted. Otherwise a user could register with the same name afterwards and see the previous user's settings.
+     *
+     * @param string $userLogin
+     *
+     * @throws \Exception In case the userLogin is empty.
+     */
     public static function removeAllUserSettingsForUser($userLogin)
     {
+        if (empty($userLogin)) {
+            throw new \Exception('No userLogin specified');
+        }
+
         $pluginsSettings = Manager::getAllPluginSettings();
 
         foreach ($pluginsSettings as $pluginSettings) {