CVS: phpweather/config pw_dependency.php,1.1,1.2 pw_dependency_or.php...

[Martin G. <gim...@us...>]

Update of /cvsroot/phpweather/phpweather/config
In directory usw-pr-cvs1:/tmp/cvs-serv17891/config

Modified Files:
	pw_dependency.php pw_dependency_or.php pw_option.php 
	pw_optiongroup.php pw_validator_ereg.php 
	pw_validator_range.php 
Log Message:
Added documentation.


Index: pw_dependency.php
===================================================================
RCS file: /cvsroot/phpweather/phpweather/config/pw_dependency.php,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- pw_dependency.php	7 Apr 2002 18:38:20 -0000	1.1
+++ pw_dependency.php	13 Apr 2002 13:12:29 -0000	1.2
@@ -1,14 +1,48 @@
 <?php
+
+/**
+ * This is the baseclass for all dependencies.
+ *
+ * @author   Martin Geisler <gim...@gi...>
+ * @version  $Id$
+ * @package  PHP Weather Configurator
+ * @abstract
+ */
 class pw_dependency {
 
+  /**
+   * The name of an option.
+   *
+   * @var  string  The name of the option that should be checked.
+   */
   var $option;
+
+  /**
+   * The value that the option must have to satisfy this dependency.
+   *
+   * @var  string  The required value.
+   */
   var $dep;
   
-  function pw_dependency($option, $d) {
+  /**
+   * Constructs a new dependency.
+   *
+   * @param string $option The name of the option that must satisfy
+   * the dependency.
+   * @param string $dep The required value of the option.
+   *
+   */
+  function pw_dependency($option, $dep) {
     $this->option = $option;
-    $this->dep = $d;
+    $this->dep = $dep;
   }
 
+  /**
+   * Checks a dependency.
+   *
+   * @return boolean True if the dependency is satisfied, false
+   * otherwise.
+   */
   function check() {
     return ($GLOBALS['options'][$this->option]->get_value() == $this->dep);
   }

Index: pw_dependency_or.php
===================================================================
RCS file: /cvsroot/phpweather/phpweather/config/pw_dependency_or.php,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- pw_dependency_or.php	7 Apr 2002 18:38:20 -0000	1.1
+++ pw_dependency_or.php	13 Apr 2002 13:12:29 -0000	1.2
@@ -1,9 +1,30 @@
 <?php
 
+/**
+ * An 'or' dependency.
+ *
+ * This dependency is a collection of several dependencies, but it
+ * will be satisfied as long a just one of them is satisfied.
+ *
+ * @author   Martin Geisler <gim...@gi...>
+ * @version  $Id$
+ * @package  PHP Weather Configurator
+ */
 class pw_dependency_or extends pw_dependency {
 
-  function pw_dependency_or($option, $d) {
-    $this->pw_dependency($option, $d);
+  /**
+   * Constructs a new 'or' dependency.
+   *
+   * @param string $option The name of the option that must satisfy
+   * one of the dependencies.
+   *
+   * @param array $dependencies This should be an array of strings. If
+   * the value of $option equals just one of these strings, then the
+   * dependency is satisfied.
+   *
+   */
+  function pw_dependency_or($option, $dependencies) {
+    $this->pw_dependency($option, $dependencies);
   }
 
   function check() {

Index: pw_option.php
===================================================================
RCS file: /cvsroot/phpweather/phpweather/config/pw_option.php,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -3 -r1.2 -r1.3
--- pw_option.php	12 Apr 2002 22:08:49 -0000	1.2
+++ pw_option.php	13 Apr 2002 13:12:29 -0000	1.3
@@ -5,6 +5,8 @@
  *
  * @author   Martin Geisler <gim...@gi...>
  * @version  $Id$
+ * @package  PHP Weather Configurator
+ * @abstract
  */
 class pw_option {
 
@@ -88,18 +90,43 @@
 
   }
 
+  /**
+   * Get the name of this option.
+   *
+   * @return the name of the option.
+   */
   function get_name() {
     return $this->name;
   }
 
+  /**
+   * Get the description of this option.
+   *
+   * @return the description of the option.
+   */
   function get_description() {
     return $this->description;
   }
 
+  /**
+   * Get the value of this option.
+   *
+   * @return the value of the option.
+   */
   function get_value() {
     return $this->value;
   }
 
+  /**
+   * Checks to see if this option is ready to be displayed.
+   *
+   * When this method is called, the option will go through it's
+   * dependencies and make sure that they're all satisfied. You
+   * shouldn't use an option that isn't ready.
+   *
+   * @return boolean True if the option is ready to be displayed,
+   * false otherwise.
+   */
   function is_ready() {
     $ready = true;
     foreach($this->dependencies as $dependency) {
@@ -111,16 +138,40 @@
     return $ready;
   }
 
+  /**
+   * Checks to see if this option has a valid value.
+   *
+   * The validator that was supplied when the option was created is
+   * asked to validate the current value of the option.
+   *
+   * @return boolean True if the option has a valid value false
+   * otherwise.
+   */
   function is_valid() {
     return $this->validator->validate($this->value);
   }
 
+  /**
+   * Updates the current value.
+   *
+   * @param array New values. This array should have the same
+   * structure as $_REQUEST which means that it should contain
+   * option_name_value => value pairs where option_name is the name of
+   * an option.
+   */
   function update_value($values) {
     if (isset($values[$this->name . '_value'])) {
       $this->value = $values[$this->name . '_value'];
     }
   }
 
+  /**
+   * Returns the configuration.
+   *
+   * @return  string  A string suitable for inclusion in the
+   * defaults.php file. If the option isn't ready yet or it's invalid
+   * an empty string is returned.
+   */
   function get_config() {
     if ($this->is_ready() && $this->is_valid() &&
         $this->value != $this->default) {

Index: pw_optiongroup.php
===================================================================
RCS file: /cvsroot/phpweather/phpweather/config/pw_optiongroup.php,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- pw_optiongroup.php	7 Apr 2002 18:38:20 -0000	1.1
+++ pw_optiongroup.php	13 Apr 2002 13:12:29 -0000	1.2
@@ -1,17 +1,60 @@
 <?php
 
+/**
+ * A group of options.
+ *
+ * @author   Martin Geisler <gim...@gi...>
+ * @version  $Id$
+ * @package  PHP Weather Configurator
+ */
 class pw_optiongroup {
 
+  /**
+   * The title of this group.
+   *
+   * @var string The title of this group.
+   */
   var $title;
+
+  /**
+   * The description of this group.
+   *
+   * @var string The description of this group.
+   */
   var $description;
+
+  /**
+   * The options which are part of this group.
+   *
+   * @var array The names of the options which are part of this group.
+   */
   var $options;
 
+  /**
+   * Constructs a new group of options.
+   *
+   * Optiongroups are used to - well - group similar options. By
+   * grouping the options, you can provide a broad description of the
+   * them before the individual options presnet their own description.
+   *
+   * @param  string  $title The title of the group.
+   * @param  string  $description  The description of the group.
+   * @param  array   $options  The names of the options in the group.
+   *
+   */
   function pw_optiongroup($title, $description, $options) {
     $this->title = $title;
     $this->description = $description;
     $this->options = $options;
   }
 
+  /**
+   * Shows the group and the options it contains.
+   *
+   * It is assumed that the call to this method is wrapped in a
+   * description-list (<dl>...</dl>). The options of this group will
+   * be inserted in their own description-list.
+   */
   function show() {
 
     echo "<dt>$this->title <input type=\"submit\" value=\"Update options\"></dt>\n";
@@ -27,6 +70,15 @@
 
   }
 
+  /**
+   * Returns the configuration.
+   *
+   * The configuration is ready to be inserted into the defaults.php
+   * file. It includes a header with the title of the group followed
+   * by the configuration of the options.
+   *
+   * @return  string  The configuration of the options in the group.
+   */
   function get_config() {
 
     $config = '';

Index: pw_validator_ereg.php
===================================================================
RCS file: /cvsroot/phpweather/phpweather/config/pw_validator_ereg.php,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -3 -r1.2 -r1.3
--- pw_validator_ereg.php	9 Apr 2002 23:21:37 -0000	1.2
+++ pw_validator_ereg.php	13 Apr 2002 13:12:29 -0000	1.3
@@ -1,19 +1,58 @@
 <?
-
+/**
+ * Validates input against a regular expression.
+ *
+ * @author   Martin Geisler <gim...@gi...>
+ * @version  $Id$
+ * @package  PHP Weather Configurator
+ */
 class pw_validator_ereg extends pw_validator {
 
+  /**
+   * The regular expression used when validating.
+   *
+   * @var string A regular expression.
+   */
   var $regex;
 
+  /**
+   * Constructs a new ereg_validator.
+   *
+   * @param  string  $error  The message displayed when the input is
+   *                         invalid.
+   * @param  string  $regex  The regular expression used when validating.
+   */
   function pw_validator_ereg($error, $regex) {
     $this->pw_validator($error);
     $this->regex = $regex;
   }
-
+  
+  /**
+   * Validates input agains a regular expression.
+   *
+   * Validates some input.
+   *
+   * @param mixed $value The input that should be matched agains the
+   * regular expression.
+   *
+   * @return boolean True if the regular expression matched the input,
+   * false otherwise.
+   * @access public
+   */
   function validate($value) {
     $this->value = $value;
     return ereg($this->regex, $value);
   }
 
+  /**
+   * Returns code for the keyup event in input fields.
+   *
+   * @param string $id The name that should be passed to the
+   * Javascript as an ID. The ID is used by the Javascript to change
+   * the right paragraph at runtime.
+   * @return  string  A string suitable for the keyup event on an text
+   *                  input field.
+   */
   function get_javascript($id) {
     return "validate_ereg('" . addslashes($this->error) .
       "', '$this->regex', '$id', this)";

Index: pw_validator_range.php
===================================================================
RCS file: /cvsroot/phpweather/phpweather/config/pw_validator_range.php,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -3 -r1.3 -r1.4
--- pw_validator_range.php	12 Apr 2002 22:07:11 -0000	1.3
+++ pw_validator_range.php	13 Apr 2002 13:12:29 -0000	1.4
@@ -6,6 +6,9 @@
  * usefull for testing port-numbers (range 1--65536) or peoples age
  * (range 1--120) etc.
  *
+ * @author   Martin Geisler <gim...@gi...>
+ * @version  $Id$
+ * @package  PHP Weather Configurator
  */
 class pw_validator_range extends pw_validator {
 
@@ -44,6 +47,16 @@
     $this->empty_ok = $empty_ok;
   }
 
+  /**
+   * Validate an integer.
+   *
+   * The input is validated to see if it's within the range specified
+   * when the validator was created.
+   *
+   * @param integer $value The new integer that should be validated.
+   * @return boolean Returns true if the integer is within the correct
+   * range, false otherwise.
+   */
   function validate($value) {
     $this->value = $value;
     
@@ -52,6 +65,15 @@
     return (ereg('^[-+]?[0-9]+$', $value) && $this->low <= $value && $value <= $this->high);
   }
 
+  /**
+   * Returns code for the keyup event in input fields.
+   *
+   * @param string $id The name that should be passed to the
+   * Javascript as an ID. The ID is used by the Javascript to change
+   * the right paragraph at runtime.
+   * @return string A string suitable for the keyup event on an text
+   * input field.
+   */
   function get_javascript($id) {
     $empty_ok = $this->empty_ok ? '1' : '0';
     return "validate_range('" . addslashes($this->error) .