MDL-30982 Documenting some parts of backup settings machinery

backup/moodle2/backup_settingslib.php

@@ -39,6 +39,15 @@ class backup_generic_setting extends root_backup_setting {}
  */
 class backup_filename_setting extends backup_generic_setting {
 
+    /**
+     * Instantiates a setting object
+     *
+     * @param string $name Name of the setting
+     * @param string $vtype Type of the setting, eg {@link base_setting::IS_TEXT}
+     * @param mixed $value Value of the setting
+     * @param bool $visibility Is the setting visible in the UI, eg {@link base_setting::VISIBLE}
+     * @param int $status Status of the setting with regards to the locking, eg {@link base_setting::NOT_LOCKED}
+     */
     public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
         parent::__construct($name, $vtype, $value, $visibility, $status);
     }

backup/util/settings/backup_setting.class.php

@@ -16,16 +16,18 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * @package    moodlecore
- * @subpackage backup-settings
- * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * Defines backup_setting class
+ *
+ * @package     core_backup
+ * @category    backup
+ * @copyright   2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+defined('MOODLE_INTERNAL') || die();
+
 /**
- * This abstract class defines one backup_setting
- *
- * TODO: Finish phpdocs
+ * Parent class for all backup settings
  */
 abstract class backup_setting extends base_setting implements checksumable {
 
@@ -35,12 +37,12 @@ abstract class backup_setting extends base_setting implements checksumable {
     const SECTION_LEVEL  = 9;
     const ACTIVITY_LEVEL = 13;
 
-    /**
-     * One of the above constants
-     * @var {int}
-     */
-    protected $level;  // level of the setting
+    /** @var int Level of the setting, eg {@link self::ROOT_LEVEL} */
+    protected $level;
 
+    /**
+     * {@inheritdoc}
+     */
     public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
         parent::__construct($name, $vtype, $value, $visibility, $status);
         // Generate a default ui
@@ -48,9 +50,7 @@ abstract class backup_setting extends base_setting implements checksumable {
     }
 
     /**
-     * Returns the level of the setting
-     *
-     * @return {int} One of the above constants
+     * @return int Level of the setting, eg {@link self::ROOT_LEVEL}
      */
     public function get_level() {
         return $this->level;
@@ -112,7 +112,7 @@ abstract class backup_setting extends base_setting implements checksumable {
     }
 }
 
-/*
+/**
  * Exception class used by all the @backup_setting stuff
  */
 class backup_setting_exception extends base_setting_exception {

backup/util/settings/base_setting.class.php

@@ -86,6 +86,15 @@ abstract class base_setting {
      */
     protected $help = array();
 
+    /**
+     * Instantiates a setting object
+     *
+     * @param string $name Name of the setting
+     * @param string $vtype Type of the setting, eg {@link self::IS_TEXT}
+     * @param mixed $value Value of the setting
+     * @param bool $visibility Is the setting visible in the UI, eg {@link self::VISIBLE}
+     * @param int $status Status of the setting with regards to the locking, eg {@link self::NOT_LOCKED}
+     */
     public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
         // Check vtype
         if ($vtype !== self::IS_BOOLEAN && $vtype !== self::IS_INTEGER &&

backup/util/settings/root/root_backup_setting.class.php

@@ -16,19 +16,24 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * @package    moodlecore
- * @subpackage backup-settings
- * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * Defines root_backup_setting class
+ *
+ * @package     core_backup
+ * @category    backup
+ * @copyright   2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+defined('MOODLE_INTERNAL') || die();
+
 /**
  * Abstract class containing all the common stuff for root backup settings
- *
- * TODO: Finish phpdocs
  */
 abstract class root_backup_setting extends backup_setting {
 
+    /**
+     * {@inheritdoc}
+     */
     public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
         $this->level = self::ROOT_LEVEL;
         parent::__construct($name, $vtype, $value, $visibility, $status);

mod/workshop/backup/moodle2/backup_workshop_settingslib.php

@@ -21,10 +21,10 @@
  * Workshop has no particular settings but the inherited from the generic
  * {@link backup_activity_task}.
  *
- * @package    mod
- * @subpackage workshop
- * @copyright  2010 David Mudrak <[email protected]>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package     mod_workshop
+ * @category    backup
+ * @copyright   2010 David Mudrak <[email protected]>
+ * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();