Merged in Olle's changes (comments). Olle, can you sync with the trunk? It's up to half an hour ago.

git-svn-id: https://svn.cakephp.org/repo/trunk/cake@213 3807eeeb-6ff5-0310-8944-8be069107fe0

app/views/pages/home.thtml

@@ -4,19 +4,19 @@
 
 <h2>Introducing Cake</h2>
 
-<p>Cake is a structure of libraries, classes and run-time infrastructure for PHP programmers. It's also what I use at work. It's based on certain conventions, so you may find it rigid at first. The directory structure is already layed out, and it's different from what most people use. From what I've experienced, great many PHP programmers start as web- or graphic-designers, i.e. they are not university-educated programmers as many in the C++ and Java-land. They invent their own, peculiar ways of solving problems and stick to them. Perhaps that's why so few people use Pear and Pecl libraries &ndash; they don't usually re-use their code. And I was one of them. (<?=$this->linkOut('continued...','http://sputnik.pl/docs/intro')?>)</p>
+<p>Cake is a structure of libraries, classes and run-time infrastructure for PHP programmers. It's also what I use at work. It's based on certain conventions, so you may find it rigid at first. The directory structure is already laid out, and it's different from what most people use. From what I've experienced, a great many PHP programmers start as web- or graphic-designers, i.e. they are not university-educated programmers as many in C++ and Java-land. They invent their own, peculiar ways of solving problems and stick to them. Perhaps that's why so few people use PEAR and PECL libraries &ndash; they don't usually re-use their code. And I was one of them. (<?=$this->linkOut('continued...','http://sputnik.pl/docs/intro')?>)</p>
 
 <h2>Features</h2>
 
 <p><ul>
 <li>compatibile with PHP4 and PHP5</li>
 <li>supplies integrated <acronym title="Create, Read, Update, Delete">CRUD</acronym> for database and simplified querying so you shouldn't need to write SQL for basic operations (although <em>some</em> familiarity with SQL is strongly recommended)</li>
-<li>request dispatcher with good looking, custom URLs</li>
+<li>request dispatcher with good-looking, custom URLs</li>
 <li>fast, flexible templating (PHP syntax with helper methods)</li>
 <li>works from a website subdirectory, with very little Apache configuration involved (requires <code>.htaccess</code> files and <code>mod_rewrite</code> to work; these are available on most web servers)</li>
 </ul></p>
 
-<p>Cake is in it's early infancy, but it works and I'm using it on a few projects. Currently the Dispatcher is working, the Model has <acronym title="Create, Read, Update, Delete">CRUD</acronym> functionality but with no joins between tables yet. The Controller is working and has the most basic functions (including <code>render()</code> for templating).</p>
+<p>Cake is in its early infancy, but it works and I'm using it on a few projects. Currently the Dispatcher is working, the Model has <acronym title="Create, Read, Update, Delete">CRUD</acronym> functionality but with no joins between tables yet. The Controller is working and has most basic functions (including <code>render()</code> for templating).</p>
 
 <h2>Getting involved</h2>
 

config/paths.php

@@ -30,49 +30,49 @@
  */
 
 /**
- * If index.php file is used instead of an .htaccess file
+ * If the index.php file is used instead of an .htaccess file
- * or if user can not set the web root to use the public
+ * or if the user can not set the web root to use the public
- * directory we will define ROOT there otherwise we set it
+ * directory we will define ROOT there, otherwise we set it
- * here
+ * here.
  */
 if( !defined('ROOT') ){
 	define ('ROOT',   '../');
 }
 
 /**
- * Path to the application directory.
+ * Path to the application's directory.
  */
 define ('APP',         ROOT.'app'.DS);
 
 /**
- * Path to the application models directory.
+ * Path to the application's models directory.
  */
 define ('MODELS',          APP.'models'.DS);
 
 /**
- * Path to the application controllers directory.
+ * Path to the application's controllers directory.
  */
 define ('CONTROLLERS',     APP.'controllers'.DS);
 
 /**
- * Path to the application helpers directory.
+ * Path to the application's helpers directory.
  */
 define ('HELPERS',         APP.'helpers'.DS);
 
 /**
- * Path to the application views directory.
+ * Path to the application's views directory.
  */
 define ('VIEWS',      	   APP.'views'.DS);
 
 /**
- * Path to the application view layouts directory.
+ * Path to the application's view's layouts directory.
  */
 define ('LAYOUTS',             APP.'views'.DS.'layouts'.DS);
 
 /**
- * Path to the application view elements directory.
+ * Path to the application's view's elements directory.
  * It's supposed to hold pieces of PHP/HTML that are used on multiple pages
- * and are not linked to a particular layout (like polls, footers and so on)
+ * and are not linked to a particular layout (like polls, footers and so on).
  */
 define ('ELEMENTS',            APP.'views'.DS.'elements'.DS);
 
