From 9bbe2759032b7373a8d4a6f148636f3c6775f9c3 Mon Sep 17 00:00:00 2001
From: pies <pies@3807eeeb-6ff5-0310-8944-8be069107fe0>
Date: Tue, 31 May 2005 23:18:22 +0000
Subject: [PATCH] (I don't know what's happening:/ )

git-svn-id: https://svn.cakephp.org/repo/trunk/cake@207 3807eeeb-6ff5-0310-8944-8be069107fe0
---
 app/controllers/pages_controller.php |   3 +
 app/controllers/tests_controller.php |   3 +
 libs/bake.php                        |  16 +-
 libs/basics.php                      |  28 +-
 libs/cache.php                       |  38 +-
 libs/controller.php                  | 592 +++++++++++++++++++++------
 libs/dbo.php                         |  93 +++--
 libs/dbo_adodb.php                   |  38 +-
 libs/dbo_mysql.php                   |  56 +--
 libs/dbo_postgres.php                |  46 +--
 libs/dispatcher.php                  |  52 +--
 libs/flay.php                        |  14 +-
 libs/folder.php                      |  81 ++--
 libs/inflector.php                   |  52 +--
 libs/model.php                       | 200 +++++----
 libs/object.php                      |  12 +-
 libs/test.php                        |  44 +-
 libs/time.php                        |  32 +-
 libs/validators.php                  |  24 +-
 19 files changed, 892 insertions(+), 532 deletions(-)

