[pLog-svn] r1657 - in plog/trunk/class: . data data/Date data/forms data/pager data/validator data/validator/rules

oscar at devel.plogworld.net oscar at devel.plogworld.net
Wed Mar 30 20:25:51 GMT 2005


Author: oscar
Date: 2005-03-30 20:25:51 +0000 (Wed, 30 Mar 2005)
New Revision: 1657

Modified:
   plog/trunk/class/Doxyfile
   plog/trunk/class/data/Date.class.php
   plog/trunk/class/data/Date/Calc.class.php
   plog/trunk/class/data/Date/Human.class.php
   plog/trunk/class/data/Date/Span.class.php
   plog/trunk/class/data/Date/TimeZone.class.php
   plog/trunk/class/data/forms/formvalidator.class.php
   plog/trunk/class/data/htmlcalendar.class.php
   plog/trunk/class/data/kses.class.php
   plog/trunk/class/data/mimetype.class.php
   plog/trunk/class/data/pager/pager.class.php
   plog/trunk/class/data/plogcalendar.class.php
   plog/trunk/class/data/stringutils.class.php
   plog/trunk/class/data/textfilter.class.php
   plog/trunk/class/data/timestamp.class.php
   plog/trunk/class/data/validator/arrayvalidator.class.php
   plog/trunk/class/data/validator/chainedvalidator.class.php
   plog/trunk/class/data/validator/emailvalidator.class.php
   plog/trunk/class/data/validator/emptyvalidator.class.php
   plog/trunk/class/data/validator/httpurlvalidator.class.php
   plog/trunk/class/data/validator/integervalidator.class.php
   plog/trunk/class/data/validator/ipmatchvalidator.class.php
   plog/trunk/class/data/validator/passwordvalidator.class.php
   plog/trunk/class/data/validator/rules/arrayrule.class.php
   plog/trunk/class/data/validator/rules/emaildnsrule.class.php
   plog/trunk/class/data/validator/rules/emailformatrule.class.php
   plog/trunk/class/data/validator/rules/equalrule.class.php
   plog/trunk/class/data/validator/rules/intrule.class.php
   plog/trunk/class/data/validator/rules/ipcidrformatrule.class.php
   plog/trunk/class/data/validator/rules/ipformatrule.class.php
   plog/trunk/class/data/validator/rules/iprangerule.class.php
   plog/trunk/class/data/validator/rules/nonemptyrule.class.php
   plog/trunk/class/data/validator/rules/numericrule.class.php
   plog/trunk/class/data/validator/rules/rangerule.class.php
   plog/trunk/class/data/validator/rules/rule.class.php
   plog/trunk/class/data/validator/rules/uintrule.class.php
   plog/trunk/class/data/validator/rules/urlformatrule.class.php
   plog/trunk/class/data/validator/stringvalidator.class.php
   plog/trunk/class/data/validator/templatevalidator.class.php
   plog/trunk/class/data/validator/uploadvalidator.class.php
   plog/trunk/class/data/validator/usernamevalidator.class.php
   plog/trunk/class/data/validator/validation.class.php
   plog/trunk/class/data/validator/validationlist.class.php
   plog/trunk/class/data/validator/validator.class.php
Log:
finished the documentation of the data/ folder

Modified: plog/trunk/class/Doxyfile
===================================================================
--- plog/trunk/class/Doxyfile	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/Doxyfile	2005-03-30 20:25:51 UTC (rev 1657)
@@ -416,7 +416,7 @@
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/ controller/ mail/ bayesian/ misc/ net/
+INPUT                  = object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/ controller/ mail/ bayesian/ misc/ net/ data/
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 

Modified: plog/trunk/class/data/Date/Calc.class.php
===================================================================
--- plog/trunk/class/data/Date/Calc.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/Date/Calc.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -8,6 +8,8 @@
 }
 
 /**
+ * \ingroup Data
+ *
  * Date_Calc is a calendar class used to calculate and
  * manipulate calendar dates and retrieve dates in a calendar
  * format. It does not rely on 32-bit system date stamps, so
@@ -29,7 +31,6 @@
  * @version 1.2.6
  * @author Monte Ohrt <monte at ispi.net>
  */