@@ -122,7 +122,7 @@ define ('CONTROLLER_TESTS',TESTS.'app'.DS.'controllers'.DS);
 define ('HELPER_TESTS',   	TESTS.'app'.DS.'helpers'.DS);
 
 /**
- * Path to the models test directory.
+ * Path to the models' test directory.
  */
 define ('MODEL_TESTS',   	TESTS.'app'.DS.'models'.DS);
 

config/routes.php.default

@@ -33,20 +33,20 @@
  */
 
 /**
- * Here, we are connecting '/' (base path) to controller called 'Pages', 
+ * Here we are connecting '/' (base path) to a controller called 'Pages', 
- * its action called 'display', and we pass a param to select the view file 
+ * and its action called 'display'. We pass a parameter to select the view file 
- * to use (in this case, /app/views/pages/home.thtml)...
+ * to use (in this case, /app/views/pages/home.thtml).
  */
 $Route->connect ('/', array('controller'=>'Pages', 'action'=>'display', 'home'));
 
 /**
- * ...and connect the rest of 'Pages' controller's urls.
+ * ...and connect the rest of 'Pages' controller's URLs.
  */
 $Route->connect ('/pages/*', array('controller'=>'Pages', 'action'=>'display'));
 
 /**
- * Then we connect url '/test' to our test controller. This is helpfull in
+ * Then we connect url '/test' to our test controller. This is helpful in
- * developement.
+ * development.
  */
 $Route->connect ('/test', array('controller'=>'Tests', 'action'=>'test_all'));
 

config/tags.php

@@ -36,17 +36,17 @@
 define('TAG_LINK', '<a href="%s"%s>%s</a>');
 
 /**
- * Tag template for openning form tag. 
+ * Tag template for opening form tag. 
  */
 define('TAG_FORM', '<form %s>');
 
 /**
- * Tag template for an input tag. 
+ * Tag template for an input type='text' tag. 
  */
 define('TAG_INPUT',			'<input name="data[%s]" %s/>');
 
 /**
- * Tag template for a hidden tag. 
+ * Tag template for an input type='hidden' tag. 
  */
 define('TAG_HIDDEN',			'<input type="hidden" name="data[%s]" %s/>');
 
@@ -56,17 +56,17 @@ define('TAG_HIDDEN',			'<input type="hidden" name="data[%s]" %s/>');
 define('TAG_AREA',			'<textarea name="data[%s]"%s>%s</textarea>');
 
 /**
- * Tag template for a checkbox input tag. 
+ * Tag template for a input type='checkbox ' tag. 
  */
 define('TAG_CHECKBOX',		'<label for="tag_%s"><input type="checkbox" name="data[%s]" id="tag_%s" %s/>%s</label>');
 
 /**
- * Tag template for a radio input tag. 
+ * Tag template for a input type='radio' tag. 
  */
 define('TAG_RADIOS', 		'<label for="tag_%s"><input type="radio" name="data[%s]" id="tag_%s" %s/>%s</label>');
 
 /**
- * Tag template for a select openning tag. 
+ * Tag template for a select opening tag. 
  */
 define('TAG_SELECT_START', '<select name="data[%s]"%s>');
 
@@ -96,7 +96,7 @@ define('TAG_PASSWORD',		'<input type="password" name="data[%s]" %s/>');
 define('TAG_FILE',			'<input type="file" name="%s" %s/>');
 
 /**
- * Tag template for a submit tag. 
+ * Tag template for a submit button tag. 
  */
 define('TAG_SUBMIT',			'<input type="submit" %s/>');
 
@@ -126,7 +126,7 @@ define('TAG_TABLE_CELL',	'<td%s>%s</td>');
 define('TAG_TABLE_ROW',		'<tr%s>%s</tr>');
 
 /**
- * Tag template for a CSS meta-tag. 
+ * Tag template for a CSS link tag. 
  */
 define('TAG_CSS',          '<link rel="%s" type="text/css" href="%s" />');
 