diff --git a/app/controllers/pages_controller.php b/app/controllers/pages_controller.php
index 12a27db40..28dbf598d 100644
--- a/app/controllers/pages_controller.php
+++ b/app/controllers/pages_controller.php
@@ -2,6 +2,9 @@
 
 class PagesController extends PagesHelper {
 
+/**
+ *  Displays a view
+ */
 	function display () {
 
 		if (!func_num_args())
diff --git a/app/controllers/tests_controller.php b/app/controllers/tests_controller.php
index 9cc5dc220..5b3702786 100644
--- a/app/controllers/tests_controller.php
+++ b/app/controllers/tests_controller.php
@@ -4,6 +4,9 @@ uses('test', 'folder', 'inflector');
 
 class TestsController extends TestsHelper {
 
+/**
+ *  Runs all library and application tests
+ */
 	function test_all () {
 
 		$this->layout = 'test';
diff --git a/libs/bake.php b/libs/bake.php
index d78a2d806..5b8402379 100644
--- a/libs/bake.php
+++ b/libs/bake.php
@@ -70,7 +70,7 @@ class Bake extends Object {
 	var $stderr = null;
 
 	/**
-	 * Counts taken actions.
+	 * Counts actions taken.
 	 *
 	 * @var integer
 	 * @access private
@@ -78,7 +78,7 @@ class Bake extends Object {
 	var $actions = null;
 
 	/**
-	 * Decides wether to overwrite existing files without asking.
+	 * Decides whether to overwrite existing files without asking.
 	 *
 	 * @var boolean
 	 * @access private
@@ -86,7 +86,7 @@ class Bake extends Object {
 	var $dontAsk = false;
 
 	/**
-	 * Returns template for file generator.
+	 * Returns code template for PHP file generator.
 	 *
 	 * @param string $type
 	 * @return string
@@ -195,8 +195,8 @@ class %sTest extends TestCase {
 	 * @param string $controller
 	 * @param string $name
 	 * @access private
-	 * @uses Inflector::underscore() Underscores directory' name.
-	 * @uses Bake::createDir() Creates new directory in views, depending on the controller's name.
+	 * @uses Inflector::underscore() Underscores directory's name.
+	 * @uses Bake::createDir() Creates new directory in views dir, named after the controller.
 	 * @uses VIEWS
 	 * @uses Bake::createFile() Creates view file.
 	 * @uses Bake::template() Collects view template.
@@ -358,7 +358,7 @@ class %sTest extends TestCase {
 	}
 
 	/**
-	 * Returns array of actions' templates.
+	 * Returns an array of actions' templates.
 	 *
 	 * @param array $as
 	 * @return array
@@ -373,7 +373,7 @@ class %sTest extends TestCase {
 	}
 
 	/**
-	 * Returns test template for defined class.
+	 * Returns a test template for given class.
 	 *
 	 * @param string $class
 	 * @return string
@@ -403,7 +403,7 @@ class %sTest extends TestCase {
 	}
 
 	/**
-	 * Returns underscored name for model's file.
+	 * Returns an underscored filename for a model.
 	 *
 	 * @param string $name
 	 * @return string
diff --git a/libs/basics.php b/libs/basics.php
index 0f75de07e..9eded39a9 100644
--- a/libs/basics.php
+++ b/libs/basics.php
@@ -65,7 +65,7 @@ function loadControllers () {
 }
 
 /**
-  * Loads a controller and it's helper libraries
+  * Loads a controller and its helper libraries.
   *
   * @param string $name
   * @return boolean
@@ -83,7 +83,7 @@ function loadController ($name) {
 }
 
 /**
-  * Lists PHP files in a specified directory
+  * Lists PHP files in given directory.
   *
   * @param string $path
   * @return array
@@ -143,7 +143,6 @@ function debug($var = false, $show_html = false) {
 
 
 if (!function_exists('getMicrotime')) {
-
 /**
  * Returns microtime for execution time checking.
  *
@@ -154,13 +153,14 @@ if (!function_exists('getMicrotime')) {
 		return ((float)$usec + (float)$sec);
 	}
 }
+
 if (!function_exists('sortByKey')) {
 /**
  * Sorts given $array by key $sortby.
  *
  * @param array $array
  * @param string $sortby
- * @param string $order
+ * @param string $order Sort order asc/desc (ascending or descending).
  * @param integer $type
  * @return mixed
  */
@@ -190,7 +190,7 @@ if (!function_exists('sortByKey')) {
 if (!function_exists('array_combine')) {
 /**
  * Combines given identical arrays by using the first array's values as keys,
- * and second one's values as values.
+ * and the second one's values as values. (Implemented for back-compatibility with PHP4.)
  *
  * @param array $a1
  * @param array $a2
@@ -216,7 +216,7 @@ if (!function_exists('array_combine')) {
 }
 
 /**
- * Class used for internal manipulation of multiarrays (arrays of arrays)
+ * Class used for internal manipulation of multiarrays (arrays of arrays).
  *
  * @package cake
  * @subpackage cake.libs
@@ -232,7 +232,7 @@ class NeatArray {
     var $value;
     
 	/**
-	 * Constructor.
+	 * Constructor. Defaults to an empty array.
 	 *
 	 * @param array $value
 	 * @access public
@@ -243,7 +243,7 @@ class NeatArray {
 	}
 
 	/**
-	 * Checks wheter $fieldName with $value exists in this NeatArray object.
+	 * Checks whether $fieldName with $value exists in this NeatArray object.
 	 *
 	 * @param string $fieldName
 	 * @param string $value
@@ -282,7 +282,7 @@ class NeatArray {
 	/**
 	 * Adds elements from the supplied array to itself.
 	 *
-	 * @param string $array
+	 * @param string $value 
 	 * @return bool
 	 * @access public
 	 * @uses NeatArray::value
@@ -293,9 +293,9 @@ class NeatArray {
 
 
 	/**
-	 * Returns itself merged with supplied array.
+	 * Returns itself merged with given array.
 	 *
-	 * @param string $array
+	 * @param array $value Array to add to NeatArray.
 	 * @return array
 	 * @access public
 	 * @uses NeatArray::value
@@ -307,7 +307,7 @@ class NeatArray {
 	/**
 	 * Counts repeating strings and returns an array of totals.
 	 *
-	 * @param int $sortedBy 1 sorts by values, 2 by keys, default null (no sort)
+	 * @param int $sortedBy A value of 1 sorts by values, a value of 2 sorts by keys. Defaults to null (no sorting).
 	 * @return array
 	 * @access public
 	 * @uses NeatArray::value
@@ -333,7 +333,7 @@ class NeatArray {
 	}
 
 	/**
-	 * Passes each of it's values thrue a specified function or method.
+	 * Passes each of its values through a specified function or method. Think of PHP's array_walk.
 	 *
 	 * @return array
 	 * @access public
@@ -345,7 +345,7 @@ class NeatArray {
 	}
 
 	/**
-	 * Extracts a value from all array items
+	 * Extracts a value from all array items.
 	 *
 	 * @return array
 	 * @access public
diff --git a/libs/cache.php b/libs/cache.php
index 1ffb3d90b..a61e0866b 100644
--- a/libs/cache.php
+++ b/libs/cache.php
@@ -46,35 +46,35 @@ uses('model');
 class Cache extends Model {
 
 /**
-  * Enter description here...
+  * Identifier. Either an MD5 string or NULL.
   *
   * @var unknown_type
   */
 	var $id = null;
 
 /**
-  * Enter description here...
+  * Content container for cache data.
   *
   * @var unknown_type
   */
 	var $data = null;
 
 /**
-  * Enter description here...
+  * Content to be cached.
   *
   * @var unknown_type
   */
 	var $for_caching = null;
 
 /**
-  * Enter description here...
+  * Name of the database table used for caching.
   *
   * @var unknown_type
   */
 	var $use_table = 'cache';
 
 /**
-  * Enter description here...
+  * Constructor. Generates an md5'ed id for internal use. Calls the constructor on Model as well.
   *
   * @param unknown_type $id
   */
@@ -84,7 +84,7 @@ class Cache extends Model {
 	}
 
 /**
-  * Enter description here...
+  * Returns this object's id after setting it. If no $id is given then $this->id is returned.
   *
   * @param unknown_type $id
   * @return unknown
@@ -95,10 +95,10 @@ class Cache extends Model {
 	}
 
 /**
-  * Enter description here...
+  * Save $content in cache for $keep_for seconds.
   *
-  * @param unknown_type $content
-  * @param unknown_type $keep_for
+  * @param string $content Content to keep in cache.
+  * @param int $keep_for Number of seconds to keep data in cache.
   * @return unknown
   */
 	function remember ($content, $keep_for=CACHE_PAGES_FOR) {
@@ -108,11 +108,11 @@ class Cache extends Model {
 	}
 
 /**
-  * Enter description here...
+  * Returns content from the Cache object itself, if the Cache object has a non-empty data property. Else from the database cache.
   *
   * @return unknown
   */
-	function restore () {
+	function restore() {
 		if (empty($this->data['data']))
 			return $this->find("id='{$this->id}' AND expire>NOW()");
 		
@@ -120,29 +120,29 @@ class Cache extends Model {
 	}
 
 /**
-  * Enter description here...
+  * Returns true if the cache data property has current (non-stale) content for given id.
   *
-  * @return unknown
+  * @return boolean
   */
-	function has () {
+	function has() {
 		return is_array($this->data = $this->find("id='{$this->id}' AND expire>NOW()"));
 	}
 
 /**
-  * Enter description here...
+  * Appends $string to the for_caching property of the Cache object.
   *
-  * @param unknown_type $string
+  * @param string $string
   */
-	function append ($string) {
+	function append($string) {
 		$this->for_caching .= $string;
 	}
 
 /**
-  * Enter description here...
+  * Clears the cache database table.
   *
   * @return unknown
   */
-	function clear () {
+	function clear() {
 		return $this->query("DELETE FROM {$this->use_table}");
 	}
 }
diff --git a/libs/controller.php b/libs/controller.php
index d30244a98..55d72f53e 100644
--- a/libs/controller.php
+++ b/libs/controller.php
@@ -51,7 +51,7 @@ uses('model', 'template', 'inflector', 'folder');
 class Controller extends Template {
     
 /**
-  * Enter description here...
+  * Name of the controller.
   *
   * @var unknown_type
   * @access public
@@ -75,7 +75,7 @@ class Controller extends Template {
     var $action = null;
 
 /**
-  * Enter description here...
+  * This Controller's Model.
   *
   * @var unknown_type
   * @access public
@@ -99,7 +99,7 @@ class Controller extends Template {
     var $_crumbs = array();
 
 /**
-  * Enter description here...
+  * Constructor. 
   *
   */
 	function __construct () {
@@ -140,7 +140,7 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Redirects to given $url, after turning off $this->autoRender.
   *
   * @param unknown_type $url
   */
@@ -162,30 +162,32 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns an URL for a combination of controller and action.
   *
-  * @param unknown_type $url
-  * @return unknown
+  * @param string $url
+  * @return string Full constructed URL as a string.
   */
 	function urlFor ($url=null) {
 		if (empty($url)) {
-			return $this->base.'/'.strtolower($this->params['controller']).'/'.strtolower($this->params['action']);
+			$out = $this->base.'/'.strtolower($this->params['controller']).'/'.strtolower($this->params['action']);
 		}
 		elseif ($url[0] == '/') {
-			return $this->base . $url;
+			$out = $this->base . $url;
 		}
 		else {
-			return $this->base . '/' . strtolower($this->params['controller']) . '/' . $url;
+			$out = $this->base . '/' . strtolower($this->params['controller']) . '/' . $url;
 		}
+
+		return ereg_replace('&([^a])', '&amp;\1', $out);
 	}
 
 /**
-  * Enter description here...
+  * Returns a space-separated string with items of the $options array.
   *
-  * @param unknown_type $options
-  * @param unknown_type $insert_before
+  * @param array $options Array of HTML options.
+  * @param string $insert_before
   * @param unknown_type $insert_after
-  * @return unknown
+  * @return string
   */
 	function parseHtmlOptions ($options, $insert_before=' ', $insert_after=null) {
 		if (is_array($options)) {
@@ -202,13 +204,13 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns an HTML link to $url for given $title, optionally using $html_options and $confirm_message (for "flash").
   *
-  * @param unknown_type $title
-  * @param unknown_type $url
-  * @param unknown_type $html_options
-  * @param unknown_type $confirm_message
-  * @return unknown
+  * @param string $title The content of the A tag.
+  * @param string $url
+  * @param array $html_options Array of HTML options.
+  * @param string $confirm_message Message to be shown in "flash".
+  * @return string
   */
 	function linkTo ($title, $url, $html_options=null, $confirm_message=false) {
 		$confirm_message? $html_options['onClick'] = "return confirm('{$confirm_message}')": null;
@@ -216,12 +218,12 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns an external HTML link to $url for given $title, optionally using $html_options.
   *
-  * @param unknown_type $title
-  * @param unknown_type $url
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $title
+  * @param string $url
+  * @param array $html_options
+  * @return string
   */
 	function linkOut ($title, $url=null, $html_options=null) {
 		$url = $url? $url: $title;
@@ -229,32 +231,31 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns an HTML FORM element. 
   *
-  * @param unknown_type $target
-  * @param unknown_type $type
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $target URL for the FORM's ACTION attribute.
+  * @param string $type FORM type (POST/GET).
+  * @param array $html_options
+  * @return string An formatted opening FORM tag.
   */
 	function formTag ($target=null, $type='post', $html_options=null) {
 		$html_options['action'] = $this->UrlFor($target);
 		$html_options['method'] = $type=='get'? 'get': 'post';
 		$type == 'file'? $html_options['enctype'] = 'multipart/form-data': null;
-
 		return sprintf(TAG_FORM, $this->parseHtmlOptions($html_options, ''));
 	}
 
 /**
-  * Creates a generic html tag (no content)
+  * Returns a generic HTML tag (no content). 
   * 
   * Examples:
   * * <i>tag("br") => <br /></i>
   * * <i>tag("input", array("type" => "text")) => <input type="text" /></i>
   *
-  * @param string $name name of element
-  * @param array $options html options
-  * @param bool $open is the tag open or closed (default closed "/>")
-  * @return string html tag
+  * @param string $name Name of HTML element
+  * @param array $options HTML options
+  * @param bool $open Is the tag open or closed? (defaults to closed "/>")
+  * @return string The formatted HTML tag
   */	
       function tag($name, $options=null, $open=false) {
 		$tag = "<$name ". $this->parseHtmlOptions($options);
@@ -263,28 +264,28 @@ class Controller extends Template {
       }
 
 /**
-  * Creates a generic html tag with content
+  * Returns a generic HTML tag with content.
   * 
   * Examples:
   * * <i>content_tag("p", "Hello world!") => <p>Hello world!</p></i>
   * * <i>content_tag("div", content_tag("p", "Hello world!"), array("class" => "strong")) => </i>
   *   <i><div class="strong"><p>Hello world!</p></div></i>
   *
-  * @param string $name name of element
-  * @param array $options html options
-  * @param bool $open is the tag open or closed (default closed "/>")
-  * @return string html tag
+  * @param string $name Name of HTML element
+  * @param array $options HTML options
+  * @param bool $open Is the tag open or closed? (defaults to closed "/>")
+  * @return string The formatted HTML tag
   */	
       function contentTag($name, $content, $options=null) {
 		return "<$name ". $this->parseHtmlOptions($options). ">$content</$name>";
       }
       
 /**
-  * Enter description here...
+  * Returns a formatted SUBMIT button for HTML FORMs.
   *
-  * @param unknown_type $caption
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $caption Text on SUBMIT button
+  * @param array $html_options HTML options
+  * @return string The formatted SUBMIT button
   */
 	function submitTag ($caption='Submit', $html_options=null) {
 		$html_options['value'] = $caption;
@@ -292,12 +293,12 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns a formatted INPUT tag for HTML FORMs.
   *
-  * @param unknown_type $tag_name
-  * @param unknown_type $size
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $tag_name Name attribute for INPUT element
+  * @param int $size Size attribute for INPUT element
+  * @param array $html_options
+  * @return string The formatted INPUT element
   */
 	function inputTag ($tag_name, $size=20, $html_options=null) {
 		$html_options['size'] = $size;
@@ -307,12 +308,12 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns an INPUT element with type="password".
   *
-  * @param unknown_type $tag_name
-  * @param unknown_type $size
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $tag_name
+  * @param int $size
+  * @param array $html_options
+  * @return string
   */
 	function passwordTag ($tag_name, $size=20, $html_options=null) {
 		$html_options['size'] = $size;
@@ -321,12 +322,12 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns an INPUT element with type="hidden".
   *
-  * @param unknown_type $tag_name
-  * @param unknown_type $value
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $tag_name
+  * @param string $value
+  * @param array $html_options
+  * @return string
   */
 	function hiddenTag ($tag_name, $value=null, $html_options=null) {
 		$html_options['value'] = $value? $value: $this->tagValue($tag_name);
@@ -334,24 +335,24 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns an INPUT element with type="file".
   *
-  * @param unknown_type $tag_name
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $tag_name
+  * @param array $html_options
+  * @return string
   */
 	function fileTag ($tag_name, $html_options=null) {
 		return sprintf(TAG_FILE, $tag_name, $this->parseHtmlOptions($html_options, '', ' '));
 	}
 
 /**
-  * Enter description here...
+  * Returns a TEXTAREA element.
   *
-  * @param unknown_type $tag_name
-  * @param unknown_type $cols
-  * @param unknown_type $rows
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $tag_name
+  * @param int $cols
+  * @param int $rows
+  * @param array $html_options
+  * @return string
   */
 	function areaTag ($tag_name, $cols=60, $rows=10, $html_options=null) {
 		$value = empty($html_options['value'])? $this->tagValue($tag_name): empty($html_options['value']);
@@ -361,12 +362,12 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns an INPUT element with type="checkbox". Checkedness is to be passed as string "checked" with the key "checked" in the $html_options array.
   *
-  * @param unknown_type $tag_name
-  * @param unknown_type $title
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $tag_name
+  * @param string $title
+  * @param array $html_options
+  * @return string
   */
 	function checkboxTag ($tag_name, $title=null, $html_options=null) {
 		$this->tagValue($tag_name)? $html_options['checked'] = 'checked': null;
@@ -375,13 +376,13 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns a set of radio buttons. 
   *
-  * @param unknown_type $tag_name
-  * @param unknown_type $options
-  * @param unknown_type $inbetween
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $tag_name
+  * @param array $options Array of options to select from
+  * @param string $inbetween String to separate options. See PHP's implode() function
+  * @param array $html_options
+  * @return string
   */
 	function radioTags ($tag_name, $options, $inbetween=null, $html_options=null) {
 		$value = isset($html_options['value'])? $html_options['value']: $this->tagValue($tag_name);
@@ -399,13 +400,13 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns a SELECT element, 
   *
-  * @param unknown_type $tag_name
-  * @param unknown_type $options
-  * @param unknown_type $outer_options
-  * @param unknown_type $inner_options
-  * @return unknown
+  * @param string $tag_name Name attribute of the SELECT
+  * @param array $options Array of the OPTION elements to be used in the SELECT element
+  * @param array $outer_options Array of HTML options for the opening SELECT element
+  * @param array $inner_options 
+  * @return string Formatted SELECT element
   */
 	function selectTag ($tag_name, $options, $outer_options=null, $inner_options=null) { 
 		if (!is_array($options) || !count($options))
@@ -425,12 +426,12 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns a formatted IMG element.
   *
-  * @param unknown_type $path
-  * @param unknown_type $alt
-  * @param unknown_type $html_options
-  * @return unknown
+  * @param string $path Path to the image file
+  * @param string $alt ALT attribute for the IMG tag
+  * @param array $html_options
+  * @return string Formatted IMG tag
   */
 	function imageTag ($path, $alt=null, $html_options=null) {
 		$url = "{$this->base}/images/{$path}";
@@ -439,12 +440,12 @@ class Controller extends Template {
 
 
 /**
-  * Returns a CSS link meta-tag
+  * Returns a LINK element for CSS stylesheets.
   *
-  * @param string $path
-  * @param string $rel
+  * @param string $path Path to CSS file
+  * @param string $rel Rel attribute. Defaults to "stylesheet".
   * @param array $html_options
-  * @return string
+  * @return string Formatted LINK element.
   */
 	function cssTag ($path, $rel='stylesheet', $html_options=null) {
 		$url = "{$this->base}/css/{$path}.css";
@@ -463,19 +464,19 @@ class Controller extends Template {
 	}
 
 /**
-  * Returns a javascript script tag
+  * Returns a JavaScript script tag.
   *
-  * @param string $script the javascript
-  * @return string
+  * @param string $script The JavaScript to be wrapped in SCRIPT tags.
+  * @return string The full SCRIPT element, with the JavaScript inside it.
   */
 	function javascriptTag ($script) {
 		return sprintf(TAG_JAVASCRIPT, $script);
 	}
 
 /**
-  * Returns a javascript include tag
+  * Returns a JavaScript include tag
   *
-  * @param string $url url to javascript file.
+  * @param string $url URL to JavaScript file.
   * @return string
   */
 	function javascriptIncludeTag ($url) {
@@ -483,12 +484,12 @@ class Controller extends Template {
 	}
 	
 /**
-  * Enter description here...
+  * Returns a row of formatted and named TABLE headers.
   *
-  * @param unknown_type $names
-  * @param unknown_type $tr_options
-  * @param unknown_type $th_options
-  * @return unknown
+  * @param array $names
+  * @param array $tr_options
+  * @param array $th_options
+  * @return string
   */
 	function tableHeaders ($names, $tr_options=null, $th_options=null) {
 		$args = func_get_args();
@@ -501,12 +502,12 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns a formatted string of table rows (TR's with TD's in them).
   *
-  * @param unknown_type $data
-  * @param unknown_type $tr_options
-  * @param unknown_type $td_options
-  * @return unknown
+  * @param array $data Array of table data
+  * @param array $tr_options HTML options for TR elements
+  * @param array $td_options HTML options for TD elements
+  * @return string
   */
 	function tableCells ($data, $odd_tr_options=null, $even_tr_options=null) {
 		if (empty($data[0]) || !is_array($data[0]))
@@ -527,7 +528,7 @@ class Controller extends Template {
 	}
 
 /**
-  * Generates a nested <UL> tree from an array
+  * Generates a nested <UL> (unordered list) tree from an array
   *
   * @param array $data
   * @param array $htmlOptions
@@ -551,19 +552,19 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns value of $tag_name. False is the tag does not exist.
   *
-  * @param unknown_type $tag_name
-  * @return unknown
+  * @param string $tag_name
+  * @return unknown Value of the named tag.
   */
 	function tagValue ($tag_name) {
 		return isset($this->params['data'][$tag_name])? $this->params['data'][$tag_name]: false;
 	}
 
 /**
-  * Enter description here...
+  * Returns number of errors in a submitted FORM.
   *
-  * @return unknown
+  * @return int Number of errors
   */
 	function validate () {
 		$args = func_get_args();
@@ -573,9 +574,9 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Validates a FORM according to the rules set up in the Model.
   *
-  * @return unknown
+  * @return int Number of errors
   */
 	function validateErrors () {
 		$objects = func_get_args();
@@ -590,11 +591,11 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns a formatted error message for given FORM field, NULL if no errors.
   *
-  * @param unknown_type $field
-  * @param unknown_type $text
-  * @return unknown
+  * @param string $field
+  * @param string $text
+  * @return string If there are errors this method returns an error message, else NULL. 
   */
 	function tagErrorMsg ($field, $text) {
 		if ($error = $this->tagIsInvalid($field)) {
@@ -606,7 +607,7 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Returns false if given FORM field has no errors. Otherwise it returns the constant set in the array Model->validationErrors.
   *
   * @param unknown_type $field
   * @return unknown
@@ -618,19 +619,19 @@ class Controller extends Template {
 
 
 /**
-  * Enter description here...
+  * Adds $name and $link to the breadcrumbs array.
   *
-  * @param unknown_type $name
-  * @param unknown_type $link
+  * @param string $name Text for link
+  * @param string $link URL for link
   */
 	function addCrumb ($name, $link) {
 		$this->_crumbs[] = array ($name, $link);
 	}
 
 /**
-  * Enter description here...
+  * Returns the breadcrumb trail as a sequence of &raquo;-separated links.
   *
-  * @return unknown
+  * @return string Formatted &raquo;-separated list of breadcrumb links. Returns NULL if $this->_crumbs is empty.
   */
 	function getCrumbs () {
 
@@ -648,16 +649,341 @@ class Controller extends Template {
 	}
 
 /**
-  * Enter description here...
+  * Displays an error page to the user. Uses layouts/error.html to render the page.
   *
-  * @param unknown_type $code
-  * @param unknown_type $name
-  * @param unknown_type $message
+  * @param int $code Error code (for instance: 404)
+  * @param string $name Name of the error (for instance: Not Found)
+  * @param string $message Error message
   */
 	function error ($code, $name, $message) {
 		header ("HTTP/1.0 {$code} {$name}");
 		print ($this->_render(VIEWS.'layouts/error.thtml', array('code'=>$code,'name'=>$name,'message'=>$message)));
 	}
+
+/**
+  * Returns link to javascript function
+  * 
+  * Returns a link that'll trigger a javascript function using the 
+  * onclick handler and return false after the fact.
+  * 
+  * Examples:
+  * <code>
+  *   linkToFunction("Greeting", "alert('Hello world!')");
+  *   linkToFunction(imageTag("delete"), "if confirm('Really?'){ do_delete(); }");
+  * </code>
+  *
+  * @param string $title title of link
+  * @param string $func javascript function to be called on click
+  * @param array $html_options html options for link
+  * @return string html code for link to javascript function
+  */
+	function linkToFunction ($title, $func, $html_options=null) {
+		$html_options['onClick'] = "$func; return false;";
+		return $this->linkTo($title, '#', $html_options);
+	}
+
+/**
+  * Returns link to remote action
+  * 
+  * Returns a link to a remote action defined by <i>options[url]</i> 
+  * (using the urlFor format) that's called in the background using 
+  * XMLHttpRequest. The result of that request can then be inserted into a
+  * DOM object whose id can be specified with <i>options[update]</i>. 
+  * Usually, the result would be a partial prepared by the controller with
+  * either renderPartial or renderPartialCollection. 
+  *
+  * Examples:
+  * <code>
+  *  linkToRemote("Delete this post", 
+  *  		array("update" => "posts", "url" => "delete/{$postid->id}"));
+  *  linkToRemote(imageTag("refresh"), 
+  *		array("update" => "emails", "url" => "list_emails" ));
+  * </code>
+  *
+  * By default, these remote requests are processed asynchronous during 
+  * which various callbacks can be triggered (for progress indicators and
+  * the likes).
+  *
+  * Example:
+  * <code>
+  *   linkToRemote (word,
+  *       array("url" => "undo", "n" => word_counter),
+  *       array("complete" => "undoRequestCompleted(request)"));
+  * </code> 
+  *
+  * The callbacks that may be specified are:
+  *
+  * - <i>loading</i>::       Called when the remote document is being 
+  *                           loaded with data by the browser.
+  * - <i>loaded</i>::        Called when the browser has finished loading
+  *                           the remote document.
+  * - <i>interactive</i>::   Called when the user can interact with the 
+  *                           remote document, even though it has not 
+  *                           finished loading.
+  * - <i>complete</i>::      Called when the XMLHttpRequest is complete.
+  *
+  * If you for some reason or another need synchronous processing (that'll
+  * block the browser while the request is happening), you can specify 
+  * <i>options[type] = synchronous</i>.
+  *
+  * You can customize further browser side call logic by passing
+  * in Javascript code snippets via some optional parameters. In
+  * their order of use these are:
+  *
+  * - <i>confirm</i>::      Adds confirmation dialog.
+  * -<i>condition</i>::    Perform remote request conditionally
+  *                          by this expression. Use this to
+  *                          describe browser-side conditions when
+  *                          request should not be initiated.
+  * - <i>before</i>::       Called before request is initiated.
+  * - <i>after</i>::        Called immediately after request was
+  *  		             initiated and before <i>loading</i>.
+  *
+  * @param string $title title of link
+  * @param array $options options for javascript function
+  * @param array $html_options options for link
+  * @return string html code for link to remote action
+  */
+  	function linkToRemote ($title, $options=null, $html_options=null) {
+		return $this->linkToFunction($title, $this->remoteFunction($options), $html_options);
+	}
+	
+/**
+  * Creates javascript function for remote AJAX call
+  * 
+  * This function creates the javascript needed to make a remote call 
+  * it is primarily used as a helper for linkToRemote.
+  * 
+  * @see linkToRemote() for docs on options parameter.
+  *
+  * @param array $options options for javascript 
+  * @return string html code for link to remote action
+  */
+     	function remoteFunction ($options=null) {
+		$javascript_options = $this->__optionsForAjax($options);
+		$func = isset($options['update'])? 
+			"new Ajax.Updater('{$options['update']}', " :
+			"new Ajax.Request(";
+		
+		$func .= "'" . $this->urlFor($options['url']) . "'";
+		$func .= ", $javascript_options)";
+		
+		if (isset($options['before']))
+			$func .= "{$options['before']}; $function";
+		if (isset($options['after']))
+			$func .= "$func; {$options['before']};";
+		if (isset($options['condition']))
+			$func .= "if ({$options['condition']}) { $func; }";
+		if (isset($options['confirm']))
+			$func .= "if (confirm('" . $this->escapeJavascript($options['confirm']) . "')) { $func; }";
+			
+		return $func;
+	}
+
+/**
+  * Escape carrier returns and single and double quotes for Javascript segments. 
+  * 
+  * @param string $javascript string that might have javascript elements
+  * @return string escaped string
+  */	
+      function escapeJavascript ($javascript) {
+		$javascript = str_replace(array("\r\n","\n","\r"),'\n', $javascript);
+		$javascript = str_replace(array('"', "'"), array('\"', "\\'"), $javascript);
+		return $javascript;
+      }
+      
+/**
+  * Periodically call remote url via AJAX. 
+  * 
+  * Periodically calls the specified url (<i>options[url]</i>) every <i>options[frequency]</i> seconds (default is 10).
+  * Usually used to update a specified div (<i>options[update]</i>) with the results of the remote call.
+  * The options for specifying the target with url and defining callbacks is the same as linkToRemote.
+  *
+  * @param array $options callback options
+  * @return string javascript code
+  */	
+      function periodicallyCallRemote ($options=null) {
+		$frequency = (isset($options['frequency']))? $options['frequency'] : 10;
+		$code = "new PeriodicalExecuter(function() {" . $this->remote_function($options) . "}, $frequency)";
+		return $this->javascriptTag($code);
+      }
+
+/**
+  * Returns form tag that will submit using Ajax.
+  * 
+  * Returns a form tag that will submit using XMLHttpRequest in the background instead of the regular 
+  * reloading POST arrangement. Even though it's using Javascript to serialize the form elements, the form submission 
+  * will work just like a regular submission as viewed by the receiving side (all elements available in params).
+  * The options for specifying the target with :url and defining callbacks is the same as link_to_remote.
+  *
+  * @param array $options callback options
+  * @return string javascript code
+  */	
+      function formRemoteTag ($options=null) {
+		$options['form'] = true;
+		$options['html']['onsubmit']=$this->remoteFunction($options) . "; return false;";
+		return $this->tag("form", $options['html'], true);
+      }
+     
+/**
+  * Returns a button input tag that will submit using Ajax
+  * 
+  * Returns a button input tag that will submit form using XMLHttpRequest in the background instead of regular
+  * reloading POST arrangement. <i>options</i> argument is the same as in <i>form_remote_tag</i>
+  *
+  * @param string $name input button name
+  * @param string $value input button value
+  * @param array $options callback options
+  * @return string ajaxed input button
+  */ 
+	function submitToRemote ($name, $value, $options = null) {
+		$options['with'] = 'Form.serialize(this.form)';
+		$options['html']['type'] = 'button';
+		$options['html']['onclick'] = $this->remoteFunction($options)."; return false;";
+		$options['html']['name'] = $name;
+		$options['html']['value'] = $value;
+		return $this->tag("input", $options['html'], false);
+	}
+	
+       
+/**
+  * Includes the Prototype Javascript library (and anything else) inside a single script tag
+  * 
+  * Note: The recommended approach is to copy the contents of
+  * lib/javascripts/ into your application's
+  * public/javascripts/ directory, and use @see javascriptIncludeTag() to 
+  * create remote script links.
+  * @return string script with all javascript in /javascripts folder
+  */ 
+	function defineJavascriptFunctions () {
+		$dir = VENDORS."/javascript";
+		$folder = new Folder($dir);
+		$files = $folder->find('.*\.js');
+
+		$javascript = '';
+		foreach($files as $file) {
+			if (substr($file, -3)=='.js') {
+				$javascript .= file_get_contents("$dir/$file") . "\n\n";
+			}
+		}
+		return $this->javascriptTag($javascript);
+	}
+      
+/**
+  * Observe field and call ajax on change.
+  * 
+  * Observes the field with the DOM ID specified by <i>field_id</i> and makes
+  * an Ajax when its contents have changed.
+  * 
+  * Required +options+ are:
+  * - <i>frequency</i>:: The frequency (in seconds) at which changes to
+  *                       this field will be detected.
+  * - <i>url</i>::       @see urlFor() -style options for the action to call
+  *                       when the field has changed.
+  * 
+  * Additional options are:
+  * - <i>update</i>::    Specifies the DOM ID of the element whose 
+  *                       innerHTML should be updated with the
+  *                       XMLHttpRequest response text.
+  * - <i>with</i>::      A Javascript expression specifying the
+  *                       parameters for the XMLHttpRequest. This defaults
+  *                       to Form.Element.serialize('$field_id'), which can be
+  *                       accessed from params['form']['field_id'].
+  *
+  * Additionally, you may specify any of the options documented in
+  * @see linkToRemote().
+  *
+  * @param string $field_id DOM ID of field to observe
+  * @param array $options ajax options
+  * @return string ajax script
+  */ 
+	function observeField ($field_id, $options = null) {
+		if (!isset($options['with']))
+			$options['with'] = "Form.Element.serialize('$field_id')";
+		return $this->__buildObserver('Form.Element.Observer', $field_id, $options);
+	}
+
+/**
+  * Observe entire form and call ajax on change.
+  * 
+  * Like @see observeField(), but operates on an entire form identified by the
+  * DOM ID <b>form_id</b>. <b>options</b> are the same as <b>observe_field</b>, except 
+  * the default value of the <i>with</i> option evaluates to the
+  * serialized (request string) value of the form.
+  *
+  * @param string $field_id DOM ID of field to observe
+  * @param array $options ajax options
+  * @return string ajax script
+  */ 
+  	function observeForm ($field_id, $options = null) {
+		//i think this is a rails bug... should be set
+		if (!isset($options['with']))
+			$options['with'] = 'Form.serialize(this.form)';
+			
+		return $this->__buildObserver('Form.Observer', $field_id, $options);
+	}
+
+
+/**
+  * Javascript helper function (private).
+  *
+  */
+	function __optionsForAjax ($options) {
+	     	$js_options = $this->__buildCallbacks($options);
+	        $js_options['asynchronous'] = 'true';
+	        if (isset($options['type'])) {
+	        	if ($options['type'] == 'synchronous')
+				$js_options['asynchronous'] = 'false';
+		}
+	        if (isset($options['method']))
+	        	$js_options['method'] = $this->__methodOptionToString($options['method']);
+		if (isset($options['position']))
+	        	$js_options['insertion'] = "Insertion." . Inflector::camelize($options['position']);
+		
+	        if (isset($options['form'])) {
+	          $js_options['parameters'] = 'Form.serialize(this)';
+	        } elseif (isset($options['with'])) {
+	          $js_options['parameters'] = $options['with'];
+	        }
+	        
+		$out = array();
+		foreach ($js_options as $k => $v) {
+			$out[] = "$k:$v";
+		}
+		$out = join(', ', $out);
+	        $out = '{' . $out . '}';
+	        return $out;
+	}
+
+     
+	function __methodOptionToString ($method) {
+		return (is_string($method) && !$method[0]=="'")? $method : "'$method'";
+	}
+      
+	function __buildObserver ($klass, $name, $options=null) {
+      		if(!isset($options['with']) && isset($options['update'])) {
+      			$options['with'] = 'value';
+      		}
+		$callback = $this->remoteFunction($options);
+		$javascript = "new $klass('$name', ";
+		$javascript .= "{$options['frequency']}, function(element, value) {";
+		$javascript .= "$callback})";
+		return $this->javascriptTag($javascript);
+	}
+            
+	function __buildCallbacks($options) {
+		$actions= array('uninitialized', 'loading', 'loaded', 'interactive', 'complete');
+        	$callbacks=array();
+        	foreach($actions as $callback) {
+        		if(isset($options[$callback])) {
+				$name = 'on' . ucfirst($callback);
+				$code = $options[$callback];
+				$callbacks[$name] = "function(request){".$code."}";
+			}
+        	}
+		return $callbacks;
+	}
+
 }
 
 ?>
\ No newline at end of file
diff --git a/libs/dbo.php b/libs/dbo.php
index 2a7a105ab..fd727204c 100644
--- a/libs/dbo.php
+++ b/libs/dbo.php
@@ -81,9 +81,9 @@ uses('object');
 class DBO extends Object {
 	
 /**
-  * Enter description here...
+  * Are we connected to the database?
   *
-  * @var unknown_type
+  * @var boolean
   * @access public
   */
 	var $connected=FALSE;
@@ -91,7 +91,7 @@ class DBO extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var boolean
   * @access public
   */
 	var $debug=FALSE;
@@ -99,7 +99,7 @@ class DBO extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var boolean
   * @access public
   */
 	var $fullDebug=FALSE;
@@ -113,7 +113,7 @@ class DBO extends Object {
 	var $error=NULL;
 
 /**
-  * Enter description here...
+  * String to hold how many rows were affected by the last SQL operation.
   *
   * @var unknown_type
   * @access public
@@ -121,15 +121,15 @@ class DBO extends Object {
 	var $affected=NULL;
 
 /**
-  * Enter description here...
+  * Number of rows in current resultset
   *
-  * @var unknown_type
+  * @var int
   * @access public
   */
 	var $numRows=NULL;
 
 /**
-  * Enter description here...
+  * Time the last query took
   *
   * @var unknown_type
   * @access public
@@ -153,7 +153,7 @@ class DBO extends Object {
     var $_result=NULL;
 
 /**
-  * Enter description here...
+  * Queries count.
   *
   * @var unknown_type
   * @access private
@@ -161,7 +161,7 @@ class DBO extends Object {
     var $_queriesCnt=0;
 
 /**
-  * Enter description here...
+  * Total duration of all queries.
   *
   * @var unknown_type
   * @access private
@@ -222,10 +222,9 @@ class DBO extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Constructor. Sets the level of debug for dbo (fullDebug or debug). 
   *
-  * @param unknown_type $config
-  * @param unknown_type $DEBUG
+  * @param array $config
   * @return unknown
   */
 	function __construct ($config=NULL) {
@@ -236,7 +235,7 @@ class DBO extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Destructor. Closes connection to the database.
   *
   */
 	function __destructor () {
@@ -244,17 +243,17 @@ class DBO extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns a string with a USE [databasename] SQL statement.
   *
-  * @param unknown_type $db_name
-  * @return unknown
+  * @param string $db_name Name of database to use
+  * @return unknown Result of the query
   */
 	function useDb ($db_name) {
 		return $this->query("USE {$db_name}");
 	}
 
 /**
-  * Enter description here...
+  * Disconnects database, kills the connection and says the connection is closed, and if DEBUG is turned on, the log for this object is shown.
   *
   */
 	function close () {
@@ -265,9 +264,9 @@ class DBO extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Executes given SQL statement.
   *
-  * @param unknown_type $sql
+  * @param string $sql SQL statement
   * @return unknown
   */
 	function rawQuery ($sql) {
@@ -276,9 +275,11 @@ class DBO extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Queries the database with given SQL statement, and obtains some metadata about the result 
+  * (rows affected, timing, any errors, number of rows in resultset). The query is also logged. 
+  * If DEBUG is set, the log is shown all the time, else it is only shown on errors.
   *
-  * @param unknown_type $sql
+  * @param string $sql
   * @return unknown
   */
 	function query($sql) {
@@ -296,30 +297,31 @@ class DBO extends Object {
 	}
 
 /**
-  * Returns a single row of results from the _last_ query
+  * Returns a single row of results from the _last_ SQL query.
   *
   * @param resource $res
-  * @return unknown
+  * @return array A single row of results
   */
 	function farr ($res=false) {
 		return $this->fetchRow($res? $res: $this->_result);
 	}
 
 /**
-  * Returns a single row of results for a _given_ query
+  * Returns a single row of results for a _given_ SQL query.
   *
-  * @param unknown_type $sql
-  * @return unknown
+  * @param string $sql SQL statement
+  * @return array A single row of results
   */
 	function one ($sql) {
 		return $this->query($sql)? $this->farr(): false;
 	}
 
 /**
-  * Returns all result rows for a given query
+  * Returns an array of all result rows for a given SQL query. 
+  * Returns false if no rows matched.
   *
-  * @param unknown_type $sql
-  * @return unknown
+  * @param string $sql SQL statement
+  * @return array Array of resultset rows, or false if no rows matched
   */
 	function all ($sql) {
 		if($this->query($sql)) {
@@ -333,10 +335,10 @@ class DBO extends Object {
 	}
 
 /**
-  * Returns a single field of the first of query results for a given sql query
+  * Returns a single field of the first of query results for a given SQL query, or false if empty.
   *
-  * @param unknown_type $name
-  * @param unknown_type $sql
+  * @param string $name Name of the field
+  * @param string $sql SQL query
   * @return unknown
   */
 	function field ($name, $sql) {
@@ -347,9 +349,9 @@ class DBO extends Object {
 /**
   * Checks if the specified table contains any record matching specified SQL
   *
-  * @param unknown_type $table
-  * @param unknown_type $sql
-  * @return unknown
+  * @param string $table Name of table to look in
+  * @param string $sql SQL WHERE clause (condition only, not the "WHERE" part)
+  * @return boolean True if the table has a matching record, else false
   */
 	function hasAny($table, $sql) {
 		$out = $this->one("SELECT COUNT(*) AS count FROM {$table}".($sql? " WHERE {$sql}":""));
@@ -359,16 +361,16 @@ class DBO extends Object {
 /**
   * Checks if it's connected to the database
   *
-  * @return unknown
+  * @return boolean True if the database is connected, else false
   */
 	function isConnected() {
 		return $this->connected;
 	}
 
 /**
-  * Prepares an array of data values by quoting them etc.
+  * Prepares an array of data values by quoting and escaping them.
   *
-  * @return unknown
+  * @return array Array of prepared data
   */
 	function prepareArray($data) {
 		$out = null;
@@ -379,9 +381,9 @@ class DBO extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Outputs the contents of the log.
   *
-  * @param unknown_type $sorted
+  * @param boolean $sorted
   */
 	function showLog($sorted=false) {
 		$log = $sorted?
@@ -399,9 +401,9 @@ class DBO extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Log given SQL query.
   *
-  * @param unknown_type $q
+  * @param string $sql SQL statement
   */
 	function logQuery($sql) {
 		$this->_queriesCnt++;
@@ -419,9 +421,10 @@ class DBO extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Output information about an SQL query. The SQL statement, number of rows in resultset, 
+  * and execution time in microseconds. If the query fails, and error is output instead.
   *
-  * @param unknown_type $q
+  * @param string $sql
   */
 	function showQuery($sql) {
 		$error = $this->error;
diff --git a/libs/dbo_adodb.php b/libs/dbo_adodb.php
index 1ec323564..468692676 100644
--- a/libs/dbo_adodb.php
+++ b/libs/dbo_adodb.php
@@ -31,7 +31,7 @@
   */
 
 /**
-  * Enter description here...
+  * Include AdoDB files.
   *
   */
 require_once(VENDORS.'adodb/adodb.inc.php');
@@ -48,9 +48,9 @@ require_once(VENDORS.'adodb/adodb.inc.php');
 class DBO_AdoDB extends DBO {
 
 /**
-  * Enter description here...
+  * Connects to the database using options in the given configuration array.
   *
-  * @param unknown_type $config
+  * @param array $config Configuration array for connecting
   */
 	function connect ($config) {
 		if($this->config = $config) {
@@ -67,7 +67,7 @@ class DBO_AdoDB extends DBO {
 	}
 	
 /**
-  * Enter description here...
+  * Disconnects from database.
   *
   * @return unknown
   */
@@ -76,9 +76,9 @@ class DBO_AdoDB extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Executes given SQL statement.
   *
-  * @param unknown_type $sql
+  * @param string $sql
   * @return unknown
   */
 	function execute ($sql) {
@@ -86,9 +86,9 @@ class DBO_AdoDB extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Return a row from given resultset.
   *
-  * @param unknown_type $res
+  * @param unknown_type $res Resultset
   * @return unknown
   */
 	function fetchRow ($res) {
@@ -96,7 +96,7 @@ class DBO_AdoDB extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Returns an array of tables in the database. If there are no tables, an error is raised and the application exits.
   *
   * @return unknown
   */
@@ -111,10 +111,10 @@ class DBO_AdoDB extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Returns an array of the fields in given table name.
   *
-  * @param unknown_type $table_name
-  * @return unknown
+  * @param string $table_name Name of database table to inspect
+  * @return array Fields in table. Keys are name and type
   */
 	function fields ($table_name) {
 		$data = $this->_adodb->MetaColumns($table_name);
@@ -127,14 +127,14 @@ class DBO_AdoDB extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * To be implemented
   *
   * @param unknown_type $data
   */
 	function prepare ($data)		{ die('Please implement DBO::prepare() first.'); }
 
 /**
-  * Enter description here...
+  * Returns last SQL error message.
   *
   * @return unknown
   */
@@ -143,25 +143,25 @@ class DBO_AdoDB extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Returns number of affected rows
   *
-  * @return unknown
+  * @return int
   */
 	function lastAffected ()		{
 		return $this->_adodb->Affected_Rows(); 
 	}
 
 /**
-  * Enter description here...
+  * Returns number of rows in resultset of the last database operation.
   *
-  * @return unknown
+  * @return int Number of rows in resultset
   */
 	function lastNumRows () {
 		 return $this->_result? $this->_result->RecordCount(): false;
 	}
 
 /**
-  * Enter description here...
+  * To be implemented
   *
   */
 	function lastInsertId ()		{ die('Please implement DBO::lastInsertId() first.'); }
diff --git a/libs/dbo_mysql.php b/libs/dbo_mysql.php
index d6948adaa..d945983c2 100644
--- a/libs/dbo_mysql.php
+++ b/libs/dbo_mysql.php
@@ -54,10 +54,10 @@ uses('dbo');
 class DBO_MySQL extends DBO {
 	
 /**
-  * Enter description here...
+  * Connects to the database using options in the given configuration array.
   *
-  * @param unknown_type $config
-  * @return unknown
+  * @param array $config Configuration array for connecting
+  * @return boolean True if the database could be connected, else false
   */
 	function connect ($config) {
 		if($config) {
@@ -73,38 +73,38 @@ class DBO_MySQL extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Disconnects from database.
   *
-  * @return unknown
+  * @return boolean True if the database could be disconnected, else false
   */
 	function disconnect () {
 		return mysql_close();
 	}
 
 /**
-  * Enter description here...
+  * Executes given SQL statement.
   *
-  * @param unknown_type $sql
-  * @return unknown
+  * @param string $sql SQL statement
+  * @return resource MySQL result resource identifier
   */
 	function execute ($sql) {
 		return mysql_query($sql);
 	}
 
 /**
-  * Enter description here...
+  * Returns a row from given resultset as an array .
   *
-  * @param unknown_type $res
-  * @return unknown
+  * @param unknown_type $res Resultset
+  * @return array The fetched row as an array
   */
 	function fetchRow ($res) {
 		return mysql_fetch_array($res);
 	}
 
 /**
-  * Enter description here...
+  * Returns an array of tables in the database. If there are no tables, an error is raised and the application exits.
   *
-  * @return unknown
+  * @return array Array of tablenames in the database
   */
 	function tables () {
 		$result = mysql_list_tables($this->config['database']);
@@ -123,10 +123,10 @@ class DBO_MySQL extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Returns an array of the fields in given table name.
   *
-  * @param unknown_type $table_name
-  * @return unknown
+  * @param string $table_name Name of database table to inspect
+  * @return array Fields in table. Keys are name and type
   */
 	function fields ($table_name) {
 		$data = $this->all("DESC {$table_name}");
@@ -139,49 +139,49 @@ class DBO_MySQL extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Returns a quoted and escaped string of $data for use in an SQL statement.
   *
-  * @param unknown_type $data
-  * @return unknown
+  * @param string $data String to be prepared for use in an SQL statement
+  * @return string Quoted and escaped
   */
 	function prepare ($data) {
 		return "'".mysql_real_escape_string($data)."'";
 	}
 
 /**
-  * Enter description here...
+  * Returns a formatted error message from previous database operation.
   *
-  * @return unknown
+  * @return string Error message with error number
   */
 	function lastError () {
 		return mysql_errno()? mysql_errno().': '.mysql_error(): null;
 	}
 
 /**
-  * Enter description here...
+  * Returns number of affected rows in previous database operation. If no previous operation exists, this returns false.
   *
-  * @return unknown
+  * @return int Number of affected rows
   */
 	function lastAffected () {
 		return $this->_result? mysql_affected_rows(): false;
 	}
 
 /**
-  * Enter description here...
+  * Returns number of rows in previous resultset. If no previous resultset exists, this returns false.
   *
-  * @return unknown
+  * @return int Number of rows
   */
 	function lastNumRows () {
 		return $this->_result? @mysql_num_rows($this->_result): false;
 	}
 
 /**
-  * Enter description here...
+  * Returns the ID generated from the previous INSERT operation.
   *
-  * @return unknown
+  * @return int 
   */
 	function lastInsertId() {
-		Return mysql_insert_id();
+		return mysql_insert_id();
 	}
 
 }
diff --git a/libs/dbo_postgres.php b/libs/dbo_postgres.php
index 6e86bf56b..dadc5ac20 100644
--- a/libs/dbo_postgres.php
+++ b/libs/dbo_postgres.php
@@ -46,9 +46,9 @@ uses('object', 'dbo');
 class DBO_Postgres extends DBO {
 	
 /**
-  * Enter description here...
+  * Connects to the database using options in the given configuration array.
   *
-  * @param unknown_type $config
+  * @param array $config Configuration array for connecting
   * @return unknown
   */
 	function connect ($config) {
@@ -66,7 +66,7 @@ class DBO_Postgres extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Disconnects from database.
   *
   * @return unknown
   */
@@ -75,9 +75,9 @@ class DBO_Postgres extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Executes given SQL statement.
   *
-  * @param unknown_type $sql
+  * @param string $sql
   * @return unknown
   */
 	function execute ($sql) {
@@ -85,7 +85,7 @@ class DBO_Postgres extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Returns a row from given resultset.
   *
   * @param unknown_type $res
   * @return unknown
@@ -95,9 +95,9 @@ class DBO_Postgres extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Returns an array of tables in the database. If there are no tables, an error is raised and the application exits.
   *
-  * @return unknown
+  * @return array Array of tablenames in the database
   */
 	function tables () {
 		$sql = "SELECT a.relname AS name
@@ -120,10 +120,10 @@ class DBO_Postgres extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Returns an array of the fields in given table name.
   *
-  * @param unknown_type $table_name
-  * @return unknown
+  * @param string $table_name Name of database table to inspect
+  * @return array Fields in table. Keys are name and type
   */
 	function fields ($table_name) {
 		$sql = "SELECT c.relname, a.attname, t.typname FROM pg_class c, pg_attribute a, pg_type t WHERE c.relname = '{$table_name}' AND a.attnum > 0 AND a.attrelid = c.oid AND a.atttypid = t.oid";
@@ -139,47 +139,47 @@ class DBO_Postgres extends DBO {
 	}
 
 /**
-  * Enter description here...
+  * Returns a quoted and escaped string of $data for use in an SQL statement.
   *
-  * @param unknown_type $data
-  * @return unknown
+  * @param string $data String to be prepared for use in an SQL statement
+  * @return string Quoted and escaped
   */
 	function prepare ($data) {
 		return "'".pg_escape_string($data)."'";
 	}
 
 /**
-  * Enter description here...
+  * Returns a formatted error message from previous database operation.
   *
-  * @return unknown
+  * @return string Error message
   */
 	function lastError () {
 		return pg_last_error()? pg_last_error(): null;
 	}
 
 /**
-  * Enter description here...
+  * Returns number of affected rows in previous database operation. If no previous operation exists, this returns false.
   *
-  * @return unknown
+  * @return int Number of affected rows
   */
 	function lastAffected () {
 		return $this->_result? pg_affected_rows($this->_result): false;
 	}
 
 /**
-  * Enter description here...
+  * Returns number of rows in previous resultset. If no previous resultset exists, this returns false.
   *
-  * @return unknown
+  * @return int
   */
 	function lastNumRows () {
 		return $this->_result? pg_num_rows($this->_result): false;
 	}
 
 /**
-  * Enter description here...
+  * Returns the ID generated from the previous INSERT operation.
   *
-  * @param unknown_type $table
-  * @param unknown_type $field
+  * @param string $table Name of the database table
+  * @param string $field Name of the ID database field. Defaults to "id"
   * @return unknown
   */
 	function lastInsertId ($table, $field='id') {
diff --git a/libs/dispatcher.php b/libs/dispatcher.php
index aedf8668d..28bb8b5d3 100644
--- a/libs/dispatcher.php
+++ b/libs/dispatcher.php
@@ -32,7 +32,7 @@
 
 /**
  * Description:
- * Dispatches the request, creating aproppriate models and controllers.
+ * Dispatches the request, creating appropriate models and controllers.
  */
 
 uses('error_messages', 'object', 'router', 'controller');
@@ -48,7 +48,7 @@ uses('error_messages', 'object', 'router', 'controller');
   */
 class Dispatcher extends Object {
 /**
-  * Enter description here...
+  * Base URL
   *
   * @var unknown_type
   */
@@ -56,12 +56,12 @@ class Dispatcher extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var array
   */
 	var $passed_args = array();
 
 /**
-  * Enter description here...
+  * Constructor.
   *
   */
 	function __construct () {
@@ -72,7 +72,7 @@ class Dispatcher extends Object {
 /**
   * Enter description here...
   *
-  * @param unknown_type $url
+  * @param string $url
   * @return unknown
   */
 	function dispatch ($url) {
@@ -122,10 +122,10 @@ class Dispatcher extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns array of GET and POST parameters. GET parameters are taken from given URL.
   *
-  * @param unknown_type $from_url
-  * @return unknown
+  * @param string $from_url
+  * @return array Parameters found in POST and GET.
   */
 	function parseParams ($from_url) {
 		global $_POST, $_FILES;
@@ -147,9 +147,9 @@ class Dispatcher extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns a base URL.
   *
-  * @return unknown
+  * @return string
   */
 	function baseUrl () {
 		global $_SERVER;
@@ -170,11 +170,11 @@ class Dispatcher extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Displays an error page (e.g. 404 Not found).
   *
-  * @param unknown_type $code
-  * @param unknown_type $name
-  * @param unknown_type $message
+  * @param int $code Error code (e.g. 404)
+  * @param string $name Name of the error message (e.g. Not found)
+  * @param string $message
   */
 	function error ($code, $name, $message) {
 		$controller = new Controller ($this);
@@ -183,7 +183,7 @@ class Dispatcher extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Convenience method to display a 404 page.
   *
   * @param unknown_type $url
   * @param unknown_type $message
@@ -193,9 +193,9 @@ class Dispatcher extends Object {
 	}
 
 /**
-  * Enter description here...
+  * If DEBUG is set, this displays a 404 error with the message that no controller is set. If DEBUG is not set, nothing happens.
   *
-  * @param unknown_type $url
+  * @param string $url
   */
 	function errorNoController ($url) {
 		DEBUG?
@@ -205,10 +205,10 @@ class Dispatcher extends Object {
 	}
 
 /**
-  * Enter description here...
+  * If DEBUG is set, this displays a 404 error with the message that the asked-for controller does not exist. If DEBUG is not set, nothing happens.
   *
-  * @param unknown_type $url
-  * @param unknown_type $controller_class
+  * @param string $url
+  * @param string $controller_class
   */
 	function errorUnknownController ($url, $controller_class) {
 		DEBUG? 
@@ -218,9 +218,9 @@ class Dispatcher extends Object {
 	}
 
 /**
-  * Enter description here...
+  * If DEBUG is set, this displays a 404 error with the message that no action is set. If DEBUG is not set, nothing happens.
   *
-  * @param unknown_type $url
+  * @param string $url
   */
 	function errorNoAction ($url) {
 		DEBUG? 
@@ -230,11 +230,11 @@ class Dispatcher extends Object {
 	}
 
 /**
-  * Enter description here...
+  * If DEBUG is set, this displays a 404 error with the message that no such action exists. If DEBUG is not set, nothing happens.
   *
-  * @param unknown_type $url
-  * @param unknown_type $controller_class
-  * @param unknown_type $action
+  * @param string $url
+  * @param string $controller_class
+  * @param string $action
   */
 	function errorUnknownAction ($url,$controller_class, $action) {
 		DEBUG? 
diff --git a/libs/flay.php b/libs/flay.php
index 5bca13fd2..c1097f774 100644
--- a/libs/flay.php
+++ b/libs/flay.php
@@ -51,19 +51,19 @@ class Flay extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var string
   */
 	var $text = null;
 
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var boolean
   */
 	var $allow_html = false;
 
 /**
-  * Enter description here...
+  * Constructor.
   *
   * @param unknown_type $text
   */
@@ -73,10 +73,12 @@ class Flay extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns $text translated to HTML using the Flay syntax. 
   *
-  * @param unknown_type $text
-  * @return unknown
+  * @param string $text Text to format
+  * @param boolean $bare 
+  * @param boolean $allowHtml Set this to trim whitespace and disable all HTML
+  * @return string Formatted text
   */
 	function toHtml ($text=null, $bare=false, $allowHtml=false) {
 
diff --git a/libs/folder.php b/libs/folder.php
index 12c3ea84d..abb51d1a3 100644
--- a/libs/folder.php
+++ b/libs/folder.php
@@ -50,21 +50,21 @@ class Folder extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var string
   */
 	var $path = null;
 
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var boolean
   */
 	var $sort = false;
 
 /**
-  * Enter description here...
+  * Constructor.
   *
-  * @param unknown_type $path
+  * @param string $path
   */
 	function __construct ($path=false) {
 		if (empty($path)) $path = getcwd();
@@ -72,19 +72,19 @@ class Folder extends Object {
    }	
 
 /**
-  * Enter description here...
+  * Return current path.
   *
-  * @return unknown
+  * @return string Current path
   */
 	function pwd () {
 		return $this->path;
 	}
 
 /**
-  * Enter description here...
+  * Change directory to $desired_path.
   *
-  * @param unknown_type $desired_path
-  * @return unknown
+  * @param string $desired_path Path to the directory to change to
+  * @return string The new path. Returns false on failure
   */
 	function cd ($desired_path) {
 		$desired_path = realpath($desired_path);
@@ -97,10 +97,11 @@ class Folder extends Object {
 
 
 /**
-  * Enter description here...
+  * Returns an array of the contents of the current directory, or false on failure. 
+  * The returned array holds two arrays: one of dirs and one of files.
   *
-  * @param unknown_type $sort
-  * @return unknown
+  * @param boolean $sort
+  * @return array
   */
 	function ls($sort=true) {
 		if ($dir = opendir($this->path)) {
@@ -128,10 +129,10 @@ class Folder extends Object {
 
 
 /**
-  * Finds all matching files in a directory
+  * Returns an array of all matching files in current directory
   *
-  * @param string $pattern
-  * @return unknown
+  * @param string $pattern Preg_match pattern (Defaults to: .*)
+  * @return array
   */
 	function find ($regexp_pattern='.*') {
 		list($dirs, $files) = $this->ls();
@@ -148,10 +149,10 @@ class Folder extends Object {
 
 
 /**
-  * Enter description here...
+  * Returns an array of all matching files in and below current directory
   *
-  * @param unknown_type $pattern
-  * @return unknown
+  * @param string $pattern Preg_match pattern (Defaults to: .*)
+  * @return array Files matching $pattern
   */
 	function findRecursive ($pattern='.*') {
 		$starts_on = $this->path;
@@ -161,10 +162,10 @@ class Folder extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Private helper function for findRecursive.
   *
-  * @param unknown_type $pattern
-  * @return unknown
+  * @param string $pattern
+  * @return array Files matching pattern
   */
 	function _findRecursive ($pattern) {
 		list($dirs, $files) = $this->ls();
@@ -186,61 +187,61 @@ class Folder extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns true if given $path is a Windows path.
   *
-  * @param unknown_type $path
-  * @return unknown
+  * @param string $path Path to check
+  * @return boolean 
   */
 	function isWindowsPath ($path) {
 		return preg_match('#^[A-Z]:\\\#i', $path)? true: false;
 	}
 
 /**
-  * Enter description here...
+  * Returns true if given $path is an absolute path.
   *
-  * @param unknown_type $path
-  * @return unknown
+  * @param string $path Path to check
+  * @return boolean 
   */
 	function isAbsolute ($path) {
 		return preg_match('#^\/#', $path) || preg_match('#^[A-Z]:\\\#i', $path);
 	}
 
 /**
-  * Enter description here...
+  * Returns true if given $path ends in a slash (i.e. is slash-terminated).
   *
-  * @param unknown_type $path
-  * @return unknown
+  * @param string $path Path to check
+  * @return boolean
   */
 	function isSlashTerm ($path) {
 		return preg_match('#[\\\/]$#', $path)? true: false;
 	}
 
 /**
-  * Enter description here...
+  * Returns a correct set of slashes for given $path. (\\ for Windows paths and / for other paths.)
   *
-  * @param unknown_type $path
-  * @return unknown
+  * @param string $path Path to check
+  * @return string Set of slashes ("\\" or "/")
   */
 	function correctSlashFor ($path) {
 		return Folder::isWindowsPath($path)? '\\': '/';
 	}
 
 /**
-  * Enter description here...
+  * Returns $path with added terminating slash (corrected for Windows or other OS).
   *
-  * @param unknown_type $path
-  * @return unknown
+  * @param string $path Path to check
+  * @return string
   */
 	function slashTerm ($path) {
 		return $path . (Folder::isSlashTerm($path)? null: Folder::correctSlashFor($path));
 	}
 
 /**
-  * Enter description here...
+  * Returns $path with $element added, with correct slash in-between.
   *
-  * @param unknown_type $path
-  * @param unknown_type $element
-  * @return unknown
+  * @param string $path
+  * @param string $element
+  * @return string
   */
 	function addPathElement ($path, $element) {
 		return Folder::slashTerm($path).$element;
diff --git a/libs/inflector.php b/libs/inflector.php
index 4aca8a5db..2bad838ea 100644
--- a/libs/inflector.php
+++ b/libs/inflector.php
@@ -47,7 +47,7 @@ uses('object');
 class Inflector extends Object {
 	
 /**
-  * Enter description here...
+  * Constructor.
   *
   */
 	function __construct () {
@@ -55,10 +55,10 @@ class Inflector extends Object {
 	}
 	
 /**
-  * Enter description here...
+  * Return $word in plural form.
   *
-  * @param unknown_type $word
-  * @return unknown
+  * @param string $word Word in singular
+  * @return string Word in plural
   */
 	function pluralize ($word) {
 		$plural_rules = array(
@@ -86,10 +86,10 @@ class Inflector extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Return $word in singular form.
   *
-  * @param unknown_type $word
-  * @return unknown
+  * @param string $word Word in plural
+  * @return string Word in singular
   */
 	function singularize ($word) {
 		$singular_rules = array(
@@ -119,20 +119,20 @@ class Inflector extends Object {
 	}
 	
 /**
-  * Enter description here...
+  * Returns given $lower_case_and_underscored_word as a camelCased word.
   *
-  * @param unknown_type $lower_case_and_underscored_word
-  * @return unknown
+  * @param string $lower_case_and_underscored_word Word to camelize
+  * @return string Camelized word. likeThis.
   */
 	function camelize($lower_case_and_underscored_word) {
 		return str_replace(" ","",ucwords(str_replace("_"," ",$lower_case_and_underscored_word)));
 	}    
 
 /**
-  * Enter description here...
+  * Returns an underscore-syntaxed ($like_this_dear_reader) version of the $camel_cased_word.
   *
-  * @param unknown_type $camel_cased_word
-  * @return unknown
+  * @param string $camel_cased_word Camel-cased word to be "underscorized"
+  * @return string Underscore-syntaxed version of the $camel_cased_word
   */
 	function underscore($camel_cased_word) {
 		$camel_cased_word = preg_replace('/([A-Z]+)([A-Z])/','\1_\2',$camel_cased_word);
@@ -140,40 +140,42 @@ class Inflector extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns a human-readable string from $lower_case_and_underscored_word,
+  * by replacing underscores with a space, and by upper-casing the initial characters.
   *
-  * @param unknown_type $lower_case_and_underscored_word
-  * @return unknown
+  * @param string $lower_case_and_underscored_word String to be made more readable
+  * @return string Human-readable string
   */
 	function humanize($lower_case_and_underscored_word) {
 		return ucwords(str_replace("_"," ",$lower_case_and_underscored_word));
 	}    
 
 /**
-  * Enter description here...
+  * Returns corresponding table name for given $class_name.
   *
-  * @param unknown_type $class_name
-  * @return unknown
+  * @param string $class_name Name of class to get database table name for
+  * @return string Name of the database table for given class
   */
 	function tableize($class_name) {
 		return Inflector::pluralize(Inflector::underscore($class_name));
 	}
 
 /**
-  * Enter description here...
+  * Returns Cake class name ("Post" for the database table "posts".) for given database table.
   *
-  * @param unknown_type $table_name
-  * @return unknown
+  * @param string $table_name Name of database table to get class name for
+  * @return string
   */
 	function classify($table_name) {
 		return $this->camelize($this->singularize($table_name));
 	}
 
 /**
-  * Enter description here...
+  * Returns $class_name in underscored form, with "_id" tacked on at the end. 
+  * This is for use in dealing with the database.
   *
-  * @param unknown_type $class_name
-  * @return unknown
+  * @param string $class_name
+  * @return string
   */
 	function foreignKey($class_name) {
 		return $this->underscore($class_name) . "_id";
diff --git a/libs/model.php b/libs/model.php
index f167d5fa1..9a7010265 100644
--- a/libs/model.php
+++ b/libs/model.php
@@ -15,8 +15,8 @@
 
 /**
   * Purpose: Model
-  * DBO-backed object data model, loosly based on RoR (www.rubyonrails.com).
-  * Automatically selects db table name based on pluralized lowercase object class name
+  * 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
@@ -63,9 +63,9 @@ class Model extends Object {
 	var $parent = false;
 
 /**
-  * Enter description here...
+  * Custom database table name
   *
-  * @var unknown_type
+  * @var string
   * @access public
   */
 	var $use_table = false;
@@ -81,13 +81,13 @@ class Model extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var array
   * @access public
   */
 	var $data = array();
 
 /**
-  * Enter description here...
+  * Table name for this Model.
   *
   * @var unknown_type
   * @access public
@@ -95,9 +95,9 @@ class Model extends Object {
 	var $table = false;
 	// private
 /**
-  * Enter description here...
+  * Table metadata
   *
-  * @var unknown_type
+  * @var array
   * @access private
   */
 	var $_table_info = null;
@@ -105,7 +105,7 @@ class Model extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var array
   * @access private
   */
 	var $_oneToMany = array();
@@ -113,15 +113,15 @@ class Model extends Object {
 /**
   * Enter description here...
   *
-  * @var unknown_type
+  * @var array
   * @access private
   */
 	var $_oneToOne = array();
 
 /**
-  * Enter description here...
+  * Array of other Models this Model references in a hasMany relationship. 
   *
-  * @var unknown_type
+  * @var array
   * @access private
   */
 	var $_hasMany = array();
@@ -182,7 +182,9 @@ class Model extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Updates the many-to-one links, by emptying the links list, and linkManyToOne again.
+  *
+  * @see linkManyToOne()
   *
   */
 	function relink () {
@@ -194,10 +196,12 @@ class Model extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Creates a many-to-one link for given $model_name. 
+  * First it gets Inflector to derive a table name and a foreign key field name.
+  * Then, these are stored in the Model.
   *
-  * @param unknown_type $model_name
-  * @param unknown_type $value
+  * @param string $model_name Name of model to link to
+  * @param unknown_type $value Defaults to NULL.
   */
 	function linkManyToOne ($model_name, $value=null) {
 		$table_name = Inflector::tableize($model_name);
@@ -206,7 +210,7 @@ class Model extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Removes all one-to-many links to other Models.
   *
   */
 	function clearLinks () {
@@ -231,10 +235,15 @@ class Model extends Object {
 
 
 /**
-  * Enter description here...
+  * This function does two things: 1) it scans the array $one for they key 'id',
+  * and if that's found, it sets the current id to the value of $one[id].
+  * For all other keys than 'id' the keys and values of $one are copied to the 'data' property of this object.
+  * 2) Returns an array with all of $one's keys and values.
+  * (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 unknown_type $one
-  * @param unknown_type $two
+  * @param mixed $one Array or string.
+  * @param string $two Optional string
   * @return unknown
   */
 	function set ($one, $two=null) {
@@ -256,9 +265,9 @@ class Model extends Object {
     }
 
 /**
-  * Enter description here...
+  * Sets current id to given $id.
   *
-  * @param unknown_type $id
+  * @param int $id Id
   */
 	function setId ($id) {
 		$this->id = $id;
@@ -266,7 +275,7 @@ class Model extends Object {
 	}
 
 /**
-  * Reads table info (column names and types) from the db
+  * Returns an array of table metadata (column names and types) from the database.
   *
   * @return array
   */
@@ -277,9 +286,10 @@ class Model extends Object {
 	}
 
 /**
-  * Enter description here...
+  * 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. 
   *
-  * @param unknown_type $name
+  * @param string $name Name of table to look in
   * @return unknown
   */
 	function hasField ($name) {
@@ -288,7 +298,7 @@ class Model extends Object {
 	}
 
 /**
-  * reads a list of fields from the db
+  * Returns a list of fields from the database
   *
   * @param string $fields
   * @param array $fields
@@ -300,9 +310,10 @@ class Model extends Object {
 	}
 
 /**
-  * reads a field from a record
+  * Returns contents of a field in a query matching given conditions.
   *
-  * @param string $name
+  * @param string $name Name of field to get
+  * @param string $conditions SQL conditions (defaults to NULL)
   * @return field contents
   */
 	function field ($name, $conditions=null) {
@@ -323,10 +334,10 @@ class Model extends Object {
 	}
 
 /**
-  * saves a single field to the db
+  * Saves a single field to the database.
   *
-  * @param string $name
-  * @param mixed $value
+  * @param string $name Name of the table field
+  * @param mixed $value Value of the field
   * @return success
   */
 	function saveField($name, $value) {
@@ -334,9 +345,10 @@ class Model extends Object {
 	}
 
 /**
-  * saves model data to the db
+  * Saves model data to the database.
   *
   * @param array $data
+  * @param boolean $validate
   * @return success
   */
 	function save ($data=null, $validate=true) {
@@ -396,20 +408,21 @@ class Model extends Object {
 	}
 
 /**
-  * deletes a record
+  * Synonym for del().
   *
   * @param mixed $id
-  * @return success
+  * @see function del
+  * @return boolean True on success
   */
 	function remove ($id=null) {
 		return $this->del($id);
 	}
 
 /**
-  * Enter description here...
+  * Removes record for given id. If no id is given, the current id is used. Returns true on success.
   *
-  * @param unknown_type $id
-  * @return unknown
+  * @param mixed $id Id of database record to delete
+  * @return boolean True on success
   */
 	function del ($id=null) {
 		if ($id) $this->id = $id;
@@ -422,9 +435,9 @@ class Model extends Object {
 	}
 
 /**
-  * checks for existance of a record with set id
+  * Returns true if a record with set id exists.
   *
-  * @return true if such record exists
+  * @return boolean True if such a record exists
   */
 	function exists () {
 		return $this->id? $this->db->hasAny($this->table, "id = '{$this->id}'"): false;
@@ -432,38 +445,61 @@ class Model extends Object {
 
 
 /**
-  * checks for existance of a record with specified conditions
+  * Returns true if a record that meets given conditions exists
   *
-  * @return true if such record exists
+  * @return boolean True if such a record exists
   */
-	function hasAny ($sql_conditions=null) {
+	function hasAny ($sql_conditions = null) {
 		return $this->db->hasAny($this->table, $sql_conditions);
 	}
 
 
 /**
-  * reads a single row 
+  * Return a single row as a resultset array.
   *
-  * @param string $conditions
-  * @param string $fields
-  * @return array of fields
+  * @param string $conditions SQL conditions
+  * @param mixed $fields Either a single string of a field name, or an array of field names
+  * @return array Array of records
   */
 	function find ($conditions = null, $fields = null) {
 		$data = $this->findAll($conditions, $fields, null, 1);
 		return empty($data[0])? false: $data[0];
 	}
 
-/**
-  * returns specified fields from db records matching conditions
+/** parses conditions array (or just passes it if it's a string)
+  * @return string
   *
-  * @param string $conditions
-  * @param string $fields
-  * @param string $order
-  * @param int $limit
-  * @param int $page
-  * @return array of records
+  */
+	function parseConditions ($conditions) {
+		if (is_string($conditions)) {
+			return $conditions;
+		}
+		elseif (is_array($conditions)) {
+			$out = array();
+			foreach ($conditions as $key=>$value) {
+				$out[] = "{$key}=".($value===null? 'null': $this->db->prepare($value));
+			}
+			return join(' and ', $out);
+		}
+		else {
+			return null;
+		}
+	}
+
+/**
+  * Returns a resultset array with specified fields from database matching given conditions.
+  *
+  * @param mixed $conditions SQL conditions as a string or as an array('field'=>'value',...)
+  * @param mixed $fields Either a single string of a field name, or an array of field names
+  * @param string $order SQL ORDER BY conditions (e.g. "DESC" or "ASC")
+  * @param int $limit SQL LIMIT clause, for calculating items per page
+  * @param int $page Page number
+  * @return array Array of records
   */
 	function findAll ($conditions = null, $fields = null, $order = null, $limit=50, $page=1) {
+		
+		$conditions = $this->parseConditions($conditions);
+
 		if (is_array($fields))
 			$f = $fields;
 		elseif ($fields)
@@ -501,21 +537,20 @@ class Model extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns an array of all rows for given SQL statement.
   *
-  * @param unknown_type $sql
-  * @param unknown_type $debug
-  * @return unknown
+  * @param string $sql SQL query
+  * @return array
   */
-	function findBySql ($sql, $debug=0) {
-		return $this->db->all($sql, $debug);
+	function findBySql ($sql) {
+		return $this->db->all($sql);
 	}
 
 /**
-  * Enter description here...
+  * Returns number of rows matching given SQL condition. 
   *
-  * @param unknown_type $conditions
-  * @return unknown
+  * @param string $conditions SQL conditions (WHERE clause conditions)
+  * @return int Number of matching rows
   */
 	function findCount ($conditions) {
 		list($data) = $this->findAll($conditions, 'COUNT(id) AS count');
@@ -525,7 +560,7 @@ class Model extends Object {
 /**
   * Enter description here...
   *
-  * @param unknown_type $conditions
+  * @param string $conditions SQL conditions (WHERE clause conditions)
   * @param unknown_type $fields
   * @return unknown
   */
@@ -536,9 +571,9 @@ class Model extends Object {
 /**
   * Enter description here...
   *
-  * @param unknown_type $data
-  * @param unknown_type $root
-  * @return unknown
+  * @param unknown_type $data 
+  * @param unknown_type $root NULL or id for root node of operation
+  * @return array
   */
 	function _doThread ($data, $root) {
 		$out = array();
@@ -555,12 +590,13 @@ class Model extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns an array with keys "prev" and "next" that holds the id's of neighbouring data,
+  * which is useful when creating paged lists.
   *
-  * @param unknown_type $conditions
+  * @param string $conditions SQL conditions for matching rows
   * @param unknown_type $field
   * @param unknown_type $value
-  * @return unknown
+  * @return array Array with keys "prev" and "next" that holds the id's
   */
 	function findNeighbours ($conditions, $field, $value) {
 		list($prev) = $this->findAll($conditions." AND {$field} < '{$value}'", $field, "{$field} DESC", 1);
@@ -570,20 +606,20 @@ class Model extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns a resultset for given SQL statement.
   *
-  * @param unknown_type $sql
-  * @return unknown
+  * @param string $sql SQL statement
+  * @return array Resultset
   */
 	function query ($sql) {
 		return $this->db->query($sql);
 	}
 
 /**
-  * Enter description here...
+  * Returns true if all fields pass validation.
   *
-  * @param unknown_type $data
-  * @return unknown
+  * @param array $data POST data
+  * @return boolean True if there are no errors
   */
 	function validates ($data=null) {
 		$errors = count($this->invalidFields($data? $data: $this->data));
@@ -592,20 +628,20 @@ class Model extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns an array of invalid fields.
   *
-  * @param unknown_type $data
-  * @return unknown
+  * @param array $data Posted data
+  * @return array Array of invalid fields
   */
 	function invalidFields ($data=null) {
 		return $this->_invalidFields($data);
 	}
 
 /**
-  * Enter description here...
+  * Returns an array of invalid fields.
   *
-  * @param unknown_type $data
-  * @return unknown
+  * @param array $data 
+  * @return array Array of invalid fields
   */
 	function _invalidFields ($data=null) {
 		if (!isset($this->validate))
diff --git a/libs/object.php b/libs/object.php
index 45bd55f4c..e821b67d6 100644
--- a/libs/object.php
+++ b/libs/object.php
@@ -58,20 +58,20 @@ class Object {
 	}
 
 /**
-  * Class constructor, overriden in descendant classes
+  * Class constructor, overriden in descendant classes.
   */
 	function __construct() {
 	}
 
 /**
-  * Class destructor, overriden in descendant classes
+  * Class destructor, overriden in descendant classes.
   */
 	function __destruct() {
 	}
 
 /**
-  * Object-to-string conversion
-  * Each class can override it as necessary
+  * Object-to-string conversion.
+  * Each class can override it as necessary.
   *
   * @return string this class' name
   */
@@ -80,9 +80,9 @@ class Object {
 	}
 
 /**
-  * API for logging events
+  * API for logging events.
   *
-  * @param string $msg
+  * @param string $msg Log message
   * @param string $type
   */
 	function log ($msg, $type=LOG_ERROR) {
diff --git a/libs/test.php b/libs/test.php
index ca7f1de1c..a16ef4c3b 100644
--- a/libs/test.php
+++ b/libs/test.php
@@ -46,9 +46,9 @@
   */
 
 /**
-  * Enter description here...
+  * Outputs given string.
   *
-  * @param unknown_type $msg
+  * @param string $msg
   */
 function trace($msg) {
 	return;
@@ -63,10 +63,10 @@ if (phpversion() >= '4') {
 /**
   * Enter description here...
   *
-  * @param unknown_type $errno
-  * @param unknown_type $errstr
-  * @param unknown_type $errfile
-  * @param unknown_type $errline
+  * @param unknown_type $errno Error number
+  * @param string $errstr Error string
+  * @param unknown_type $errfile Error filename
+  * @param unknown_type $errline Error on line
   */
 	  function PHPUnit_error_handler($errno, $errstr, $errfile, $errline) {
 	global $PHPUnit_testRunning;
@@ -85,22 +85,22 @@ if (phpversion() >= '4') {
 class TestException {
 	  /* Emulate a Java exception, sort of... */
 /**
-  * Enter description here...
+  * Message of the exception
   *
-  * @var unknown_type
+  * @var string
   */
 	var $message;
 /**
- * Enter description here...
+ * Type of exception
  *
- * @var unknown_type
+ * @var string
  */
 	var $type;
 /**
-  * Enter description here...
+  * Constructor.
   *
-  * @param unknown_type $message
-  * @param unknown_type $type
+  * @param string $message
+  * @param string $type
   * @return TestException
   */
 	function TestException($message, $type = 'FAILURE') {
@@ -108,17 +108,17 @@ class TestException {
 	  $this->type = $type;
 	}
 /**
-  * Enter description here...
+  * Returns the exception's message.
   *
-  * @return unknown
+  * @return string Message of exception
   */
 	function getMessage() {
 	  return $this->message;
 	}
 /**
-  * Enter description here...
+  * Returns the exception's type.
   *
-  * @return unknown
+  * @return string Type of exception
   */
 	function getType() {
 	  return $this->type;
@@ -138,8 +138,8 @@ class Assert {
 /**
   * Enter description here...
   *
-  * @param unknown_type $boolean
-  * @param unknown_type $message
+  * @param boolean $boolean
+  * @param string $message
   */
 	function assert($boolean, $message=0) {
 	  if (! $boolean)
@@ -204,10 +204,10 @@ class Assert {
 	}
 
 /**
-  * Enter description here...
+  * Assert regular expression
   *
-  * @param unknown_type $regexp
-  * @param unknown_type $actual
+  * @param string $regexp
+  * @param string $actual
   * @param unknown_type $message
   */
 	function assertRegexp($regexp, $actual, $message=false) {
diff --git a/libs/time.php b/libs/time.php
index 552ac9217..5fb3d8ed1 100644
--- a/libs/time.php
+++ b/libs/time.php
@@ -61,7 +61,7 @@ class Time extends Object {
 /**
   * Enter description here...
   *
-  * @param unknown_type $date_string
+  * @param string $date_string Datetime string
   * @return unknown
   */
 	function niceShort ($date_string=null) {
@@ -78,40 +78,40 @@ class Time extends Object {
 	}
 
 /**
-  * Enter description here...
+  * Returns true if given datetime string is today.
   *
-  * @param unknown_type $date
-  * @return unknown
+  * @param string $date Datetime string
+  * @return boolean True if datetime string is today
   */
 	function isToday ($date) {
 		return date('Y-m-d', $date) == date('Y-m-d', time());
 	}
 
 /**
-  * Enter description here...
+  * Returns true if given datetime string is within current year.
   *
-  * @param unknown_type $date
-  * @return unknown
+  * @param string $date Datetime string
+  * @return boolean True if datetime string is within current year
   */
 	function isThisYear ($date) {
 		return date('Y', $date) == date('Y', time());
 	}
 
 /**
-  * Enter description here...
+  * Returns true if given datetime string was yesterday.
   *
-  * @param unknown_type $date
-  * @return unknown
+  * @param string $date Datetime string
+  * @return boolean True if datetime string was yesterday
   */
 	function wasYesterday ($date) {
 		return date('Y-m-d', $date) == date('Y-m-d', strtotime('yesterday'));
 	}
 
 /**
-  * Enter description here...
+  * Returns a Unix timestamp from a textual datetime description. Wrapper for PHP function strtotime().
   *
-  * @param string $date_string
-  * @return unknown
+  * @param string $date_string Datetime string to be represented as a Unix timestamp
+  * @return int Unix timestamp
   */
 	function fromString ($date_string) {
 		return strtotime($date_string);
@@ -134,15 +134,15 @@ class Time extends Object {
  *      
  *      Relative dates look something like this:
  *          3 weeks, 4 days ago
- *	    15 seconds ago
+ *          15 seconds ago
  *      Formatted dates look like this:
  *          on 02/18/2004
  *      
  *      The function includes 'ago' or 'on' and assumes you'll properly add a word
  *      like 'Posted ' before the function output.
  *      
- * @param $datetimne	time in strtotime parsable format
- * @return	 string	relative time string.
+ * @param $datetime	Time in strtotime parsable format
+ * @return string Relative time string.
  */
 
 	function timeAgoInWords ($datetime) {
diff --git a/libs/validators.php b/libs/validators.php
index 605b37f84..e17918f26 100644
--- a/libs/validators.php
+++ b/libs/validators.php
@@ -31,38 +31,22 @@
   */
 
 /**
-  * Enter description here...
-  *
+  * Not empty.
   */
 define('VALID_NOT_EMPTY', '/.+/');
 
 /**
-  * Enter description here...
-  *
+  * Numbers [0-9] only.
   */
 define('VALID_NUMBER', '/^[0-9]+$/');
 
 /**
-  * Enter description here...
-  *
+  * 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');
 
 /**
-  * Enter description here...
-  *
-  */
-define('VALID_TAG', '/[^\ ]+/i');
-
-/**
-  * Enter description here...
-  *
-  */
-define('VALID_TAGS', '/.+/i');
-
-/**
-  * Enter description here...
-  *
+  * A valid year (1000-2999).
   */
 define('VALID_YEAR', '/^[12][0-9]{3}$/');