-
 class Date_Calc
 {
     /**

Modified: plog/trunk/class/data/Date/Human.class.php
===================================================================
--- plog/trunk/class/data/Date/Human.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/Date/Human.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -20,6 +20,8 @@
 //
 
 /**
+ * \ingroup Data
+ * 
  * Class to convert date strings between Gregorian and Human calendar formats.
  * The Human Calendar format has been proposed by Scott Flansburg and can be
  * explained as follows:

Modified: plog/trunk/class/data/Date/Span.class.php
===================================================================
--- plog/trunk/class/data/Date/Span.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/Date/Span.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -23,6 +23,7 @@
 require_once PLOG_CLASS_PATH.'class/data/Date/Calc.class.php';
 
 /**
+ *
  * Non Numeric Separated Values (NNSV) Input Format.
  *
  * Input format guessed from something like this:
@@ -39,8 +40,6 @@
  * '3-12-30-18'         -> 3, 12, 30, 18<br>
  * '3 days, 12-30-18'   -> 3, 12, 30, 18<br>
  * '12:30 with 18 secs' -> 0, 12, 30, 18<br>
- *
- * @const int
  */
 define('DATE_SPAN_INPUT_FORMAT_NNSV', 1);
 
@@ -59,9 +58,10 @@
 $_DATE_SPAN_INPUT_FORMAT = DATE_SPAN_INPUT_FORMAT_NNSV;
 
 /**
+ * \ingroup Data
+ *
  * Generic time span handling class for PEAR.
  *
- * @package Date
  * @author  Leandro Lucarella <llucax at php.net>
  * @version $Revision: 1.4 $
  * @since   1.4

Modified: plog/trunk/class/data/Date/TimeZone.class.php
===================================================================
--- plog/trunk/class/data/Date/TimeZone.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/Date/TimeZone.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -24,6 +24,8 @@
 //
 
 /**
+ * \ingroup Data
+ *
  * TimeZone representation class, along with time zone information data.
  *
  * TimeZone representation class, along with time zone information data.
@@ -41,7 +43,6 @@
  *
  *
  * @author Baba Buehler <baba at babaz.com>
- * @package Date
  * @access public
  * @version 1.0
  */

Modified: plog/trunk/class/data/Date.class.php
===================================================================
--- plog/trunk/class/data/Date.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/Date.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,9 +1,5 @@
 <?php
 
-    /**
-     * @package data
-     */
-
 /* vim: set expandtab tabstop=4 shiftwidth=4: */
 // +----------------------------------------------------------------------+
 // | PHP Version 4                                                        |
@@ -62,6 +58,8 @@
 /**@#-*/
 
 /**
+ * \ingroup Data
+ *
  * Generic date handling class for PEAR.
  *
  * Generic date handling class for PEAR.  Attempts to be time zone aware
@@ -69,7 +67,6 @@
  * Date::Calc on Date objects.
  *
  * @author Baba Buehler <baba at babaz.com>
- * @package Date
  * @access public
  */
 class Date

Modified: plog/trunk/class/data/forms/formvalidator.class.php
===================================================================
--- plog/trunk/class/data/forms/formvalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/forms/formvalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -14,7 +14,7 @@
 	 *
 	 * This the class used for form validation. It works helped by the Validator classes to perform data validation,
 	 * as well as in conjunction with the Action and View classes. It is fact internally used by the Action class and it is
-	 * capable of reporting to the view class which fields of a given form genrated an error.
+	 * capable of reporting to the view class which fields of a given form generated an error.
 	 */
 	class FormValidator extends Object
 	{

Modified: plog/trunk/class/data/htmlcalendar.class.php
===================================================================
--- plog/trunk/class/data/htmlcalendar.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/htmlcalendar.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,46 +1,36 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
-
-// PHP Calendar Class Version 1.4 (5th March 2001)
-//
-// Copyright David Wilkinson 2000 - 2001. All Rights reserved.
-//
-// This software may be used, modified and distributed freely
-// providing this copyright notice remains intact at the head
-// of the file.
-//
-// This software is freeware. The author accepts no liability for
-// any loss or damages whatsoever incurred directly or indirectly
-// from the use of this script. The author of this software makes
-// no claims as to its fitness for any purpose whatsoever. If you
-// wish to use this software you should first satisfy yourself that
-// it meets your requirements.
-//
-// URL:   http://www.cascade.org.uk/software/php/calendar/
-// Email: davidw at cascade.org.uk
-
-
-/**
- * Generates an html calendar
+
+/**
+ * \ingroup Data
+ *
+ * Generates an html calendar
  *
- * Class borrowed from http://www.cascade.org.uk/software/php/calendar
+ * PHP Calendar Class Version 1.4 (5th March 2001)
  *
- * Modified by me to make in inherit from the Object class.
+ * Copyright David Wilkinson 2000 - 2001. All Rights reserved.
+ *
+ * This software may be used, modified and distributed freely
+ * providing this copyright notice remains intact at the head
+ * of the file.
+ *
+ * This software is freeware. The author accepts no liability for
+ * any loss or damages whatsoever incurred directly or indirectly
+ * from the use of this script. The author of this software makes
+ * no claims as to its fitness for any purpose whatsoever. If you
+ * wish to use this software you should first satisfy yourself that
+ * it meets your requirements.
+ *
+ * URL:   http://www.cascade.org.uk/software/php/calendar/
+ * Email: davidw at cascade.org.uk
+ *
+ * Modified by fuze (http://www.fuze.org) on 2004/07/11
+ *
+ * Just changed the html table output for better (CSS) accessibility
+ * and variable names.
  */
- 
- /**
-  * Modified by fuze (http://www.fuze.org) on 2004/07/11
-  *
-  * Just changed the html table output for better (CSS) accessibility
-  * and variable names.
-  */
-  
+
 class Calendar extends Object
 {
     /*

Modified: plog/trunk/class/data/kses.class.php
===================================================================
--- plog/trunk/class/data/kses.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/kses.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,14 +1,15 @@
 <?php
-
-    /**
-     * @package data
-     */
-
-	/*
+	/**
+	 * \ingroup Data
+	 *
 	 *	This is a fork of a slick piece of procedural code called 'kses' written by Ulf Harnhammar
 	 * The entire set of functions was wrapped in a PHP object with some internal modifications
 	 * by Richard Vasquez (http://www.chaos.org/) 7/25/2003
 	 *
+	 * The pLog project has made a few improvements to the code, for example including a mode where 
+	 * the filter can convert invalid XHTML code into valid markup, as well as a more aggressive 
+	 * filtering mode.
+	 *
 	 *	The original (procedural) version of the code can be found at:
 	 * http://sourceforge.net/projects/kses/
 	 *
@@ -46,7 +47,6 @@
 	 *
 	 * Email:    View current valid email address at http://www.chaos.org/contact/
 	 */
-
 	class kses
 	{
 		var $allowed_protocols = array('http', 'https', 'ftp', 'news', 'nntp', 'telnet', 'gopher', 'mailto', 'irc');

Modified: plog/trunk/class/data/mimetype.class.php
===================================================================
--- plog/trunk/class/data/mimetype.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/mimetype.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,13 +1,10 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
 
 /**
+ * \ingroup Data
+ * 
  * Copyright (C) 2002 Jason Sheets <jsheets at shadonet.com>.
  * All rights reserved.
  *
@@ -63,7 +60,7 @@
  *
  *    Example:
  *
- *       $mimetype = new mimetype();
+ *       $mimetype = new MimeType();
  *       print $mimetype->getType('acrobat.pdf');
  *
  *    Author: Jason Sheets <jsheets at shadonet.com>
@@ -78,7 +75,8 @@
  *    types as an static variable inside the class, so that it does not have to be rebuilt
  *    everytime when calling getType.
  */
-class MimeType extends Object {
+class MimeType extends Object 
+{
 
 	var $mimetypes = Array(
          "ez" => "application/andrew-inset",

Modified: plog/trunk/class/data/pager/pager.class.php
===================================================================
--- plog/trunk/class/data/pager/pager.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/pager/pager.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,7 +6,47 @@
     define("DEFAULT_PAGER_MAX_PAGES", 1);
 
 	/**
-	 * generic implementation of a pager
+	 * \defgroup Pager
+	 *
+	 * generic implementation of a pager. It doesn't take of generating SQL queries for paging or
+	 * anythign like that, it only takes care of generating the number of pages based on the number
+	 * of registers, keeping track of the current page, etc. 
+	 *
+	 * There also needs to be some display logic in order to get it to work fine.
+	 *
+	 * At the PHP level, some code like this is necessary:
+	 *
+	 * <pre>
+     * $pager = new Pager( "?op=editPosts&amp;showStatus={$this->_showStatus}&amp;page=",
+     *                     $this->_page, 
+     *                     $numPosts, 
+     *                     $this->_itemsPerPage );
+     * $view->setValue( "pager", $pager );
+     * </pre>
+     *
+     * The first parameter passed to the constructor is the string that the pager class will use
+     * to generate the page links. It will only append a page number, nothing else.
+     *
+     * At the Smarty/template level, some code like this is necessary in order to display the links
+     * properly, etc:
+     *
+     * <pre>
+     *   {if !$pager->isFirstPage() && !$pager->isEmpty()}
+     *      &lt;a class="pagerLink" href="{$pager->getPrevPageLink()}"&gt;&laquo;Prev&lt;/a&gt;&nbsp;
+     *   {/if}	
+     *   {foreach from=$pager->getPageLinks() item=pageLink key=pageId}
+     *     {if $pageId == $pager->getCurrentPage()}
+     *       &lt;span class="pagerCurrent"&gt;&nbsp;{$pageId}&nbsp;&gt;/span&lt;
+     *     {else}
+     *       &lt;a class="pagerLink" href="{$pageLink}"&gt;&nbsp;{$pageId}&nbsp;&lt;/a&gt;&nbsp;
+     *     {/if}  
+     *   {/foreach}
+     *   {if !$pager->isLastPage() && !$pager->isEmpty()}
+     *       &lt;a class="pagerLink" href="{$pager->getNextPageLink()}"&gt;Next&raquo;&lt;/a&gt;&nbsp;
+     *   {/if}
+	 * </pre>     
+	 *
+	 * The display logic might look a bit complex but it is unavoidable...
 	 */
     class Pager extends Object
     {
@@ -22,11 +62,13 @@
 
 
 		/**
-		 * @param baseUrl
-		 * @param offset
-		 * @param totalRegs
-		 * @param regsForPage
-		 * @param maxPages
+		 * Constructor of the pager
+		 * 
+		 * @param baseUrl The base url that will be used to generate the different URLs to the pages
+		 * @param curPage The current page
+		 * @param totalRegs The total number of registers
+		 * @param regsForPage The maximum number of registers per page, defaults to 
+		 * DEFAULT_PAGER_REGS_FOR_PAGE
 		 */
         function Pager($baseUrl, $curPage, $totalRegs, $regsForPage = DEFAULT_PAGER_REGS_FOR_PAGE )
         {
@@ -41,15 +83,17 @@
         }
 
         /**
-        *    Add function info here
-        */
+         * Sets the base url
+		 *
+		 * @param url The url
+         */
         function setBaseUrl($url)
         {
             $this->_baseUrl = $url;
         }
 
         /**
-        *    Add function info here
+        * @return returns the base url
         */
         function getBaseUrl()
         {
@@ -57,40 +101,40 @@
         }
 
         /**
-        *    Add function info here
-        */
+         * @return Returns the current total amount of registers
+         */
         function getTotalRegs()
         {
             return $this->_totalRegs;
         }
 
         /**
-        *    Add function info here
-        */
+         * @return Returns the current number of records per page
+         */
         function getRegsForPage()
         {
             return $this->_regsForPage;
         }
 
         /**
-        *    Add function info here
-        */
+         * @return Returns the maximum number of pages
+         */
         function getMaxPages()
         {
             return $this->_maxPages;
         }
 
         /**
-        *    Add function info here
-        */
+         * @return The total number of pages
+         */
         function getTotalPages()
         {
             return $this->_totalPages;
         }
 
         /**
-        *    Add function info here
-        */
+         * @return The current page
+         */
         function getCurrentPage()
         {
             return $this->_curPage;
@@ -125,39 +169,39 @@
 		}
 
         /**
-        *    Add function info here
-        */
+         * @return Returns the current start page, if any
+         */
         function getStartPage()
         {
             return $this->_startPage;
         }
 
         /**
-        *    Add function info here
-        */
+         * @return Returns the last page
+         */
         function getEndPage()
         {
             return $this->_endPage;
         }
 
         /**
-        *    Add function info here
-        */
+         * @return True if the current page is the first page or false otherwise
+         */
         function isFirstPage()
         {
             return ($this->_curPage == 1);
         }
 
         /**
-        *    Add function info here
-        */
+         * @return Returns true if the current page is the last one or false otherwise
+         */
         function isLastPage()
         {
             return ($this->_curPage == $this->_totalPages);
         }
 		
 		/**
-		 *
+		 * @return Returns an array containing all the links to the different pages
 		 */
 		function getPageLinks()
 		{
@@ -165,7 +209,7 @@
 		}
 		
 		/**
-		 *
+		 * @return Returns a link to the next page
 		 */
 		function getNextPageLink()
 		{
@@ -173,7 +217,7 @@
 		}
 		
 		/**
-		 *
+		 * @return Returns a link to the previous page
 		 */
 		function getPrevPageLink()
 		{
@@ -181,7 +225,7 @@
 		}
 		
 		/**
-		 * returns the link to the first page
+		 * @return returns the link to the first page
 		 */
 		function getFirstPageLink()
 		{
@@ -189,7 +233,7 @@
 		}
 		
 		/**
-		 * returns the link to the last page
+		 * @return returns the link to the last page
 		 */
 		function getLastPageLink()
 		{
@@ -224,8 +268,8 @@
 		}
 
         /**
-        *    Add function info here
-        */
+         * @private
+         */
         function _init()
         {
             $this->_totalPages       = ceil($this->_totalRegs / $this->_regsForPage);

Modified: plog/trunk/class/data/plogcalendar.class.php
===================================================================
--- plog/trunk/class/data/plogcalendar.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/plogcalendar.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/htmlcalendar.class.php" );
     include_once( PLOG_CLASS_PATH."class/locale/locale.class.php" );
     include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
@@ -12,19 +7,23 @@
     include_once( PLOG_CLASS_PATH."class/dao/bloginfo.class.php" );
     include_once( PLOG_CLASS_PATH."class/locale/locales.class.php" );
 
-   /**
+   /**
+    * \ingroup Data
+    *
  	* A derived class is required to reimplement some methods from the parent
  	* Calendar class to add things like links to the days and so on.
     * This one also converts the original HtmlCalendar into Locale aware, respecting
-    * things like the first day of the week and the abbreviations of the days of the week.
+    * things like the first day of the week and the abbreviations of the days of the week.
+    *
+    * User classes will rarely need to use this class.
  	*/
-	class PlogCalendar extends Calendar {
+	class PlogCalendar extends Calendar 
+	{
 
     	var $_dayPosts;
-        var $_blogInfo;
+        var $_blogInfo;
+        var $rg;
 
-	var $rg;
-
     	/**
          * Constructor.
          *
@@ -64,7 +63,9 @@
 
         /**
          * Function overwritten from the base one, so that we can display links for the
-         * next month and the previous month
+         * next month and the previous month
+         *
+         * @see Calendar::getCalendarLink()
          */
     	function getCalendarLink( $month, $year )
     	{
@@ -79,7 +80,9 @@
 
         /**
          * Function overwritten from the base one, so that we can display a link for the days
-         * that have posts
+         * that have posts
+         *
+         * @see Calendar::getDateLink()
          */
     	function getDateLink( $day, $month, $year )
     	{

Modified: plog/trunk/class/data/stringutils.class.php
===================================================================
--- plog/trunk/class/data/stringutils.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/stringutils.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,19 +1,32 @@
 <?php
 
-    /**
-     * @package data
+	include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
+
+    /**
+     * \ingroup Data
+     *
+     * Basic methods for formatting or doing nasty things to strings :-)
      */
-
-
-	include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
-
-    class StringUtils extends Object {
-
+    class StringUtils extends Object 
+    {
+
+        /** 
+         * Alias for htmlspecialchars
+         * @static
+         */
         function htmlTranslate( $string )
         {
         	return htmlspecialchars( $string );
         }
-
+
+        /**
+         * cuts a string at a given character
+         *
+         * @param string
+         * @param n
+         * @return The reduced string
+         * @static
+         */
         function cutString( $string, $n )
         {
         	return substr( $string, 0, $n );
@@ -23,7 +36,8 @@
          * Returns an array with all the links in a string.
          *
          * @param string The string
-         * @return An array with the links in the string.
+         * @return An array with the links in the string.
+         * @static
          */
         function getLinks( $string )
         {
@@ -43,7 +57,8 @@
 		 * Returns a size formatted and with its unit: "bytes", "KB", "MB" or "GB"
 		 *
 		 * @param size The amount
-		 * @return A string with the formatted size.
+		 * @return A string with the formatted size.
+		 * @static
 		 */
 		function formatSize( $size )
 		{
@@ -57,7 +72,9 @@
          * Returns a string in a readable and url-compliant format.
          *
          * @param string The string
-         * @return A string ready to use in urls.
+         * @return A string ready to use in urls.
+         * @static
+         * @see TextFilter::urlize()
          */
         function text2url( $string )
         {
@@ -83,12 +100,12 @@
         }
 		
 		/**
-		 * extremely lame function. I'm sure there are better ways to do this in php
-		 * but I can't think of any myself at the moment :-)
+		 * extremely lame function. 
 		 *
 		 * @param count how many times we'd like to repeat the character
 		 * @param char The character (or string) we'd like to repeat
-		 * @return The resulting string
+		 * @return The resulting string
+		 * @static
 		 */
  		function pad( $count, $char = " ")
 		{

Modified: plog/trunk/class/data/textfilter.class.php
===================================================================
--- plog/trunk/class/data/textfilter.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/textfilter.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,18 +1,22 @@
 <?php
 
     /**
-     * @package data
+     * \defgroup Data
+     *
+     * The Data module includes all sorts of functions that deal with data manipulation such as Validator
+     * classes, text formatters or pagers
      */
 
-
 	include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
 	include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
 	include_once( PLOG_CLASS_PATH."class/data/kses.class.php" );
 	include_once( PLOG_CLASS_PATH."class/data/stringutils.class.php" );
 
     /**
-	 * Implements some text filters, for example removing javascript
-	 * code from a string or removing any non-allowed character.
+     * \ingroup Data
+     *
+	 * Implements some text filters that can be used to remove Javascript code, or convert
+	 * non-XHTML code into valid XHTML code, etc.
 	 */
 	class TextFilter extends Object 
 	{
@@ -114,6 +118,8 @@
 
         /**
          * Alias for filterHTMLEntities
+         *
+         * @see filterHTMLEntities
          */
 		function filterXMLEntities( $string )
 		{
@@ -137,27 +143,6 @@
 		}
 		
         /**
-         * Translates all the &gt;a href="..."&lt; tags of a text to include the
-         * target="blank_" parameter so that they will open in a new window
-         */
-		function linksInNewWindow( $text )
-		{
-			$text = str_replace( "<a ", "<a target=\"blank_\" ", $text );
-
-			return $text;
-		}
-
-		function translateSmileys( $text )
-		{
-			foreach( $this->_smileys as $symbol => $icon ) {
-				$new_text = str_replace( $symbol, $icon, $text );
-				$text = $new_text;
-			}
-
-			return $text;
-		}
-
-        /**
          * Texturize function borrowed from http://photomatt.net/tools/texturize
          *
          * Takes care of "beautifying" code typed by users.
@@ -212,6 +197,9 @@
          *
          * Takes care of "beautifying" text, by adding <p> tags to blocks of texts without the users
          * needing to know any html.
+         *
+         * @param pee
+         * @param br
          */
 		function autoP($pee, $br=1)
         {
@@ -380,6 +368,17 @@
             return $newtext;
         }
         
+        /** 
+         * Given a string, convert it into something that can be used in a URL (it probably doesn't work very
+         * well with non iso-8859-X strings) It will remove the following characters:
+         *
+         * ; / ? : @ & = + $ ,
+         *
+         * It will convert accented characters such as ˆ, , ’, etc to their non-accented counterparts (a, e, i) And
+         * any other non-alphanumeric character that hasn't been removed or replaced will be thrown away.
+         *
+         * @param string The string that we wish to convert into something that can be used as a URL
+         */
         function urlize( $string )
         {
 		    // remove unnecessary spaces and make everything lower case
@@ -400,7 +399,10 @@
         }
 		
 		/**
-		 * xhtml-izes a string
+		 * xhtml-izes a string. It uses the KSes filter for the task as long as the configuration parameter
+		 * xhtml_converter_enabled is enabled. If xhtml_converter_aggreesive_mode_enabled is also enabled,
+		 * KSes will be set into "aggressive" mode and it will try to fix even more problems with the XHTML
+		 * markup (but it can also introduce more mistakes)
 		 *
 		 * @param string
 		 * @return the xhtml-ized string
@@ -423,7 +425,7 @@
 		}
 		
 		/**
-		 * tbd
+		 * @private
 		 */
 		function checkboxToBoolean( $value )
 		{

Modified: plog/trunk/class/data/timestamp.class.php
===================================================================
--- plog/trunk/class/data/timestamp.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/timestamp.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	 include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
 	 include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
 	 include_once( PLOG_CLASS_PATH."class/locale/locales.class.php" );
@@ -18,7 +13,27 @@
  	 define( "TIME_DIFFERENCE_CALCULATION_DYNAMIC", 0 );	 
 	 define( "TIME_DIFFERENCE_CALCULATION_STATIC", 1 );
 
-	 
+
+    /**
+     * \ingroup Data
+     *
+     * This class allows to deal with all sorts of different date formats, as many as the PEAR::Date class
+     * supports (Timestamp started as an independent class but later on due to requirements it was developed
+     * as an extension for PEAR::Date, maintaining the previous interface for compatibility reasons)
+     *
+     * PEAR::Date has its own documentation available here: http://pear.php.net/package/Date/docs/1.4.2/Date/Date.html
+     * 
+     * The formats supported by PEAR::Date are:
+     *
+     * - DATE_FORMAT_ISO (YYYY-MM-DD HH:MM:SS)
+     * - DATE_FORMAT_ISO_BASIC (YYYYMMSSTHHMMSS(Z|(+/-)HHMM)?)
+     * - DATE_FORMAT_ISO_EXTENDED (YYYY-MM-SSTHH:MM:SS(Z|(+/-)HH:MM)?)
+     * - DATE_FORMAT_ISO_EXTENDED_MICROTIME (YYYY-MM-SSTHH:MM:SS(.S*)?(Z|(+/-)HH:MM)?)
+     * - DATE_FORMAT_TIMESTAMP (YYYYMMDDHHMMSS)
+     * - DATE_FORMAT_UNIXTIME (seconds since the unix epoch)
+     *
+     * @see Date
+     */
 	class Timestamp extends Date 
 	{
 
@@ -29,6 +44,8 @@
 		 * Creates a Timestamp object
 		 * If $timestamp is empty or not specified, creates a timestamp
 		 * taking the current time
+		 *
+		 * @param timestamp a valid SQL timestamp (DATE_FORMAT_TIMESTAMP / YYYYMMDDHHMMSS)
 		 */
 		function Timestamp( $timestamp = null )
 		{
@@ -58,6 +75,7 @@
          * century will be '2000', not 21.
          *
          * @return An integer value representing the current century.
+         * @deprecated
          */
 		function getCentury()
 		{
@@ -97,6 +115,9 @@
             die();
 		}
 
+        /**
+         * @return Returns the current month, as a value from "00" to "12"
+         */
         function getMonth()
         {
         	// call the parent getMonth() method
@@ -107,6 +128,11 @@
             return $month;
         }
 
+        /**
+         * Sets a new value for the minutes in this timestamp
+         *
+         * @param newMinutes the new value for the minutes
+         */
         function setMinutes( $newMinutes )
         {
         	$this->setMinute( $newMinutes );

Modified: plog/trunk/class/data/validator/arrayvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/arrayvalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/arrayvalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,16 +1,16 @@
 <?php
 
-    /**
-     * @package data
-     */
-	 
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
     include_once( PLOG_CLASS_PATH."class/data/validator/rules/arrayrule.class.php" );
 
     /**
-     * validates if a value is a php array... very useful when we are expecting
+     * \ingroup Validator
+     *
+     * validates if a value is a php array. Useful when we are expecting
 	 * parameters as array in a request and we'd like to know whether we're really
-	 * receiving an array
+	 * receiving an array.
+	 *
+	 * @see ArrayRule
      */
     class ArrayValidator extends Validator
     {

Modified: plog/trunk/class/data/validator/chainedvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/chainedvalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/chainedvalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,20 +1,37 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
 
     /**
+     * \ingroup Validator
+     *
      * Validator class that allows to make chained validators so that we can validate for more complex
 	 * rules. The parameter for the constructor is an array of Validator objects that we are going to
-	 * chain... Well in fact, we're not going to chain the validators but their rules, one after each
-	 * other using the Validator::addValidator() method
+	 * chain.
+	 *
+	 * Internally, this class is not actually going to chain the validators but their rules, one after each
+	 * other using the Validator::addValidator() method.
+	 *
+	 * You can either create your own brand new custom Validator class and add the rules that you need
+	 * or if you know that some Validator classes are already doing what you need, you can always 
+	 * chain them by using the ChainedValidator class.
+	 *
+	 * Example:
+	 *
+	 * <pre>
+	 *  $val = new ChainedValidator( Array( new StringValidator(),
+	 *                                      new UsernameValidator());
+	 *  $result = $val->validate( $value );
+	 * </pre>
      */
     class ChainedValidator extends Validator 
     {
+        /**
+         * Constructor of the chained validator
+         *
+         * @param validators An array of Validator objects which implement the logic that
+         * we need
+         */
     	function ChainedValidator( $validators )
         {
         	$this->Validator();

Modified: plog/trunk/class/data/validator/emailvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/emailvalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/emailvalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,20 +1,27 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
     include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
     include_once( PLOG_CLASS_PATH."class/data/validator/rules/emailformatrule.class.php" );
     include_once( PLOG_CLASS_PATH."class/data/validator/rules/emaildnsrule.class.php" );    
 
     /**
-     * Extends the validator class to determine wether an email address is valid or not.
+     * \ingroup Validator
+     * 
+     * Implements validation of email addresses. If check_email_address_validity is set to
+     * enabled, it will also check whether the email address is valid in the given email server
+     * by adding an EmailDnsRule to the list of rules to validate.
+     *
+     * @see EmailFormatRule
+     * @see EmailDnsRule
      */
     class EmailValidator extends Validator
     {
+        /**
+         * The constructor only initializes the validator and depending on the 
+         * value of check_email_address_validity, it will also add a EmailDnsRule
+         * rule to check for the validity of the mailbox in the given email server
+         */
         function EmailValidator()
         {
             $this->Validator();

Modified: plog/trunk/class/data/validator/emptyvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/emptyvalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/emptyvalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,17 +1,20 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
 
     /**
-     * Empty validation class that always returns true
+     * \ingroup Validator
+     *
+     * Empty validation class that always returns true.
      */
     class EmptyValidator extends Validator 
-    {
+    {  
+        /**
+         * This method always return true
+         *
+         * @param value 
+         * @return Always true
+         */
 		function validate( $value )
 		{
 			return true;

Modified: plog/trunk/class/data/validator/httpurlvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/httpurlvalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/httpurlvalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,16 +1,15 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
 	include_once( PLOG_CLASS_PATH."class/data/validator/rules/regexprule.class.php" );
 	include_once( PLOG_CLASS_PATH."class/data/validator/rules/nonemptyrule.class.php" );
 
     /**
+     * \ingroup Validator
+     *
      * Checks whether the string is a valid http/https url
+     *
+     * @see NonEmptyRule
      */
     class HttpUrlValidator extends Validator 
     {

Modified: plog/trunk/class/data/validator/integervalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/integervalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/integervalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,15 +1,14 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
 	include_once( PLOG_CLASS_PATH."class/data/validator/rules/uintrule.class.php" );
 
     /**
+     * \ingroup Validator
+     *
      * Checks that it is really an integer value.
+     *
+     * @see UIntRule
      */
     class IntegerValidator extends Validator 
     {

Modified: plog/trunk/class/data/validator/ipmatchvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/ipmatchvalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/ipmatchvalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,28 +1,29 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
 
     /**
+     * \ingroup Validator
+     * 
      * Matches ip address with masks. Returns true wether
      * the given ip address matches with the given mask
      */
-	class IpMatchValidator extends Validator {
+	class IpMatchValidator extends Validator 
+	{
 
     	function IpValidator()
         {
         	$this->Validator();
         }
-
+        
         function validate( $ip, $mask )
         {
         	return $this->checkip( $ip, $mask );
         }
 
+        /**
+         * @private
+         */
         function checkip($ip , $csiext)
         {
         	$counter = 0;

Modified: plog/trunk/class/data/validator/passwordvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/passwordvalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/passwordvalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
     include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
     include_once( PLOG_CLASS_PATH."class/data/validator/rules/nonemptyrule.class.php" );
@@ -16,7 +11,15 @@
     define( "ERROR_PASSWORD_EMPTY", 2 );
 
     /**
-     * Checks passwords
+     * \ingroup Validator
+     *
+     * Validates passwords according to certain rules:
+     *
+     * - passwords should not be empty
+     * - password should have a length between minimun_password_length (if not available, defaults to '6') and a maximum length of 32
+     *
+     * @see NonEmptyRule
+     * @see RangeRule
      */
     class PasswordValidator extends Validator 
     {

Modified: plog/trunk/class/data/validator/rules/arrayrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/arrayrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/arrayrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,11 +1,18 @@
 <?php
 
     include_once(PLOG_CLASS_PATH."class/data/validator/rules/rule.class.php");
-
+	
+	/**
+	 * \ingroup Validator_Rules
+	 *
+	 * Implements a rule that checks if the input is a valid php array (used
+	 * in cases when we'd like to validate if something coming from $_GET or $_POST
+	 * is an array)
+	 */
     class ArrayRule extends Rule
     {
         /**
-         * The constructor does nothing.
+         * Initializes the rule
          */
         function ArrayRule()
         {
@@ -13,8 +20,9 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+         * Validates the data.
+         *
+         * @param value The array that we'd like to validate
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/emaildnsrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/emaildnsrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/emaildnsrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -8,13 +8,16 @@
     define( "ERROR_RULE_EMAIL_DNS_NOT_PERMITTED", "error_rule_email_dns_not_permitted");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+	 * \ingroup Validator_Rules
+	 *
+	 * Given an email address it will connect to the MX server listed for the given domain
+	 * and check whether the given user name has a valid mailbox in the server. This operation
+	 * is a bit costly concerning time, since it takes a while to carry out these operations.
+	 *
+	 * This class will set one of these errors:
+	 *
+	 * - ERROR_RULE_EMAIL_DNS_NOT_PERMITTED
+	 * - ERROR_RULE_EMAIL_DNS_SERVER_UNREACHABLE
      */
     class EmailDnsRule extends Rule
     {
@@ -27,8 +30,7 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+		 * Checks the given email address
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/emailformatrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/emailformatrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/emailformatrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,13 +6,10 @@
     define( "ERROR_RULE_EMAIL_FORMAT_WRONG", "error_rule_email_format_wrong");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+	 * \ingroup Validator_Rules
+	 *
+	 * Given an email address, returns true if it looks like a valid email address (if it has the 
+	 * valid format) If not, it will return ERROR_RULE_EMAIL_FORMAT_WRONG
      */
     class EmailFormatRule extends RegExpRule
     {
@@ -25,8 +22,7 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+		 * Validates the format of the given email address
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/equalrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/equalrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/equalrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,13 +6,11 @@
     define( "ERROR_RULE_VALUES_NOT_EQUAL", "error_rule_values_not_equal");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+	 * \ingroup Validator_Rules
+	 *
+	 * checks whether an item is equal to another via the binary operator '=='.
+	 * Use the setEqualValue() method to set the first value and call the validate()
+	 * method with the second value.
      */
     class EqualRule extends Rule
     {
@@ -28,7 +26,7 @@
         }
 
         /**
-         * Add function info here
+         * @return returns the value we're comparing
          */
         function getEqualValue()
         {
@@ -36,7 +34,9 @@
         }
 
         /**
-         * Add function info here
+         * Sets the value we're comparing to
+		 *
+		 * @param equalValue the valure we're comparing to
          */
         function setEqualValue($equalValue)
         {
@@ -44,8 +44,8 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+		 * Returns true if the two given values are equal. It will return ERROR_RULE_VALUES_NOT_EQUAL
+		 * if they're not
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/intrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/intrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/intrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,18 +6,15 @@
     define( "ERROR_RULE_INT_FORMAT_WRONG", "error_rule_int_format_wrong");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+	 * \ingroup Validator_Rules
+	 *
+	 * Checks if the given value is an integer, not only in type but also in format.
+	 * It will return ERROR_RULE_INT_FORMAT_WRONG if the format is not correct
      */
     class IntRule extends RegExpRule
     {
         /**
-         * The constructor does nothing.
+         * Initialize the rule
          */
         function IntRule()
         {
@@ -25,8 +22,8 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+		 * Returns true if the given value is an integer, or false otherwise. In case of error
+		 * it will also set the error code to ERROR_RULE_INT_FORMAT_WRONG
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/ipcidrformatrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/ipcidrformatrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/ipcidrformatrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,18 +6,19 @@
     define( "ERROR_RULE_IP_CIDR_FORMAT_WRONG", "error_rule_ip_cidr_format_wrong");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+	 * \ingroup Validator_Rules
+	 *
+	 * Returns true if a given IP address is in valid CIDR format (Classless Inter-Domain Routing) These addresses
+	 * should have the following format: 
+	 *
+	 * <pre>xxx.yyy.zzz.www</pre>
+	 *
+	 * where each one of the elements is an integer between 0 and 255.
      */
     class IpCidrFormatRule extends RegExpRule
     {
         /**
-         * The constructor does nothing.
+         * Initializes the rule
          */
         function IpCidrFormatRule()
         {
@@ -25,8 +26,9 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+         * Retursn true if the given IP address is in valid CIDR format
+         *
+         * @param value the IP address to validate
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/ipformatrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/ipformatrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/ipformatrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,18 +6,19 @@
     define( "ERROR_RULE_IP_FORMAT_WRONG", "error_rule_ip_format_wrong");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+	 * \ingroup Validator_Rules
+	 *
+	 * Returns true if a given IP address is in valid CIDR format (Classless Inter-Domain Routing) These addresses
+	 * should have the following format: 
+	 *
+	 * <pre>xxx.yyy.zzz.www</pre>
+	 *
+	 * where each one of the elements is an integer between 0 and 255.
      */
     class IpFormatRule extends RegExpRule
     {
         /**
-         * The constructor does nothing.
+         * Initializes the rule
          */
         function IpFormatRule()
         {
@@ -25,8 +26,9 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+         * Retursn true if the given IP address is in valid CIDR format
+         *
+         * @param value the IP address to validate
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/iprangerule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/iprangerule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/iprangerule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -5,20 +5,23 @@
     define( "ERROR_RULE_IP_NOT_IN_RANGE", "error_rule_ip_not_in_range");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+     * \ingroup Validator_Rules
+     *
+     * This rule returns true if the given IP address is within a certain range. Use the constructor
+     * or the setRange() method for setting the right range. The range should be given in a submask format,
+     * so for example 1.2.3.4 would be within the range 1.2.3.255
+     *
+     * It will set the error flag ERROR_RULE_IP_NOT_IN_RANGE error if the address is not in the
+     * given range.
      */
     class IpRangeRule extends Rule
     {
         var $_range;
 
         /**
-         * The constructor does nothing.
+         * Initializes the rule with the given range
+         *
+         * @param range The range.
          */
         function IpRangeRule($range)
         {
@@ -27,7 +30,9 @@
         }
 
         /**
-         * Add function info here
+         * Sets a different range than the one given in the constructor
+         *
+         * @param range the new range
          */
         function setRange($range)
         {
@@ -35,7 +40,9 @@
         }
 
         /**
-         * Add function info here
+         * Returns the current range being used for the calculations
+         *
+         * @return A string representing the range
          */
         function getRange()
         {
@@ -43,8 +50,11 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+         * Returns true if the address is within the given range or false otherwise. It will
+         * also set the error ERROR_RULE_IP_NOT_IN_RANGE
+         *
+         * @param value The IP address to validate
+         * @return True if within range or false otherwise
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/nonemptyrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/nonemptyrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/nonemptyrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -5,12 +5,14 @@
     define( "ERROR_RULE_VALUE_IS_EMPTY", "error_rule_value_is_empty");
 
     /**
+     * \ingroup Validator_Rules
+     *
      * Validates if a string is empty or not
      */
     class NonEmptyRule extends Rule
     {
         /**
-         * The constructor does nothing.
+         * Initializes the rule
          */
         function NonEmptyRule()
         {
@@ -18,8 +20,11 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+         * Returns true if the value is not empty or false otherwise. If empty,
+         * the error ERROR_RULE_VALUE_IS_EMPTY will be set.
+         *
+         * @param value the string that we'd like to validate
+         * @return true if successful or false otherwise
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/numericrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/numericrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/numericrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,18 +6,14 @@
     define( "ERROR_RULE_NUMERIC_FORMAT_WRONG", "error_rule_numeric_format_wrong");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+     * \ingroup Validator_Rules
+     *
+     * Via a regular expression, validates whether the given string is a valid numeric value.
      */
     class NumericRule extends RegExpRule
     {
         /**
-         * The constructor does nothing.
+         * Initializes the rule
          */
         function NumericRule()
         {
@@ -25,8 +21,11 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+         * Returns true if the rule is successful or false otherwise. It will set the error
+         * ERROR_RULE_NUMERIC_FORMAT_WRONG in case the validation is unsuccessful.
+         *
+         * @param value The value that should be checked
+         * @return true if successful or false otherwise.
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/rangerule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/rangerule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/rangerule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,13 +6,13 @@
     define( "ERROR_RULE_TOO_LARGE", "error_rule_too_large");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+     * \ingroup Validator_Rules
+     *
+     * Given two values that will be used as lower and upper boundaries of the range, 
+     * it will validate whether the given value falls within the range.
+     *
+     * It will set the errors ERROR_RULE_TOO_SMALL or ERROR_RULE_TOO_LARGE in case the
+     * validation is not successful.
      */
     class RangeRule extends Rule
     {
@@ -20,7 +20,10 @@
         var $_maxValue;
 
         /**
-         * The constructor does nothing.
+         * Initializes the rule
+         *
+         * @param minValue the lower boundary of the range
+         * @param maxValue the upper boundary of the range
          */
         function RangeRule($minValue, $maxValue)
         {
@@ -31,7 +34,7 @@
         }
 
         /**
-         * Add function info here
+         * @return the lower boundary of the range
          */
         function getMinValue()
         {
@@ -39,7 +42,9 @@
         }
 
         /**
-         * Add function info here
+         * sets the lower boundary of the range
+         *
+         * @param minValue the minimum value
          */
         function setMinValue($minValue)
         {
@@ -47,7 +52,7 @@
         }
 
         /**
-         * Add function info here
+         * @return the upper boundary of the range
          */
         function getMaxValue()
         {
@@ -55,7 +60,9 @@
         }
 
         /**
-         * Add function info here
+         * sets the lower boundary of the range
+         *
+         * @param minValue the minimum value
          */
         function setMaxValue($maxValue)
         {
@@ -63,8 +70,10 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+         * validates that the given value is within the two boundaries previously specified
+         *
+         * @param value The value to validate
+         * @return True if successful or false otherwise
          */
         function validate($value)
         {
@@ -87,4 +96,4 @@
             }
         }
     }
-?>
+?>
\ No newline at end of file

Modified: plog/trunk/class/data/validator/rules/rule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/rule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/rule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -3,14 +3,37 @@
     include_once( PLOG_CLASS_PATH."class/data/validator/validation.class.php");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+     * \defgroup Validator_Rules
+     *
+     * The main classes that implement the Strategy pattern as described here
+     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/ are the classes
+     * that extend the Validator interface. 
+     *
+     * But at a deeper level, a Validator class is nothing else than a collection of rules,
+     * or classes that extend the Rule interface. Implementing Validator classes as a collection
+     * of Rule classes allows for better code reusability, since sometimes most of the Validator
+     * classes check for similar things and therefore we can reuse most of the Rule classes.
+     *
+     * In order to implement your own rule, simply create your own class extending the Rule 
+     * class and make sure to implement the Rule::Validate() method with your own validation logic. This
+     * method should return 'true' if the data complies with the logic of the rule or 'false' if it does
+     * not. Additionally, since Rule extends the Validation interface it is also possible to set
+     * certain error flags or messages via the private method Validation::_setError(). These error
+     * codes can be checked by Validator classes or by users of this class via the Validation::getError()
+     * method.
+     *
+     * See the documentation of the Validator base class on how to use Rule classes in your own validators.
+     * @see Validator
      */
+     
+    /**
+     * \ingroup Validator_Rules
+     *
+     * This is the main base class that all custom Rule classes should extend. Please implement the
+     * Rule::validate() with your own logic and return 'true' if the validation was successful or 
+     * 'false' otherwise. Please use Validation::_setError() to set additional error codes reporting
+     * more information.
+     */
     class Rule extends Validation
     {
         /**
@@ -24,10 +47,13 @@
         /**
          * Validates the data. Does nothing here and it must be reimplemented by
          * every child class.
+         *
+         * @param value The value that we're going to validate
+         * @return True if successful or false otheriwse
          */
         function validate($value)
         {
-            throw(new Exception("qRule::validate: This method must be implemented by child classes."));
+            throw(new Exception("Rule::validate: This method must be implemented by child classes."));
             die();
         }
     }

Modified: plog/trunk/class/data/validator/rules/uintrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/uintrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/uintrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,18 +6,15 @@
     define( "ERROR_RULE_UINT_FORMAT_WRONG", "error_rule_uint_format_wrong");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+     * \ingroup Validator_Rules
+     *
+     * Validates that the given value is an unsigned integer or not. If unsuccessful, the error
+     * ERROR_RULE_UINT_FORMAT_WRONG will be set.
      */
     class UIntRule extends RegExpRule
     {
         /**
-         * The constructor does nothing.
+         * Initialize the rule
          */
         function UIntRule()
         {
@@ -25,8 +22,10 @@
         }
 
         /**
-         * Validates the data. Does nothing here and it must be reimplemented by
-         * every child class.
+         * Checks whether the given value is an unsigned integer
+         *
+         * @return True if successful or false otherwise. If unsuccessful, the error
+         * ERROR_RULE_UINT_FORMAT_WRONG will be set.
          */
         function validate($value)
         {

Modified: plog/trunk/class/data/validator/rules/urlformatrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/urlformatrule.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/urlformatrule.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,21 +1,21 @@
 <?php
 
-/**
-* I'm leaving the copyright just to give some credit to the original author... Good work here,
-* I guess he deserves it :)
-*
-* @copyright 2004Esben Maaløe esm-at-baseclassmodulweb.dk
-* @authorEsben Maaløe esm-at-baseclassmodulweb.dk
-* @license You are free to copy/modify this function to your hearts content
-*However I ask that you return any improvements you make to me,
-*and that you credit me in your sourcecode if you use it
-* @version 0.21
-*/
-
     include_once(PLOG_CLASS_PATH."class/data/validator/rules/rule.class.php");
     include_once(PLOG_CLASS_PATH."class/net/dns.class.php");
 		include_once(PLOG_CLASS_PATH."class/net/httpvars.class.php");
 
+   /**
+    * \ingroup Validator_Rules
+    *
+    * Checks that a given URL is valid.
+    *
+    * @copyright 2004Esben Maaløe esm-at-baseclassmodulweb.dk
+    * @authorEsben Maaløe esm-at-baseclassmodulweb.dk
+    * @license You are free to copy/modify this function to your hearts content
+    * However I ask that you return any improvements you make to me,
+    * and that you credit me in your sourcecode if you use it
+    * @version 0.21
+    */
 	class UrlFormatRule extends Rule
 	{
 	

Modified: plog/trunk/class/data/validator/stringvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/stringvalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/stringvalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,19 +1,14 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
 	include_once( PLOG_CLASS_PATH."class/data/validator/rules/nonemptyrule.class.php" );
 
     /**
-     * Checks that a string is not empty. That could be because it is
-     * 'null', there is really nothing ('') or it is just a bunch of
-     * blank spaces.
+     * \ingroup Validator
      *
-     * Classes can extend this one to provide a custom error message.
+     * Checks that a string is not empty. 
+     *
+     * @see NonEmptyRule
      */
     class StringValidator extends Validator 
     {

Modified: plog/trunk/class/data/validator/templatevalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/templatevalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/templatevalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH.'class/data/validator/validator.class.php' );
     include_once( PLOG_CLASS_PATH.'class/file/file.class.php' );
 
@@ -12,11 +7,28 @@
     define( 'ERROR_MISSING_BASE_FILES', -2 );
 
     /**
-     * Little class that will return true if a template set is valid
-     * or not.
+     * This is a more complex Validator (and a very specific one) that will validate whether
+     * the contents of a given folder are the same of a valid template set. In order to be valid
+     * a template folder must contain the following template files:
      *
-     * Could have moved this as a static method in the TemplateService
-     * class but didn't feel like making TemplateService too big after all...
+     * - main.template
+     * - postandcomments.template
+     * - commentarticle.template
+     * - posttrackbacks.template
+     * - error.template
+     * - album.template
+     * - albums.template
+     * - resource.template
+     *
+     * The template files should be inside a folder with the same name as template set.
+     *
+     * If the template set is not valid, this class will set one of the following errors:
+     * 
+     * - ERROR_TEMPLATE_NOT_INSIDE_FOLDER
+     * - ERROR_MISSING_BASE_FILES
+     *
+     * This Validator class is also a good example of the more complex things that can be achieved
+     * with Validator classes, not just simple data validation.
      */
     class TemplateValidator extends Validator 
 	{

Modified: plog/trunk/class/data/validator/uploadvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/uploadvalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/uploadvalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
 	include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
     include_once( PLOG_CLASS_PATH."class/misc/glob.class.php" );	
@@ -15,13 +10,24 @@
     define( "UPLOAD_VALIDATOR_ERROR_FORBIDDEN_EXTENSION", -2 );
 
 	/**
-     * This class is designed for administrators who want to have some rules on what can
-     * be uploaded. At the moment does nothing but accept that the file is valid, but many many
-     * things can be done here...
+	 * \ingroup Validator
+	 *
+     * Given a FileUpload object, checks that it is not bigger than the maximum size allowed
+     * and that it does not have one of the forbidden extensions.
+     *
+     * The maximum size allowed is controlled via the 'maximum_file_upload_size' configuration setting 
+     * and the list of forbidden extensions can be configured via the upload_forbidde_files configuration
+     * setting.
+     *
+     * If the validation is unsuccessful, the error codes UPLOAD_VALIDATOR_ERROR_UPLOAD_TOO_BIG or 
+     * UPLOAD_VALIDATOR_ERROR_FORBIDDEN_EXTENSION will be set.
      */
 	class UploadValidator extends Validator 
 	{
 
+        /**
+         * Constructor. Initializes the rule.
+         */
     	function UploadValidator()
         {
         	$this->Validator();

Modified: plog/trunk/class/data/validator/usernamevalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/usernamevalidator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/usernamevalidator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
 	include_once( PLOG_CLASS_PATH."class/data/validator/rules/nonemptyrule.class.php" );
 	include_once( PLOG_CLASS_PATH."class/data/validator/rules/regexprule.class.php" );
@@ -13,7 +8,18 @@
 	define( "ONLY_ALPHANUMERIC_REGEXP", "^([A-za-z0-9]*)$" );
 
     /**
-     * checks if a username is valid
+     * \ingroup Validator
+     *
+     * Checks if a username is valid. Usernames have to comply with the following rules:
+     *
+     * - They must not be empty
+     * - They must only be made of alphanumeric characters (a-z, A-Z and 0-9)
+     * - They must not be any of the forbidden usernames. Forbidden usernames can be configured
+     * via the 'forbidden_usernames' configuration parameter.
+     *
+     * @see NonEmptyRule
+     * @see RegExpRule
+     * @see FilteredWordsRule
      */
     class UsernameValidator extends Validator 
     {

Modified: plog/trunk/class/data/validator/validation.class.php
===================================================================
--- plog/trunk/class/data/validator/validation.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/validation.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,27 +1,23 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
     include_once( PLOG_CLASS_PATH."class/object/object.class.php");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+     * \ingroup Validator
+     *
+     * This is the base class that the Rule classes implement. Classes extending this one
+     * can use the private method _setError for raising custom error codes (in addition to 
+     * returning 'false' from the validate() method)
+     *
+     * Client classes can use the public method getError() to retrieve this error codes
+     * and perhaps show a more meaningful message based on its value (if any)
      */
     class Validation extends Object
     {
         var $_error;
 
         /**
-         * The constructor does nothing.
+         * Initialize the validation scheme
          */
         function Validation()
         {
@@ -30,27 +26,41 @@
         }
 
         /**
-        *    Add function info here
-        **/
+         * Set a custom error code or message
+         * 
+         * @param error The new error code
+         */
         function _setError($error)
         {
             $this->_error = $error;
         }
 
         /**
-        *    Add function info here
-        **/
+         * For client classes, use this method to retrieve the custom error code which was (if any)
+         * that was set in the validate() method. 
+         *
+         * It is not guaranteed that an unsuccessful result of the validate() method will set a custom
+         * error message, as that is completely up to the Validator class. Also depending on the 
+         * class we might get different return values from this method.
+         *
+         * @return An extended error message
+         */
         function getError()
         {
             return $this->_error;
         }
 
         /**
-        *    Add function info here
-        **/
+         * Implementation of the validation logic
+         *
+         * @param value The value that we're going to validate
+         * @return true if successful or false otherwise
+         * @see Rule::validate()
+         * @see Validator::validate()
+         */
         function validate($value)
         {
-            throw(new Exception("qValidation::validate: This method must be implemented by child classes."));
+            throw(new Exception("Validation::validate: This method must be implemented by child classes."));
             die();
         }
     }

Modified: plog/trunk/class/data/validator/validationlist.class.php
===================================================================
--- plog/trunk/class/data/validator/validationlist.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/validationlist.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,22 +1,11 @@
 <?php
 
-    /**
-     * @package data
-     */
-
-
     include_once( PLOG_CLASS_PATH."class/object/object.class.php");
 
     define(ERROR_RULE_IS_EMPTY, "error_rule_is_empty");
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+     * @private
      */
     class ValidationList extends Object
     {

Modified: plog/trunk/class/data/validator/validator.class.php
===================================================================
--- plog/trunk/class/data/validator/validator.class.php	2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/validator.class.php	2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,20 +1,55 @@
 <?php
 
     /**
-     * @package data
+     * \defgroup Validator
+     *
+     * Validator in pLog is an implementation of the 'Strategy' pattern as it can be seen
+     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/.
+     *
+     * Validator classes allow to reuse validation logic wherever needed, and in a uniform
+     * way since class users can safely assume that all validators implement the
+     * Validator::validate() method. 
+     *
+     * Validator classes in pLog can be built as a set of Rules, as a set of chained Validator
+     * classes or they can also bring their own non-reusable logic (non-reusable in the sense that 
+     * validation logic does not necessarily need to be part of a Rule class) 
+     *
+     * This the preferred way to validate data using a Validator class in pLog:
+     *
+     * <pre>
+     *  $val = new UsernameValidator();
+     *  if( !$val->validate( $newUsername ))
+     *    print( "the username $newUsername is not correct!" );
+     *  else
+     *    print( "the username is correct" );
+     * </pre>
+     *
+     * It is also possible to implemlent our own custom validators by extending the Validator base class
+     * and adding a few rules. Keep in mind that if we overwrite the Validator::validate() method, 
+     * we will lose some logic regarding rules. If our Validator class does not use rules, it is safe
+     * to overwrite such method and return 'true' if successful or false otherwise.
+     *
+     * In order to implement our own validator, the preferred way of doing it is by adding the necessary
+     * Validator and Rule objects in the constructor:
+     *
+     * <pre>
+     *  class NewValidator extend Validator {
+     *    function NewValidator() 
+     *    {
+     *     $this->addRule( new NonEmptyRule());
+     *     $this->addRule( new NumericRule()); 
+     *    }
+     *  }
+     * </pre>
      */
 
-
 	include_once( PLOG_CLASS_PATH."class/data/validator/validation.class.php" );
 
     /**
-     * This is an implementation of the 'Strategy' pattern as it can be seen
-     * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
-     * this pattern to validate data received from forms. Its is useful since for example
-     * we check in many places if a 'postId' is valid or not. We can put the
-     * checkings inside the class and simply reuse this class wherever we want. If we ever
-     *`change the format of the postId parameter, we only have to change the code of the
-     * class that validates it and it will be automatically used everywhere.
+     * \ingroup Validator
+     *
+     * Base class that all other validators extend. See the documentation of the Validator module for more
+     * information.
      */
     class Validator extends Validation 
     {
@@ -22,7 +57,7 @@
         var $_rules;
 
     	/**
-         * The constructor does nothing.
+         * Initializes the constructor
          */
     	function Validator()
         {
@@ -32,16 +67,21 @@
         }
         
         /**
-        *    Add function info here
-        **/
+         * Adds a rule to the Validator
+         *
+         * @param rule A valid Rule object
+         */
         function addRule(&$rule)
         {
             $this->_rules[] = &$rule;
         }
         
         /**
-        *    Add function info here
-        **/
+         * Our validators can also be built based on other validators. It is also possible
+         * to use the ChainedValidator if we don't wish to create a completely new Validator
+         *
+         * @param validator A Validator object or a class extending from it
+         */ 
         function addValidator(&$validator)
         {
             foreach ($validator->_rules as $rule)
@@ -51,8 +91,15 @@
         }                
 
         /**
-        *    Add function info here
-        **/
+         * This is the main method that takes care of processing all the rules. It is not necessary
+         * to reimplement this method in our custom Validator classes if we have already added some rules, 
+         * as this method already provides some logic for going through the rules and setting some extended
+         * error codes if necessary.
+         *
+         * If your custom validator does not use rules, it is safe to reimplement this method.
+         *
+         * @param value The value that we're going to validate.
+         */
         function validate($value)
         {
             foreach ($this->_rules as $rule)




More information about the pLog-svn mailing list