@@ -136,12 +136,12 @@ define('TAG_CSS',          '<link rel="%s" type="text/css" href="%s" />');
 define('TAG_CHARSET',      '<meta http-equiv="Content-Type" content="text/html; charset=%s" />');
 
 /**
- * Tag template for inline JavaScript
+ * Tag template for inline JavaScript.
  */
 define('TAG_JAVASCRIPT', '<script language="javascript" type="text/javascript">%s</script>');
 
 /**
- * Tag template for included JavaScript
+ * Tag template for included JavaScript.
  */
 define('TAG_JAVASCRIPT_INCLUDE', '<script language="javascript" type="text/javascript" src="%s"></script>');
 

libs/dbo_mysql.php

@@ -43,7 +43,7 @@
 
 uses('dbo');
 /**
-  * Enter description here...
+  * MySQL layer for DBO.
   *
   *
   * @package cake
@@ -167,7 +167,8 @@ class DBO_MySQL extends DBO {
 	}
 
 /**
-  * Returns number of rows in previous resultset. If no previous resultset exists, this returns false.
+  * Returns number of rows in previous resultset. If no previous resultset exists, 
+  * this returns false.
   *
   * @return int Number of rows
   */

libs/dbo_postgres.php

@@ -36,7 +36,7 @@
 
 uses('object', 'dbo');
 /**
-  * Enter description here...
+  * PostgreSQL layer for DBO.
   *
   * @package cake
   * @subpackage cake.libs

libs/dispatcher.php

@@ -38,7 +38,7 @@
 uses('error_messages', 'object', 'router', 'controller');
 
 /**
-  * Enter description here...
+  * Dispatches the request, creating appropriate models and controllers.
   *
   *
   * @package cake

libs/error_messages.php

@@ -30,97 +30,97 @@
   */
 
 /**
-  * Enter description here...
+  * Error string for when the specified database driver can not be found.
   *
   */
 define ('ERROR_UNKNOWN_DATABASE_DRIVER', '[DbFactory] Specified database driver (%s) not found');
 
 /**
-  * Enter description here...
+  * Error string for when the dispatcher can not find a default controller.
   *
   */
 define ('ERROR_NO_CONTROLLER_SET', '[Dispatcher] No default controller, can\'t continue, check routes config');
 
 /**
-  * Enter description here...
+  * Error string for when the dispatcher can not find a default action.
   *
   */
 define ('ERROR_NO_ACTION_SET', '[Dispatcher] No default action, can\'t continue, check routes config');
 
 /**
-  * Enter description here...
+  * Error string for when the dispatcher can not find given controller.
   *
   */
 define ('ERROR_UNKNOWN_CONTROLLER', '[Dispatcher] Specified controller "%s" doesn\'t exist, create it first');
 
 /**
-  * Enter description here...
+  * Error string for when the dispatcher can not find expected action in controller.
   *
   */
 define ('ERROR_NO_ACTION', '[Dispatcher] Action "%s" is not defined in the "%s" controller, create it first');
 
 /**
-  * Enter description here...
+  * Error string for errors in view.
   *
   */
 define ('ERROR_IN_VIEW', '[Controller] Error in view "%s", got: <blockquote>%s</blockquote>');
 
 /**
-  * Enter description here...
+  * Error string for when the controller can not find expected view.
   *
   */
 define ('ERROR_NO_VIEW', '[Controller] No template file for view "%s" (expected "%s"), create it first');
 
 /**
-  * Enter description here...
+  * Error string for errors in layout.
   *
   */
 define ('ERROR_IN_LAYOUT', '[Controller] Error in layout "%s", got: <blockquote>"%s"</blockquote>');
 
 /**
-  * Enter description here...
+  * Error string for when the controller can not find expected layout.
   *
   */
 define ('ERROR_NO_LAYOUT', '[Controller] Couln\'t find layout "%s" (expected "%s"), create it first');
 
 /**
-  * Enter description here...
+  * Error string for database not being able to access the table list.
   *
   */
 define ('ERROR_NO_TABLE_LIST', '[Database] Couldn\'t get table list, check database config');
 
 /**
-  * Enter description here...
+  * Error string for No corresponding database table found for model.
   *
   */
 define ('ERROR_NO_MODEL_TABLE', '[Model] No DB table for model "%s" (expected "%s"), create it first');
 
 /**
-  * Enter description here...
+  * Error string for Field not present in table. 
   *
   */
 define ('ERROR_NO_FIELD_IN_MODEL_DB', '[Model::set()] Field "%s" is not present in table "%s", check database schema');
 
 /**
-  * Enter description here...
+  * Error string short short error message.
   *
   */
 define ('SHORT_ERROR_MESSAGE', '<div class="error_message"><i>%s</i></div>');
 
 /**
-  * Enter description here...
+  * Error string for when original image can not be loaded.
   *
   */
-define ('ERROR_CANT_GET_ORIGINAL_IMAGE', '[Image] Couln\'t load original image %s (tried from "%s")');
+define ('ERROR_CANT_GET_ORIGINAL_IMAGE', '[Image] Couldn\'t load original image %s (tried from "%s")');
 
 /**
-  * Enter description here...
+  * Error string for error 404.
   *
   */
 define ('ERROR_404', "The requested address /%s was not found on this server."); // second %s contains short error message
 
 /**
-  * Enter description here...
+  * Error string for error 500.
   *
   */
 define ('ERROR_500', "Application error, sorry.");

libs/flay.php

@@ -39,7 +39,7 @@
 uses('object');
 
 /**
-  * Enter description here...
+  * Text-to-html parser, similar to Textile or RedCloth, only with a little different syntax. 
   *
   *
   * @package cake

libs/folder.php

@@ -37,7 +37,7 @@
 uses('object');
 
 /**
-  * Enter description here...
+  * Folder structure browser, lists folders and files.
   *
   *
   * @package cake

libs/inflector.php

@@ -16,7 +16,7 @@
 /**
   * Purpose: Inflector
   * I'm trying to port RoR Inflector class here.
-  * Inflector pluralizes and singularizes english nouns.
+  * Inflector pluralizes and singularizes English nouns.
   * Test with $i = new Inflector(); $i->test();
   *
   * @filesource 
@@ -38,7 +38,9 @@
 uses('object');
 
 /**
-  * Enter description here...
+  * This is a port of Ruby on Rails' Inflector class.
+  * Inflector pluralizes and singularizes English nouns.
+  * Test with $i = new Inflector(); $i->test();
   *
   * @package cake
   * @subpackage cake.libs

libs/log.php

@@ -38,7 +38,10 @@ class Log {
 		return $log = fopen($fn, 'a+') && fwrite($log, $out) && fclose($log);
 	}
 }
-
+/**
+  * Error constant. Used for differentiating error logging and debugging.
+  *
+  */
 define ('LOG_ERROR', 2);
 
 ?>

libs/model.php

@@ -44,7 +44,11 @@
 uses('object', 'validators', 'inflector');
 
 /**
-  * Enter description here...
+  * DBO-backed object data model, loosely based on RoR (www.rubyonrails.com).
+  * Automatically selects a database table name based on a pluralized lowercase object class name
+  * (i.e. class 'User' => table 'users'; class 'Man' => table 'men')
+  * The table is required to have at least 'id auto_increment', 'created datetime', 
+  * and 'modified datetime' fields.
   *
   *
   * @package cake
@@ -79,7 +83,7 @@ class Model extends Object {
 	var $id = false;
 
 /**
-  * Enter description here...
+  * Container for the data that this model gets from persistent storage (the database).
   *
   * @var array
   * @access public
@@ -89,7 +93,7 @@ class Model extends Object {
 /**
   * Table name for this Model.
   *
-  * @var unknown_type
+  * @var string
   * @access public
   */
 	var $table = false;
@@ -103,7 +107,7 @@ class Model extends Object {
 	var $_table_info = null;
 
 /**
-  * Enter description here...
+  * Array of other Models this Model references in a one-to-many relationship. 
   *
   * @var array
   * @access private
@@ -111,7 +115,7 @@ class Model extends Object {
 	var $_oneToMany = array();
 
 /**
-  * Enter description here...
+  * Array of other Models this Model references in a one-to-one relationship. 
   *
   * @var array
   * @access private
@@ -119,7 +123,7 @@ class Model extends Object {
 	var $_oneToOne = array();
 
 /**
-  * Array of other Models this Model references in a hasMany relationship. 
+  * Array of other Models this Model references in a has-many relationship. 
   *
   * @var array
   * @access private
@@ -131,29 +135,27 @@ class Model extends Object {
   *
   * append entries for validation as ('field_name' => '/^perl_compat_regexp$/') that has to match with preg_match()
   * validate with Model::validate()
-  * @var unknown_type
+  * @var array
   */
 	var $validate = array();
 
 /**
   * Append entries for validation as ('field_name' => '/^perl_compat_regexp$/') that has to match with preg_match()
   * validate with Model::validate()
-  * @var unknown_type
+  * @var array
   */
 	var $validationErrors = null;
 
 /**
-  * Constructor binds the Model's database table
+  * Constructor. Binds the Model's database table to the object.
   *
   * @param unknown_type $id
+  * @param unknown_type $db Database connection object.
   */
 	function __construct ($id=false, $db=null) {
 		global $DB;
 
-		if ($db)
+		$this->db = $db? $db: &$DB;
-			$this->db = $db;
-		else
-			$this->db = &$DB;
 
 		if ($id) 
 			$this->id = $id;
@@ -165,7 +167,9 @@ class Model extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Creates has-many relationships, and then call relink.
+  *
+  * @see relink()
   *
   */
 	function createLinks () {
@@ -182,7 +186,7 @@ class Model extends Object {
 	}
 
 /**
-  * Updates the many-to-one links, by emptying the links list, and linkManyToOne again.
+  * Updates this model's many-to-one links, by emptying the links list, and then linkManyToOne again.
   *
   * @see linkManyToOne()
   *
@@ -218,9 +222,9 @@ class Model extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Sets a custom table for your controller class. Used by your controller to select a database table.
   *
-  * @param unknown_type $table_name
+  * @param string $table_name Name of the custom table
   */
 	function useTable ($table_name) {
 		if (!in_array($table_name, $this->db->tables())) {
@@ -242,8 +246,8 @@ class Model extends Object {
   * (Alternative indata: two strings, which are mangled to 
   * a one-item, two-dimensional array using $one for a key and $two as its value.)
   *
-  * @param mixed $one Array or string.
+  * @param mixed $one Array or string of data
-  * @param string $two Optional string
+  * @param string $two Value string for the alternative indata method
   * @return unknown
   */
 	function set ($one, $two=null) {
@@ -265,7 +269,7 @@ class Model extends Object {
     }
 
 /**
-  * Sets current id to given $id.
+  * Sets current Model id to given $id.
   *
   * @param int $id Id
   */
@@ -277,7 +281,7 @@ class Model extends Object {
 /**
   * Returns an array of table metadata (column names and types) from the database.
   *
-  * @return array
+  * @return array Array of table metadata
   */
 	function loadInfo () {
 		if (empty($this->_table_info))
@@ -287,10 +291,10 @@ class Model extends Object {
 
 /**
   * Returns true if given field name exists in this Model's database table.
-  * Starts by pre-caching the metadata into the private property table_info if that is not already set. 
+  * Starts by loading the metadata into the private property table_info if that is not already set. 
   *
   * @param string $name Name of table to look in
-  * @return unknown
+  * @return boolean
   */
 	function hasField ($name) {
 		if (empty($this->_table_info)) $this->loadInfo();
@@ -300,9 +304,8 @@ class Model extends Object {
 /**
   * Returns a list of fields from the database
   *
-  * @param string $fields
+  * @param mixed $fields String of single fieldname, or an array of fieldnames.
-  * @param array $fields
+  * @return array Array of database fields
-  * @return array of values
   */
 	function read ($fields=null) {
 		$this->validationErrors = null;
@@ -338,7 +341,7 @@ class Model extends Object {
   *
   * @param string $name Name of the table field
   * @param mixed $value Value of the field
-  * @return success
+  * @return boolean True on success save
   */
 	function saveField($name, $value) {
 		return $this->save(array($name=>$value), false);
@@ -347,9 +350,9 @@ class Model extends Object {
 /**
   * Saves model data to the database.
   *
-  * @param array $data
+  * @param array $data Data to save. 
   * @param boolean $validate
-  * @return success
+  * @return boolean success
   */
 	function save ($data=null, $validate=true) {
 		if ($data) $this->set($data);

libs/object.php

@@ -46,7 +46,7 @@ class Object {
 /**
   * A hack to support __construct() on PHP 4
   * Hint: descendant classes have no PHP4 class_name() constructors,
-  * so this one gets called first and calls the top-layer __construct()
+  * so this constructor gets called first and calls the top-layer __construct()
   * which (if present) should call parent::__construct()
   *
   * @return Object
@@ -58,13 +58,13 @@ class Object {
 	}
 
 /**
-  * Class constructor, overriden in descendant classes.
+  * Class constructor, overridden in descendant classes.
   */
 	function __construct() {
 	}
 
 /**
-  * Class destructor, overriden in descendant classes.
+  * Class destructor, overridden in descendant classes.
   */
 	function __destruct() {
 	}
@@ -73,7 +73,7 @@ class Object {
   * Object-to-string conversion.
   * Each class can override it as necessary.
   *
-  * @return string this class' name
+  * @return string This name of this class
   */
 	function toString () {
 		return get_class($this);
@@ -83,7 +83,7 @@ class Object {
   * API for logging events.
   *
   * @param string $msg Log message
-  * @param string $type
+  * @param int $type Error type constant. Defined in /libs/log.php.
   */
 	function log ($msg, $type=LOG_ERROR) {
 		if (!$this->_log)

libs/router.php

@@ -15,7 +15,7 @@
 
 /**
   * Purpose: Router
-  * Parses the request URL into controller, action, and params
+  * Parses the request URL into controller, action, and parameters.
   *
   * @filesource 
   * @author Cake Authors/Developers
@@ -37,7 +37,7 @@
 uses('object');
 
 /**
-  * Enter description here...
+  * Parses the request URL into controller, action, and parameters.
   *
   *
   * @package cake
@@ -48,14 +48,14 @@ uses('object');
 class Router extends Object {
 
 /**
-  * Enter description here...
+  * Array of routes
   *
-  * @var unknown_type
+  * @var array
   */
 	var $routes = array();
 
 /**
-  * Enter description here...
+  * Constructor.
   *
   */
 	function __construct () {
@@ -63,10 +63,12 @@ class Router extends Object {
 	}
 	
 /**
-  * Enter description here...
+  * TODO: Better description. Returns this object's routes array. Returns false if there are no routes available.
   *
-  * @param unknown_type $route
+  * @param string $route An empty string, or a route string "/"
-  * @param unknown_type $default
+  * @param array $default NULL or an array describing the default route
+  * @see routes
+  * @return array Array of routes
   */
 	function connect ($route, $default=null) {
 		$parsed = $names = array ();
@@ -104,10 +106,10 @@ class Router extends Object {
 	}
 
 /**
-  * Enter description here...
+  * TODO: Better description. Returns an array of routes.
   *
-  * @param unknown_type $url
+  * @param string $url URL to be parsed 
-  * @return unknown
+  * @return array 
   */
 	function parse ($url) {
 		$out = array();

libs/template.php

@@ -37,7 +37,8 @@
 uses('object');
 
 /**
-  * Enter description here...
+  * Templating for Controller class. Takes care of rendering views.
+  * 
   *
   *
   * @package cake
@@ -58,7 +59,7 @@ class Template extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var string
   * @access public
   */
 	var $layout = 'default';
@@ -66,7 +67,7 @@ class Template extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var boolean
   * @access public
   */
 	var $autoRender = true;
@@ -74,15 +75,15 @@ class Template extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var boolean
   * @access public
   */
 	var $autoLayout = true;
 
 /**
-  * Enter description here...
+  * Variables for the view
   *
-  * @var unknown_type
+  * @var array
   * @access private
   */
 	var $_view_vars = array();
@@ -90,13 +91,13 @@ class Template extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var boolean
   * @access private
   */
 	var $_page_title = false;
 
 /**
-  * Enter description here...
+  * Constructor. 
   *
   */
 	function __construct () {
@@ -115,8 +116,8 @@ class Template extends Object {
 /**
   * Enter description here...
   *
-  * @param unknown_type $one
+  * @param mixed $one An array of POST data. (Or: a string of a single POST datum.)
-  * @param unknown_type $two
+  * @param string $two Value in case $one is a string (which then works as the key).
   * @return unknown
   */
 	function set($one, $two=null) {
@@ -124,18 +125,18 @@ class Template extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Set the title element of the page.
   *
-  * @param unknown_type $value
+  * @param string $pageTitle Text for the title
   */
-	function setTitle ($value) {
+	function setTitle ($pageTitle) {
-		$this->_page_title = $value;
+		$this->_page_title = $pageTitle;
 	}
 
 /**
-  * Enter description here...
+  * Sets data for this view. Will set title is the key "title" is in given $data array.
   *
-  * @param unknown_type $data
+  * @param array $data Array of 
   */
 	function _setArray($data) {
 		foreach ($data as $name => $value) {
@@ -147,11 +148,11 @@ class Template extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Displays a flash message. A flash message is feedback to the user that displays after editing actions, among other things.
   *
-  * @param unknown_type $message
+  * @param string $message Text to display to the user
-  * @param unknown_type $url
+  * @param string $url URL fragment
-  * @param unknown_type $time
+  * @param int $time Display time, in seconds
   */
 	function flash ($message, $url, $time=1) {
 		$this->autoRender = false;
@@ -165,11 +166,12 @@ class Template extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Render view for given action and layout. If $file is given, that is used 
+  * for a view filename (e.g. customFunkyView.thtml).
   *
-  * @param unknown_type $action
+  * @param string $action Name of action to render for
-  * @param unknown_type $layout
+  * @param string $layout 
-  * @param unknown_type $file
+  * @param string $file Custom filename for view
   */
 	function render ($action=null, $layout=null, $file=null) {
 		$this->autoRender = false;
@@ -199,10 +201,10 @@ class Template extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Enter description here... Renders a layout. Returns output from _render(). Returns false on error.
   *
-  * @param unknown_type $content_for_layout
+  * @param string $content_for_layout Content to render in a view
-  * @return unknown
+  * @return string Rendered output
   */
 	function renderLayout ($content_for_layout) {
 		$layout_fn = $this->_getLayoutFn();
@@ -230,10 +232,11 @@ class Template extends Object {
 	}
 
 /**
-  * Renders a piece of PHP with provided params and returns HTML, XML, or any other string.
+  * Renders a piece of PHP with provided parameters and returns HTML, XML, or any other string.
   *
-  * @param unknown_type $content_for_layout
+  * @param string $name Name of template file
-  * @return unknown
+  * @param array $params Array of data for rendered view 
+  * @return string Rendered output
   */
 	function renderElement ($name, $params=array()) {
 		$fn = ELEMENTS.$name.'.thtml';
@@ -245,31 +248,32 @@ class Template extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns layout filename for this template as a string.
   *
-  * @return unknown
+  * @return string Filename for layout file (.thtml).
   */
 	function _getLayoutFn() {
 		return VIEWS."layouts".DS."{$this->layout}.thtml";
 	}
 
 /**
-  * Enter description here...
+  * Returns filename of given action's template file (.thtml) as a string.
   *
-  * @param unknown_type $action
+  * @param string $action Controller action to find template filename for
-  * @return unknown
+  * @return string Template filename
   */
 	function _getViewFn($action) {
 		return VIEWS.$this->viewpath.DS."{$action}.thtml";
 	}
 
 /**
-  * Enter description here...
+  * Renders and returns output for given view filename with its 
+  * array of data.
   *
-  * @param unknown_type $___view_fn
+  * @param string $___view_fn Filename of the view
-  * @param unknown_type $___data_for_view
+  * @param array $___data_for_view Data to include in rendered view
-  * @param unknown_type $___play_safe
+  * @param boolean $___play_safe If set to false, the include() of the $__view_fn is done without suppressing output of errors
-  * @return unknown
+  * @return string Rendered output
   */
 	function _render($___view_fn, $___data_for_view, $___play_safe = true) {
 		extract($___data_for_view, EXTR_SKIP); # load all view variables
@@ -288,11 +292,11 @@ class Template extends Object {
 	}
 
 /**
-  * trims a string to a specified length adding elipsis '..' if necessary
+  * Returns given string trimmed to given length, adding an elipsis '..' if necessary.
   *
-  * @param unknown_type $string
+  * @param string $string String to trim
-  * @param unknown_type $length
+  * @param int $length Length of returned string, excluding ellipsis
-  * @return unknown
+  * @return string Trimmed string
   */
 	function trimTo ($string, $length) {
 		return substr($string, 0, $length).(strlen($string)>$length? '..': null);

libs/test.php

@@ -74,7 +74,7 @@ if (phpversion() >= '4') {
 	  }
 }
 /**
-  * Enter description here...
+  * Exception class for testing
   *
   *
   * @package cake
@@ -126,7 +126,7 @@ class TestException {
 }
 
 /**
-  * Enter description here...
+  * Asserts for Unit Testing
   *
   *
   * @package cake
@@ -587,7 +587,7 @@ class TestCase extends Assert /* implements Test */ {
 
 
 /**
-  * Enter description here...
+  * Test Suite for Unit Testing.
   *
   *
   * @package cake
@@ -722,7 +722,7 @@ class TestSuite /* implements Test */ {
 
 
 /**
-  * Enter description here...
+  * Test Failure for Unit Testing
   *
   *
   * @package cake
@@ -788,7 +788,7 @@ class TestFailure {
 
 
 /**
-  * Enter description here...
+  * Test Result for Unit Testing
   *
   *
   * @package cake
@@ -959,7 +959,7 @@ class TestResult {
 }
 
 /**
-  * Enter description here...
+  * Mines data from test results. Used for Unit Testing.
   *
   *
   * @package cake
@@ -975,15 +975,15 @@ class ResultDataMiner extends TestResult {
   */
 	var $tests = null;
 /**
-  * Enter description here...
+  * Total number of tests
   *
-  * @var unknown_type
+  * @var int
   */
 	var $total_tests = 0;
 /**
-  * Enter description here...
+  * Total number of errors
   *
-  * @var unknown_type
+  * @var int
   */
 	var $total_errors = 0;
 
@@ -1025,9 +1025,9 @@ class ResultDataMiner extends TestResult {
 	}
 
 /**
-  * Enter description here...
+  * Returns an array with total number of performed tests, total number of errors, and details of the tests.
   *
-  * @return unknown
+  * @return array Array with information on how the tests went. 
   */
 	function report () {
 		return array('tests'=>$this->total_tests, 'errors'=>$this->total_errors, 'details'=>$this->tests);
@@ -1036,7 +1036,7 @@ class ResultDataMiner extends TestResult {
 }
 
 /**
-  * Enter description here...
+  * Test Runner for Unit Testing.
   *
   *
   * @package cake
@@ -1045,9 +1045,8 @@ class ResultDataMiner extends TestResult {
   *
   */
 class TestRunner {
-	/* Run a suite of tests and report results. */
 /**
-  * Enter description here...
+  * Run a suite of tests and report results.
   *
   * @param unknown_type $suite
   * @return unknown

libs/time.php

@@ -37,7 +37,7 @@
 uses ('object');
 
 /**
-  * Enter description here...
+  * Time related functions, formatting for dates etc.
   *
   *
   * @package cake
@@ -48,10 +48,10 @@ uses ('object');
 class Time extends Object {
 
 /**
-  * Enter description here...
+  * Returns a formatted date string for given Datetime string.
   *
-  * @param unknown_type $date_string
+  * @param string $date_string Datetime string
-  * @return unknown
+  * @return string Formatted date string
   */
 	function nice ($date_string=null) {
 		$date = $date_string? strtotime($date_string): time();
@@ -59,10 +59,14 @@ class Time extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns a formatted descriptive date string for given datetime string.
+  * If the given date is today, the returned string could be "Today, 16:54".
+  * If the given date was yesterday, the returned string could be "Yesterday, 16:54".
+  * If $date_string's year is the current year, the returned string does not
+  * include mention of the year.
   *
   * @param string $date_string Datetime string
-  * @return unknown
+  * @return string Described, relative date string
   */
 	function niceShort ($date_string=null) {
 		$date = $date_string? Time::fromString($date_string): time();
@@ -108,7 +112,7 @@ class Time extends Object {
 	}
 
 /**
-  * Returns a Unix timestamp from a textual datetime description. Wrapper for PHP function strtotime().
+  * Returns a Unix timestamp for a datetime string. Wrapper for PHP function strtotime().
   *
   * @param string $date_string Datetime string to be represented as a Unix timestamp
   * @return int Unix timestamp
@@ -118,19 +122,19 @@ class Time extends Object {
 	}
 
 /**
-  * Formats date for Atom RSS feeds
+  * Returns a date formatted for Atom RSS feeds.
   *
-  * @param datetime $date
+  * @param string $date Datetime string
-  * @return string
+  * @return string Formatted date string
   */
 	function toRss ($date) {
 		return date('Y-m-d', $date).'T'.date('H:i:s', $date).'Z';
 	}
 
 /**     
- *      This function returns either a relative date or a formatted date depending
+ *      Returns either a relative date or a formatted date depending
- *      on the difference between the current datetime and the datetime passed.
+ *      on the difference between the current time and given datetime.
- *      $datetime should be in a <i>strtotime<i/i> parsable format like MySQL datetime.
+ *      $datetime should be in a <i>strtotime</i>-parsable format like MySQL datetime.
  *      
  *      Relative dates look something like this:
  *          3 weeks, 4 days ago
@@ -138,10 +142,10 @@ class Time extends Object {
  *      Formatted dates look like this:
  *          on 02/18/2004
  *      
- *      The function includes 'ago' or 'on' and assumes you'll properly add a word
+ *      The returned string includes 'ago' or 'on' and assumes you'll properly add a word
  *      like 'Posted ' before the function output.
  *      
- * @param $datetime	Time in strtotime parsable format
+ * @param $datetime	Time in strtotime-parsable format
  * @return string Relative time string.
  */
 

libs/validators.php

@@ -32,16 +32,19 @@
 
 /**
   * Not empty.
+  *
   */
 define('VALID_NOT_EMPTY', '/.+/');
 
 /**
   * Numbers [0-9] only.
+  *
   */
 define('VALID_NUMBER', '/^[0-9]+$/');
 
 /**
   * A valid email address.
+  *
   */
 define('VALID_EMAIL', '/^([a-z0-9][a-z0-9_\-\.\+]*)@([a-z0-9][a-z0-9\.\-]{0,63}\.[a-z]{2,3})$/i');