API Documentation updates

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@47766 467b73ca-7a2a-4603-9d3b-597d59a354a9

_config.php

@@ -12,10 +12,11 @@
  * <code>
  * Authenticator::register_authenticator('OpenIDAuthenticator');
  * </code>
+ *
+ * @package sapphire
+ * @subpackage core
  */
 
-
-
 /**
  * Add pear parser to include path
  */

api/RSSFeed.php

@@ -9,6 +9,8 @@
  * RSSFeed class
  *
  * This class is used to create an RSS feed.
+ * @package sapphire
+ * @subpackage integration
  */
 class RSSFeed extends ViewableData {
 
@@ -191,6 +193,8 @@ class RSSFeed extends ViewableData {
  * This class is used for entries of an RSS feed.
  *
  * @see RSSFeed
+ * @package sapphire
+ * @subpackage integration
  */
 class RSSFeed_Entry extends ViewableData {
 

api/RestfulService.php

@@ -8,6 +8,8 @@
 /**
  * RestfulService class allows you to consume various RESTful APIs.
  * Through this you could connect and aggregate data of various web services.
+ * @package sapphire
+ * @subpackage integration
  */
 class RestfulService extends ViewableData {
 	protected $baseURL;
@@ -24,7 +26,7 @@ class RestfulService extends ViewableData {
 	
 	/**
  	* Sets the Query string parameters to send a request.
- 	* @param params An array passed with necessary parameters. 
+ 	* @param $params array An array passed with necessary parameters. 
  	*/
 	function setQueryString($params=NULL){
 		$this->queryString = http_build_query($params,'','&');
@@ -85,9 +87,9 @@ class RestfulService extends ViewableData {
 	
 	/**
  	* Gets attributes as an array, of a particular type of element.
- 	* @params xml - the source xml to parse, this could be the original response received.
+ 	* @param $xml string The source xml to parse, this could be the original response received.
- 	* @params collection - parent node which wraps the elements, if available
+ 	* @param $collection string The name of parent node which wraps the elements, if available
- 	* @params element - element we need to extract the attributes.
+ 	* @param $element string The element we need to extract the attributes.
  	* Example : <photo id="2636" owner="123" secret="ab128" server="2"> 
  	* returns id, owner,secret and sever attribute values of all such photo elements.
  	*/
@@ -117,10 +119,10 @@ class RestfulService extends ViewableData {
 	
 	/**
  	* Gets an attribute of a particular element.
- 	* @params xml - the source xml to parse, this could be the original response received.
+ 	* @param $xml string The source xml to parse, this could be the original response received.
- 	* @params collection - parent node which wraps the element, if available
+ 	* @param $collection string The name of the parent node which wraps the element, if available
- 	* @params element - element we need to extract the attribute
+ 	* @param $element string The element we need to extract the attribute
- 	* @params attr - name of the attribute
+ 	* @param $attr string The name of the attribute
  	*/
 	
 	function getAttribute($xml, $collection=NULL, $element=NULL, $attr){
@@ -142,9 +144,9 @@ class RestfulService extends ViewableData {
 	/**
  	* Gets set of node values as an array. 
  	* When you get to the depth in the hierachchy use node_child_subchild syntax to get the value.
- 	* @params xml - the source xml to parse, this could be the original response received.
+ 	* @param $xml string The the source xml to parse, this could be the original response received.
- 	* @params collection - parent node which wraps the elements, if available
+ 	* @param $collection string The name of parent node which wraps the elements, if available
- 	* @params element - element we need to extract the node values.
+ 	* @param $element string The element we need to extract the node values.
  	*/
 	
 	function getValues($xml, $collection=NULL, $element=NULL){
@@ -182,9 +184,9 @@ class RestfulService extends ViewableData {
 	
 	/**
  	* Gets a single node value. 
- 	* @params xml - the source xml to parse, this could be the original response received.
+ 	* @param $xml string The source xml to parse, this could be the original response received.
- 	* @params collection - parent node which wraps the elements, if available
+ 	* @param $collection string The name of parent node which wraps the elements, if available
- 	* @params element - element we need to extract the node value.
+ 	* @param $element string The element we need to extract the node value.
  	*/
 	
 	function getValue($xml, $collection=NULL, $element=NULL){

api/SapphireSoapServer.php

@@ -7,6 +7,8 @@
 
 /**
  * Soap server class
+ * @package sapphire
+ * @subpackage integration
  */
 class SapphireSoapServer extends Controller {
 	static $methods = array();

api/SimplePie.php

@@ -5,28 +5,18 @@
  * @subpackage integration
  */
 
-/****************************************************
+/**
-SIMPLEPIE
+ * A PHP-Based RSS and Atom Feed Framework
-A PHP-Based RSS and Atom Feed Framework
+ * Takes the hard work out of managing a complete RSS/Atom solution.
-Takes the hard work out of managing a complete RSS/Atom solution.
+ * Version: "Lemon Meringue"
-
+ * Updated: 3 November 2006
-Version: "Lemon Meringue"
+ * Copyright: 2004-2006 Ryan Parman, Geoffrey Sneddon
-Updated: 3 November 2006
+ * http://simplepie.org
-Copyright: 2004-2006 Ryan Parman, Geoffrey Sneddon
+ * LICENSE: GNU Lesser General Public License 2.1 (LGPL)
-http://simplepie.org
+ * Please submit all bug reports and feature requests to the SimplePie forums. http://simplepie.org/support/
-
+ * @package sapphire
-*****************************************************
+ * @subpackage integration
-LICENSE:
+ */
-
-GNU Lesser General Public License 2.1 (LGPL)
-http://creativecommons.org/licenses/LGPL/2.1/
-
-*****************************************************
-Please submit all bug reports and feature requests to the SimplePie forums.
-http://simplepie.org/support/
-
-****************************************************/
-
 class SimplePie
 {
 	// SimplePie Info
@@ -1178,6 +1168,10 @@ EOT;
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
 class SimplePie_Item
 {
 	var $data;
@@ -1687,6 +1681,10 @@ class SimplePie_Item
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
 class SimplePie_Author
 {
 	var $name;
@@ -1738,6 +1736,10 @@ class SimplePie_Author
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
 class SimplePie_Enclosure
 {
 	var $link;
@@ -2125,6 +2127,10 @@ class SimplePie_Enclosure
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
 class SimplePie_File
 {
 	var $url;
@@ -2383,6 +2389,10 @@ class SimplePie_File
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
 class SimplePie_Cache
 {
 	var $location;
@@ -2450,6 +2460,10 @@ class SimplePie_Cache
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
 class SimplePie_Misc
 {
 	function absolutize_url($relative, $base)
@@ -3560,6 +3574,10 @@ class SimplePie_Misc
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
 class SimplePie_Locator
 {
 	var $useragent;
@@ -3764,6 +3782,10 @@ class SimplePie_Locator
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
 class SimplePie_Parser
 {	
 	var $encoding;
@@ -4396,6 +4418,10 @@ class SimplePie_Parser
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
 class SimplePie_Sanitize
 {
 	// Private vars

api/Spyc.php

@@ -13,6 +13,8 @@
 
 /**
  * A node, used by Spyc for parsing YAML.
+ * @package sapphire
+ * @subpackage misc
  */
 class YAMLNode {
   /**#@+
@@ -60,6 +62,8 @@ class YAMLNode {
  *   $parser = new Spyc;
  *   $array  = $parser->load($file);
  * </code>
+ * @package sapphire
+ * @subpackage misc
  */
 class Spyc {
 
@@ -842,7 +846,7 @@ class Spyc {
    * An ever-so-slightly modified version of the array_kmerge() function posted
    * to php.net by mail at nospam dot iaindooley dot com on 2004-04-08.
    *
-   * http://us3.php.net/manual/en/function.array-merge.php#41394
+   * http://us3.php.net/manual/en/function.array-merge.php
    *
    * @access private
    * @param array $arr1

cli-script.php

@@ -1,8 +1,17 @@
 #!/usr/bin/php5
 <?php
+
+
 /**
- * Main file that handles every page request.
+ * File similar to main.php designed for command-line scripts
+ * 
+ * This file lets you execute Sapphire requests from the command-line.  The URL is passed as the first argument to the scripts.
+ * 
+ * @package sapphire
+ * @subpackage core
  */
+
+
 $_SERVER['HTTP_HOST'] = $_SERVER['argv'][2];
 $_SERVER['SCRIPT_FILENAME'] = __FILE__;
 chdir(dirname($_SERVER['SCRIPT_FILENAME']));

cli/CliController.php

@@ -6,8 +6,10 @@
  */
 
 /**
-* Base class invoked from CLI rather than the webserver (Cron jobs, handling email bounces)
+ * Base class invoked from CLI rather than the webserver (Cron jobs, handling email bounces)
-*/
+ * @package sapphire
+ * @subpackage cron
+ */
 abstract class CliController extends Controller {
     function init() {
       $this->disableBasicAuth();

cli/DailyTask.php

@@ -7,6 +7,8 @@
 
 /**
  * Classes that must be run daily extend this class
+ * @package sapphire
+ * @subpackage cron
  */
 class DailyTask extends ScheduledTask {
 	

cli/MonthlyTask.php

@@ -7,6 +7,8 @@
 
 /**
  * Classes that must be run monthly extend this class
+ * @package sapphire
+ * @subpackage cron
  */
 class MonthlyTask extends ScheduledTask {
 

cli/ScheduledTask.php

@@ -7,6 +7,8 @@
 
 /**
  * Abstract task representing scheudled tasks
+ * @package sapphire
+ * @subpackage cron
  */
 abstract class ScheduledTask extends CliController {
     // this class exists as a logical extension

cli/WeeklyTask.php

@@ -7,6 +7,8 @@
 
 /**
  * Classes that must be run weekly extend this class
+ * @package sapphire
+ * @subpackage cron
  */
 class WeeklyTask extends ScheduledTask {
 

core/ArrayData.php

@@ -15,6 +15,8 @@
  *    "ClassName" => "Page",
  *    "AddAction" => "Add a new Page page",
  * ));
+ * @package sapphire
+ * @subpackage view
  */
 class ArrayData extends ViewableData {
 

core/ArrayLib.php

@@ -7,6 +7,8 @@
 
 /**
  * Library of static methods for manipulating arrays.
+ * @package sapphire
+ * @subpackage misc
  */
 class ArrayLib extends Object {
 	static function invert($arr) {

core/ClassInfo.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage core
+ */
+
 /**
  * Provides introspection information about the class tree.
  * It's a cached wrapper around the built-in class functions.  Sapphire uses class introspection heavily

core/Convert.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /**
  * Library of conversion functions, implemented as static methods.
  *

core/Cookie.php

@@ -7,6 +7,8 @@
 
 /**
  * A set of static methods for manipulating cookies.
+ * @package sapphire
+ * @subpackage misc
  */
 class Cookie extends Object {
 	/**

core/Debug.php

@@ -1,7 +1,12 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage core
+ */
+
 /**
  * Class of static methods to support debugging.
- *
  * @package sapphire
  * @subpackage core
  */

core/Email.php

@@ -13,6 +13,8 @@ define('X_MAILER', 'SilverStripe Mailer - version 2006.06.21 (Sent from "'.$_SER
 
 /**
  * Class to support sending emails.
+ * @package sapphire
+ * @subpackage email
  */
 class Email extends ViewableData {
 	protected $from, $to, $subject, $body, $plaintext_body, $cc, $bcc;
@@ -793,8 +795,10 @@ function loadMimeTypes() {
 }
 
 /**
-* Base class that email bounce handlers extend
+ * Base class that email bounce handlers extend
-*/
+ * @package sapphire
+ * @subpackage email
+ */
 class Email_BounceHandler extends Controller {
 	
 	function init() {
@@ -909,6 +913,11 @@ class Email_BounceHandler extends Controller {
     
 }
 
+/**
+ * Database record for recording a bounced email
+ * @package sapphire
+ * @subpackage email
+ */
 class Email_BounceRecord extends DataObject {
     static $db = array(
         'BounceEmail' => 'Varchar',
@@ -924,6 +933,8 @@ class Email_BounceRecord extends DataObject {
 /**
  * This class is responsible for ensuring that members who are on it receive NO email 
  * communication at all. any correspondance is caught before the email is sent.
+ * @package sapphire
+ * @subpackage email
  */
 class Email_BlackList extends DataObject{
 	 static $db = array(

core/Extension.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage core
+ */
+
 /**
  * Add extension that can be added to an object with Object::add_extension().
  * For DataObject extensions, use DataObjectDecorator
@@ -7,7 +12,6 @@
  * @package sapphire
  * @subpackage core
  */
-
 abstract class Extension extends Object {
 	/**
 	 * The DataObject that owns this decorator.

core/HTTP.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /**
  * A class with HTTP-related helpers.
  * Like Debug, this is more a bundle of methods than a class ;-)

core/ManifestBuilder.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage core
+ */
+
 /**
  * Name of the manifest file
  */
@@ -10,14 +15,18 @@ define("MANIFEST_FILE", TEMP_FOLDER . "/manifest" . str_replace(array("/",":", "
  * 
  * The manifest file is a PHP include that contains global variables that
  * represent the collected contents of the application:
- *   - all classes
+ *   - all classes ({@link __autoload()})
- *   - all templates
+ *   - all templates ({@link SSViewer})
  *   - all _config.php files
  *
  * Traversing the filesystem to collect this information on everypage.
  * This information is cached so that it need not be regenerated on every
  * pageview.
+ * 
+ * {@link ManifestBuilder::compileManifest()} is called by {@link main.php} 
+ * whenever {@link ManifestBuilder::staleManifest()} returns true.
  *
+ * @see main.php, __autoload(), SSViewer, Requirements::themedCSS()
  * @package sapphire
  * @subpackage core
  */

core/Object.php

@@ -8,6 +8,8 @@
 /**
  * Base object that all others should inherit from.
  * This object provides a number of helper methods that patch over PHP's deficiencies.
+ * @package sapphire
+ * @subpackage core
  */
 class Object {
 	/**

core/Requirements.php

@@ -8,6 +8,8 @@
 /**
  * Requirements tracker, for javascript and css.
  * @todo Document the requirements tracker, and discuss it with the others.
+ * @package sapphire
+ * @subpackage view
  */
 class Requirements {
 	private static $javascript = array();

core/SSViewer.php

@@ -14,6 +14,8 @@
  * Compiled templates are cached.  If you put ?flush=1 on your URL, it will force the template to be recompiled.  This
  * is a hack; the system should really detect when a page needs re-fetching.
  * @todo Fix the broken caching.
+ * @package sapphire
+ * @subpackage view
  */
 class SSViewer extends Object {
 	private $chosenTemplates;
@@ -333,7 +335,11 @@ class SSViewer extends Object {
 	}
 }
 
-
+/**
+ * Special SSViewer that will process a template passed as a string, rather than a filename.
+ * @package sapphire
+ * @subpackage view
+ */
 class SSViewer_FromString extends SSViewer {
 	protected $content;
 	

core/Session.php

@@ -17,6 +17,8 @@
  * 
  * The instance object is basically just a way of manipulating a set of nested maps, and isn't specific to session data.
  * This class is currently really basic and could do with a more well-thought-out implementation
+ * @package sapphire
+ * @subpackage control
  */
 class Session {
 	public static function set($name, $val) {

core/ViewableData.php

@@ -15,6 +15,8 @@
  * 
  * ViewableData cover page controls, controllers, and data objects.  It's the basic unit of
  * data exchange.  More specifically, it's anything that can be put into a view.
+ * @package sapphire
+ * @subpackage view
  */
 class ViewableData extends Object implements Iterator {
 	/**
@@ -885,6 +887,8 @@ class ViewableData extends Object implements Iterator {
 /**
  * A ViewableData object that has been customised with extra data. Use
  * ViewableData->customise() to create.
+ * @package sapphire
+ * @subpackage view
  */
 class ViewableData_Customised extends ViewableData {
 	public function castingHelperPair($field) {
@@ -991,6 +995,8 @@ class ViewableData_Customised extends ViewableData {
 /**
  * A ViewableData object that has been customised with an extra object. Use
  * ViewableData->customise() to create.
+ * @package sapphire
+ * @subpackage view
  */
 class ViewableData_ObjectCustomised extends ViewableData {
 	function __construct($obj, $extraObj) {
@@ -1060,6 +1066,8 @@ class ViewableData_ObjectCustomised extends ViewableData {
 
 /**
  * Debugger helper.
+ * @package sapphire
+ * @subpackage view
  * @todo Finish this off
  */
 class ViewableData_Debugger extends ViewableData {

core/control/ContentController.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage control
+ */
+
 /**
  * The most common kind if controller; effectively a controller linked to a {@link DataObject}.
  *

core/control/ContentNegotiator.php

@@ -7,6 +7,8 @@
 /**
  * The content negotiator performs text/html or application/xhtml+xml switching.
  * It does this through the static function ContentNegotiator::process()
+ * @package sapphire
+ * @subpackage control
  */
 class ContentNegotiator {
 	protected static $encoding = 'utf-8';

core/control/Controller.php

@@ -12,6 +12,8 @@
  * the appropriate action - either by calling the action method, or displaying the action's template.
  *
  * See {@link getTemplate()} for information on how the template is chosen.
+ * @package sapphire
+ * @subpackage control
  */
 class Controller extends ViewableData {
 	
@@ -44,7 +46,7 @@ class Controller extends ViewableData {
 	}
 	
 	/**
-	 * @return
+	 * @return array The parameters extracted from the URL by the {@link Director}.
 	 */
 	function getURLParams() {
 		return $this->urlParams;
@@ -59,11 +61,32 @@ class Controller extends ViewableData {
 	}
 
 	/**
+	 * Executes this controller, and return an {@link HTTPResponse} object with the result.
+	 * 
+	 * This method first does a few set-up activities:
+	 *  - Push this controller ont to the controller stack - see {@link Controller::curr()} for information about this.
+	 *  - Call {@link init()}
+	 * 
+	 * Then it looks for the action method.  The action is taken from $this->urlParams['Action'] - for this reason, it's important
+	 * to have $Action included in your Director rule
+	 * 
+	 * If $requestParams['executeForm'] is set, then the Controller assumes that we're processing a form.  This is usually
+	 * set by adding ?executeForm=XXX to the form's action URL.  Form processing differs in the following ways:
+	 *  - The action name will be the name of the button clicked.  If no button-click can be detected, the first button in the
+	 *    list will be assumed.
+	 *  - If the given action method doesn't exist on the controller, Controller will look for that method on the Form object.
+	 *    this lets developers package both a form and its action handlers in a single subclass of Form.
+	 * 
+	 * NOTE: You should rarely need to overload run() - this kind of change is only really appropriate for things like nested
+	 * controllers - {@link ModelAsController} and {@link RootURLController} are two examples here.  If you want to make more
+	 * orthodox functionality, it's better to overload {@link init()} or {@link index()}.
+	 * 
+	 * 
+	 * 
 	 * Execute the appropriate action handler.  If none is given, use defaultAction to display
 	 * a template.  The default action will be appropriate in most cases where displaying data
 	 * is the core goal; the Viewer can call methods on the controller to get the data it needs.
 	 * 
-	 * @param array $urlParams named parameters extracted from the URL, including Action.
 	 * @param array $requestParams GET and POST variables.
 	 * @return HTTPResponse The response that this controller produces, including HTTP headers such as redirection info
 	 */

core/control/Director.php

@@ -1,14 +1,21 @@
 <?php
 
 /**
- * Director is responsible for processing the URL
+ * @package sapphire
- * Director is the first step in the "execution pipeline".  It parses the URL, matching it to
+ * @subpackage control
- * one of a number of patterns, and determines the controller, action and any argument to be
+ */
- * used.  It then runs the controller, which will finally run the viewer and/or perform processing
+
- * steps.
+/**
+ * Director is responsible for processing URLs, and providing environment information.
+ * 
+ * The most important part of director is {@link Director::direct()}, which is passed a URL and will execute the appropriate
+ * controller.
+ * 
+ * Director also has a number of static methods that provide information about the environment, such as {@link Director::set_environment_type()}.
  *
  * @package sapphire
  * @subpackage control
+ * @see Director::direct(),Director::addRules(),Director::set_environment_type()
  */
 class Director {
 	
@@ -56,14 +63,31 @@ class Director {
 
 
 	/**
-	 * Add new rules
+	 * Add URL matching rules to the Director.
+	 * 
+	 * The director is responsible for turning URLs into Controller objects.  It does thi
+	 * 
+	 * @param $priority The priority of the rules; higher values will get your rule checked first.  
+	 * We recommend priority 100 for your site's rules.  The built-in rules are priority 10, standard modules are priority 50.
 	 */
 	static function addRules($priority, $rules) {
 		Director::$rules[$priority] = isset(Director::$rules[$priority]) ? array_merge($rules, (array)Director::$rules[$priority]) : $rules;
 	}
 
 	/**
-	 * Process the given URL, creating the appropriate controller and executing it
+	 * Process the given URL, creating the appropriate controller and executing it.
+	 * 
+	 * This method will:
+	 *  - iterate over all of the rules given in {@link Director::addRules()}, and find the first one that matches.
+	 *  - instantiate the {@link Controller} object required by that rule, and call {@link Controller::setURLParams()} to give the URL paramters to the controller.
+	 *  - link the Controller's session to PHP's main session, using {@link Controller::setSession()}.
+	 *  - call {@link Controller::run()} on that controller
+	 *  - save the Controller's session back into PHP's main session.
+	 *  - output the response to the browser, using {@link HTTPResponse::output()}.
+	 * 
+	 * @param $url String, the URL the user is visiting, without the querystring.
+	 * @uses getControllerForURL() The rule-lookup logic is handled by this.
+	 * @uses Controller::run() The actual page logic is handled by this.
 	 */
 	function direct($url) {
 		if(isset($_GET['debug_profile'])) Profiler::mark("Director","direct");
@@ -92,9 +116,16 @@ class Director {
 	
 	/**
 	 * Test a URL request, returning a response object.
+	 * 
+	 * This method is the counterpart of Director::direct() that is used in functional testing.  It will execute the URL given,
+	 * 
 	 * @param $url The URL to visit
 	 * @param $post The $_POST & $_FILES variables
-	 * @param $session The {@link Session} object representing the current session.
+	 * @param $session The {@link Session} object representing the current session.  By passing the same object to multiple
+	 * calls of Director::test(), you can simulate a peristed session.
+	 * 
+	 * @uses getControllerForURL() The rule-lookup logic is handled by this.
+	 * @uses Controller::run() The actual page logic is handled by this.
 	 */
 	function test($url, $post = null, $session = null) {
         $getVars = array();
@@ -405,12 +436,18 @@ class Director {
 	}
 	
 	/**
+	 * Returns true if this script is being run from the command line rather than the webserver.
+	 * 
 	 * @return boolean
 	 */
 	public static function is_cli() {
 		return preg_match('/cli-script\.php/', $_SERVER['SCRIPT_NAME']);
 	}
 
+	////////////////////////////////////////////////////////////////////////////////////////////
+	// Site mode methods
+	////////////////////////////////////////////////////////////////////////////////////////////
+
 	/**
 	 * Sets the site mode (if it is the public site or the cms),
 	 * and runs registered modules.
@@ -443,17 +480,35 @@ class Director {
 		self::$callbacks[$mode][] = $function;
 	}
 
-	static function set_dev_servers($servers) {
+	////////////////////////////////////////////////////////////////////////////////////////////
-		Director::$dev_servers = $servers;
+	// Environment type methods
-	}
+	////////////////////////////////////////////////////////////////////////////////////////////
-	
+
-	static function set_test_servers($servers) {
-		Director::$test_servers = $servers;
-	}
-	
 	/**
-	 * Force the environment type to be dev, test or live.
+	 * Set the environment type of the current site.
-	 * This will affect the results of isLive, isDev, and isTest
+	 *
+	 * Typically, a SilverStripe site have a number of environments: 
+	 *  - development environments, such a copy on your local machine.
+	 *  - test sites, such as the one you show the client before going live.
+	 *  - the live site itself.
+	 * 
+	 * The behaviour of these environments often varies slightly.  For example, development sites may have errors dumped to the screen,
+	 * and order confirmation emails might be sent to the developer instead of the client.
+	 * 
+	 * To help with this, Sapphire support the notion of an environment type.  The environment type can be dev, test, or live.
+	 * 
+	 * You can set it explicitly with Director::set_environment_tpye().  Or you can use {@link Director::set_dev_servers()} and {@link Director::set_test_servers()}
+	 * to set it implicitly, based on the value of $_SERVER['HTTP_HOST'].  If the HTTP_HOST value is one of the servers listed, then
+	 * the environment type will be test or dev.  Otherwise, the environment type will be live.
+	 *
+	 * Dev mode can also be forced by putting ?isDev=1 in your URL, which will ask you to log in and then push the site into dev
+	 * mode for the remainder of the session. Putting ?isDev=0 onto the URL can turn it back.
+	 * Generally speaking, these methods will be called from your _config.php file.
+	 * 
+	 * Once the environment type is set, it can be checked with {@link Director::isDev()}, {@link Director::isTest()}, and
+	 * {@link Director::isLive()}.
+	 * 
+	 * @param $et string The environment type: dev, test, or live.
 	 */
 	static function set_environment_type($et) {
 		if($et != 'dev' && $et != 'test' && $et != 'live') {
@@ -463,10 +518,36 @@ class Director {
 		}
 	}
 
+	/**
+	 * Specify HTTP_HOST values that are development environments.
+	 * For information about environment types, see {@link Director::set_environment_type()}.
+	 * @param $servers array An array of HTTP_HOST values that should be treated as development environments.
+	 */
+	static function set_dev_servers($servers) {
+		Director::$dev_servers = $servers;
+	}
+	
+	/**
+	 * Specify HTTP_HOST values that are test environments.
+	 * For information about environment types, see {@link Director::set_environment_type()}.
+	 * @param $servers array An array of HTTP_HOST values that should be treated as test environments.
+	 */
+	static function set_test_servers($servers) {
+		Director::$test_servers = $servers;
+	}
+
+	/*
+	 * This function will return true if the site is in a live environment.
+	 * For information about environment types, see {@link Director::set_environment_type()}.
+	 */
 	static function isLive() {
 		return !(Director::isDev() || Director::isTest());
 	}
 	
+	/**
+	 * This function will return true if the site is in a development environment.
+	 * For information about environment types, see {@link Director::set_environment_type()}.
+	 */
 	static function isDev() {
 		if(self::$environment_type) return self::$environment_type == 'dev';
 
@@ -495,6 +576,10 @@ class Director {
 		return false;
 	}
 	
+	/**
+	 * This function will return true if the site is in a test environment.
+	 * For information about environment types, see {@link Director::set_environment_type()}.
+	 */
 	static function isTest() {
 		if(self::$environment_type) {
 			return self::$environment_type == 'test';

core/control/FormResponse.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage core
+ */
+
 /**
  * This class collects all output that needs to be returned after an Form-Request to the client. It automatically determines
  * if it needs to send back javascript after an Ajax-Request or just redirect to another page (on a normal request).
@@ -19,11 +25,11 @@
  * - Please DON'T escape literal parameters which are passed to FormResponse, they are escaped automatically.
  * - Some functions assume a {LeftAndMain}-based environment (e.g. load_form())
  * 
- * TODO Force a specific execution order ($forceTop, $forceBottom)
+ * TODO Force a specific execution order ($forceTop, $forceBottom)Ω
  * TODO Extension to return different formats, e.g. JSON or XML
  *
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage core
  */
 class FormResponse {
 	

core/control/HTTPResponse.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage control
+ */
+
 /**
  * Represenets an HTTPResponse returned by a controller.
  *

core/control/ModelAsController.php

@@ -1,12 +1,16 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage control
+ */
+
 /**
  * ModelAsController will hand over all control to the appopriate model object
  * It uses URLSegment to determine the right object.  Also, if (ModelClass)_Controller exists,
  * that controller will be used instead.  It should be a subclass of ContentController.
  *
  * @package sapphire
- * @subpackage control
  */
 class ModelAsController extends Controller implements NestedController {
 	

core/control/NestedController.php

@@ -9,8 +9,9 @@
  * Interface that is implemented by controllers that are designed to hand control over to another controller.  
  * ModelAsController, which selects up a SiteTree object and passes control over to a suitable subclass of ContentController, is a good
  * example of this.
+ * @package sapphire
+ * @subpackage control
  */
- 
 interface NestedController {
 	public function getNestedController();
 

core/control/RootURLController.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage control
+ */
+
 /**
  * This controller handles what happens when you visit the root URL.
  *

core/i18n.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /**
  * Base-class for storage and retrieval of translated entities.
  * Most common use is translation of the CMS-interface through the _t()-method
@@ -24,7 +29,6 @@
  * @package sapphire
  * @subpackage misc
  */
-
 class i18n extends Controller {
 	
 	/**

core/model/ComponentSet.php

@@ -7,6 +7,8 @@
 /**
  * This is a special kind of DataObjectSet used to represent the items linked to in a 1-many or many-many
  * join.  It provides add and remove methods that will update the database.
+ * @package sapphire
+ * @subpackage model
  */
 class ComponentSet extends DataObjectSet {
 	/**

core/model/CurrentPageIdentifier.php

@@ -6,6 +6,7 @@
 
 /**
  * This interface lets us set up objects that will tell us what the current page is.
+ * @package cms
  */
 interface CurrentPageIdentifier {
 	/**

core/model/DB.php

@@ -8,6 +8,8 @@
 /**
  * Global database interface, complete with static methods.
  * Use this class for interacting with the database.
+ * @package sapphire
+ * @subpackage model
  */
 class DB {
 	/**

core/model/DataObject.php

@@ -7,6 +7,8 @@
 
 /**
  * A single database record & abstract class for the data-access-model.
+ * @package sapphire
+ * @subpackage model
  */
 class DataObject extends Controller implements DataObjectInterface {
 	/**
@@ -113,16 +115,10 @@ class DataObject extends Controller implements DataObjectInterface {
 
 	/**
 	 * Create a duplicate of this node.
+	 * Caution: Doesn't duplicate relations.
 	 * 
 	 * @param $doWrite Perform a write() operation before returning the object.  If this is true, it will create the duplicate in the database.
-	 * 
 	 * @return DataObject A duplicate of this node. The exact type will be the type of this node.
-	 * Caution: Doesn't duplicate relations.
-	 * 
-	 * @return DataObject
-	 * Caution: Doesn't duplicate relations.
-	 * 
-	 * @return DataObject
 	 */
 	function duplicate($doWrite = true) {
 		$className = $this->class;
@@ -1408,7 +1404,10 @@ class DataObject extends Controller implements DataObjectInterface {
 	}
 
 	/**
-	 * Get a bunch of fields in a list - a <ul> of <li><b>name:</b> value</li>
+	 * Get a bunch of fields in an HTML LI, like this:
+	 *  - name: value
+	 *  - name: value
+	 *  - name: value
 	 *
 	 * @return string The fields as an HTML unordered list
 	 */

core/model/DataObjectDecorator.php

@@ -10,6 +10,8 @@
  * Plug-ins for additional functionality in your DataObjects
  *
  * DataObject decorators add extra functionality to your data objects.
+ * @package sapphire
+ * @subpackage model
  */
 abstract class DataObjectDecorator extends Extension {
 

core/model/DataObjectInterface.php

@@ -9,6 +9,8 @@
  * similar to DataObject.
  *
  * In addition to the methods defined below, the data of the object should be directly accessible as fields.
+ * @package sapphire
+ * @subpackage model
  */
 interface DataObjectInterface {
 	/**

core/model/DataObjectLog.php

@@ -9,6 +9,8 @@
  * A DataObjectLog is a log of changes that have been made to the database in this session.
  * It was designed to help with updates to the CMS tree, and could be used wherever an Ajax call 
  * needs to update a complex on-screen representation of your data.
+ * @package sapphire
+ * @subpackage model
  */
 class DataObjectLog extends Object {
 	/**

core/model/DataObjectSet.php

@@ -7,6 +7,8 @@
 
 /**
  * This class represents a set of database objects, such as the results of a query
+ * @package sapphire
+ * @subpackage model
  */
 class DataObjectSet extends ViewableData implements Iterator {
 	/**

core/model/Database.php

@@ -8,6 +8,8 @@
 /**
  * Abstract database connectivity class.
  * Sub-classes of this implement the actual database connection libraries
+ * @package sapphire
+ * @subpackage model
  */
 abstract class Database extends Object {
 	/**

core/model/DatabaseAdmin.php

@@ -20,6 +20,8 @@ require_once("core/model/DB.php");
  *
  * Utility functions for administrating the database. These can be accessed
  * via URL, e.g. http://www.yourdomain.com/db/build.
+ * @package sapphire
+ * @subpackage model
  */
 class DatabaseAdmin extends Controller {
 

core/model/ErrorPage.php

@@ -6,6 +6,7 @@
 
 /**
  * ErrorPage holds the content for the page of an error response.
+ * @package cms
  */
 class ErrorPage extends Page {
 

core/model/GhostPage.php

@@ -7,6 +7,7 @@
 /**
  * Ghost pages are placeholder pages that are used to facilitate the apparent support for
  * multiple parents.
+ * @package cms
  */
 class GhostPage extends SiteTree implements HiddenClass {
 	static $has_one = array(

core/model/HiddenClass.php

@@ -7,6 +7,7 @@
 /**
  * Anything that implements HiddenClass won't be shown in user-interface elements.  For example,
  * DataObjects that implement HiddenClass won't be showing in the "new page" dropdown.
+ * @package cms
  */
 interface HiddenClass {
 	

core/model/Hierarchy.php

@@ -8,6 +8,8 @@
 /**
  * DataObjects that use the Hierachy decorator can be be organised as a hierachy, with children and parents.
  * The most obvious example of this is SiteTree.
+ * @package sapphire
+ * @subpackage model
  */
 class Hierarchy extends DataObjectDecorator {
 	protected $markedNodes;
@@ -295,7 +297,7 @@ class Hierarchy extends DataObjectDecorator {
 	}
 
 	/**
-	 * Return a partial tree as a <ul>.
+	 * Return a partial tree as an HTML UL.
 	 */
 	public function partialTreeAsUL($minCount = 50) {
 		$children = $this->owner->AllChildren();

core/model/Image.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents an image attached to a page.
+ * @package sapphire
+ * @subpackage filesystem
  */
 class Image extends File {
 	/**

core/model/MySQLDatabase.php

@@ -7,6 +7,8 @@
 
 /**
  * MySQL connector class.
+ * @package sapphire
+ * @subpackage model
  */
 class MySQLDatabase extends Database {
 	/**

core/model/PDODatabase.php

@@ -7,6 +7,8 @@
 
 /**
  * PDO (general database) connector class.
+ * @package sapphire
+ * @subpackage model
  */
 class PDODatabase extends Database {
 	/**

core/model/PageView.php

@@ -5,6 +5,7 @@
 
 /**
  * Data object that represents any page view in the system.
+ * @package cms
  */
 class PageView extends DataObject {
 

core/model/RedirectorPage.php

@@ -6,6 +6,7 @@
 
 /**
  * A redirector page redirects when the page is visited.
+ * @package cms
  */
 class RedirectorPage extends Page {
 	static $add_action = "Redirector to another page";

core/model/SQLMap.php

@@ -8,6 +8,8 @@
 /**
  * This is a class used to represent key->value pairs generated from database queries.
  * The query isn't actually executed until you need it.
+ * @package sapphire
+ * @subpackage model
  */
 class SQLMap extends Object implements Iterator {
 	/**

core/model/SQLQuery.php

@@ -8,6 +8,8 @@
 /**
  * Object representing a SQL query.
  * The various parts of the SQL query can be manipulated individually.
+ * @package sapphire
+ * @subpackage model
  */
 class SQLQuery extends Object {
 	/**

core/model/SiteTree.php

@@ -10,6 +10,7 @@
  * should inherit from this.
  *
  * In addition, it contains a number of static methods for querying the site tree.
+ * @package cms
  */
 class SiteTree extends DataObject {
 

core/model/Translatable.php

@@ -28,7 +28,8 @@
  * e.g. when overriding the get_one()-calls (which are already extended by {Translatable}).
  * 
  * @author Bernat Foj Capell <bernat@silverstripe.com>
- * 
+ * @package sapphire
+ * @subpackage misc
  */
 class Translatable extends DataObjectDecorator {
 	
@@ -148,7 +149,7 @@ class Translatable extends DataObjectDecorator {
 	/**
 	 * Set default language.
 	 * 
-	 * @paran $lang String
+	 * @param $lang String
 	 */
 	static function set_default_lang($lang) {
 		self::$default_lang = $lang;

core/model/Versioned.php

@@ -8,6 +8,8 @@
 /**
  * The Versioned decorator allows your DataObjects to have several versions, allowing
  * you to rollback changes and view history. An example of this is the pages used in the CMS.
+ * @package sapphire
+ * @subpackage model
  */
 class Versioned extends DataObjectDecorator {
 	/**
@@ -692,6 +694,9 @@ class Versioned extends DataObjectDecorator {
 
 /**
  * Represents a single version of a record.
+ * @package sapphire
+ * @subpackage model
+ * @see Versioned
  */
 class Versioned_Version extends ViewableData {
 	protected $record;

core/model/VirtualPage.php

@@ -8,6 +8,7 @@
 * Virtual Page creates an instance of a  page, with the same fields that the original page had, but readonly.
 * This allows you can have a page in mulitple places in the site structure, with different children without duplicating the content
 * Note: This Only duplicates $db fields and not the $has_one etc.. 
+* @package cms
 */
 class VirtualPage extends Page {
 
@@ -124,7 +125,8 @@ class VirtualPage extends Page {
 }
 
 /**
- * @desc 
+ * Controller for the virtual page.
+ * @package cms
  */
 class VirtualPage_Controller extends Page_Controller {
 

core/model/fieldtypes/Boolean.php

@@ -7,8 +7,8 @@
 
 /**
  * Represents a boolean field.
- * 
+ * @package sapphire
- * @param $defaultVal int
+ * @subpackage model
  */
 class Boolean extends DBField {
 	

core/model/fieldtypes/Currency.php

@@ -8,6 +8,8 @@
 /**
  * Represents a decimal field containing a currency amount.
  * Currency the currency class only supports single currencies.
+ * @package sapphire
+ * @subpackage model
  */
 class Currency extends Decimal {
 	

core/model/fieldtypes/DBField.php

@@ -9,6 +9,8 @@
  * Single field in the database.
  * Every field from the database is represented as a sub-class of DBField.  In addition to supporting
  * the creation of the field in the database,
+ * @package sapphire
+ * @subpackage model
  */
 abstract class DBField extends ViewableData {
 	

core/model/fieldtypes/Date.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents a date field.
+ * @package sapphire
+ * @subpackage model
  */
 class Date extends DBField {
 	

core/model/fieldtypes/Datetime.php

@@ -6,6 +6,11 @@
  */
 
 if(!class_exists('Datetime')) {
+	/**
+	 * @package sapphire
+	 * @subpackage model
+	 * @deprecated Use {@link SSDatetime} instead, as PHP 5.2 has its own Datetime class.  Object::create('Datetime') will instantiate an SSDatetime object.
+	 */
 	class Datetime extends Date {
 		function __construct($name) {
 			user_error('Datetime is deprecated. Use SSDatetime instead.', E_USER_NOTICE);

core/model/fieldtypes/Decimal.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents a Decimal field.
+ * @package sapphire
+ * @subpackage model
  */
 class Decimal extends DBField {
 	protected $wholeSize, $decimalSize;

core/model/fieldtypes/Enum.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents an enumeration field.
+ * @package sapphire
+ * @subpackage model
  */
 class Enum extends DBField {
 	

core/model/fieldtypes/Float.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents a floating point field.
+ * @package sapphire
+ * @subpackage model
  */
 class Float extends DBField {
 	

core/model/fieldtypes/HTMLText.php

@@ -9,6 +9,8 @@
  * Represents a large text field that contains HTML content.
  * 
  * This behaves similarly to Text, but the template processor won't escape any HTML content within it.
+ * @package sapphire
+ * @subpackage model
  */
 class HTMLText extends Text {
 

core/model/fieldtypes/HTMLVarchar.php

@@ -9,6 +9,8 @@
  * Represents a short text field that is intended to contain HTML content.
  *
  * This behaves similarly to Varchar, but the template processor won't escape any HTML content within it.
+ * @package sapphire
+ * @subpackage model
  */
 class HTMLVarchar extends Varchar {
 

core/model/fieldtypes/Int.php

@@ -7,8 +7,8 @@
 
 /**
  * Represents an integer field.
- *
+ * @package sapphire
- * @param $defaultVal int
+ * @subpackage model
  */
 class Int extends DBField {
 

core/model/fieldtypes/Percentage.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents a decimal field from 0-1 containing a percentage value.
+ * @package sapphire
+ * @subpackage model
  */
 class Percentage extends Decimal {
 	

core/model/fieldtypes/SSDatetime.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents a date-time field.
+ * @package sapphire
+ * @subpackage model
  */
 class SSDatetime extends Date {
 	function setValue($value) {

core/model/fieldtypes/Text.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents a long text field.
+ * @package sapphire
+ * @subpackage model
  */
 class Text extends DBField {
 	static $casting = array(

core/model/fieldtypes/Time.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents a column in the database with the type 'Time'
+ * @package sapphire
+ * @subpackage model
  */
 class Time extends DBField {
 

core/model/fieldtypes/Varchar.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents a short text field.
+ * @package sapphire
+ * @subpackage model
  */
 class Varchar extends DBField {
 	protected $size;

email/Notifications.php

@@ -8,6 +8,7 @@
  * The Notifications class allows you to create email notifications for various events.
  * It lets your scripts generate a number of notifications, and delay sending of the emails until
  * the end of execution, so that multiple notifications can collated together
+ * @package cms
  */
 class Notifications extends Object {
 	protected static $events = array();

email/QueuedEmail.php

@@ -7,6 +7,8 @@
 
 /**
  * Stores a queued email to be sent at the given time
+ * @package sapphire
+ * @subpackage email
  */
 class QueuedEmail extends DataObject {
 	

email/QueuedEmailDispatchTask.php

@@ -7,6 +7,8 @@
 
 /**
  * Daily task to send queued email.
+ * @package sapphire
+ * @subpackage email
  */
 class QueuedEmailDispatchTask extends DailyTask {
 	

filesystem/Archive.php

@@ -8,6 +8,8 @@
 /**
  * Class for handling archives.
  * To implement a specific archive system, create a subclass of this abstract class, and amend the implementation of Archive::open().
+ * @package sapphire
+ * @subpackage filesystem
  */
 abstract class Archive extends Object {
 	/**

filesystem/File.php

@@ -11,6 +11,8 @@
  * looks at the db object to gather information about a file such as URL
  *
  * It then uses this for all processing functions (like image manipulation)
+ * @package sapphire
+ * @subpackage filesystem
  */
 class File extends DataObject {
 	static $default_sort = "Name";

filesystem/Filesystem.php

@@ -7,6 +7,8 @@
 
 /**
  * A collection of static methods for manipulating the filesystem.
+ * @package sapphire
+ * @subpackage filesystem
  */
 class Filesystem extends Object {
 	

filesystem/Folder.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents a folder in the assets directory.
+ * @package sapphire
+ * @subpackage filesystem
  */
 class Folder extends File {
 	

filesystem/GD.php

@@ -7,6 +7,8 @@
 
 /**
  * A wrapper class for GD-based images, with lots of manipulation functions.
+ * @package sapphire
+ * @subpackage filesystem
  */
 class GD extends Object {
 	protected $gd, $width, $height;

filesystem/PostBackup.php

@@ -1,12 +1,14 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage core
  */
 
 /**
  * Writes the POST array to a file as a last-ditch effort to preserve entered data.
+ * @package forms
+ * @subpackage core
  */
 class PostBackup extends Object {
 	

filesystem/TarballArchive.php

@@ -7,6 +7,8 @@
 
 /**
  * Implementation of .tar, .tar.gz, and .tar.bz2 archive handler.
+ * @package sapphire
+ * @subpackage filesystem
  */
 class TarballArchive extends Archive {
 	private $filename = '';

forms/AjaxFormAction.php

@@ -1,8 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage actions
+ */
 
 /**
  * Action button with Ajax/JavaScript overloading.
+ * @package forms
+ * @subpackage actions
  */
 class AjaxFormAction extends FormAction {
 	protected $ajaxAction;

forms/AjaxUniqueTextField.php

@@ -1,8 +1,16 @@
 <?php
-	/**
+
-	 * Text field that automatically checks that the value entered is unique for the given
+/**
-	 * set of fields in a given set of tables
+ * @package forms
-	 */
+ * @subpackage fields-formattedinput
+ */
+
+/**
+ * Text field that automatically checks that the value entered is unique for the given
+ * set of fields in a given set of tables
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class AjaxUniqueTextField extends TextField {
 	
 	protected $restrictedField;

forms/AutocompleteTextField.php

@@ -1,6 +1,14 @@
 <?php
+
 /**
- * 
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
+/**
+ * Autocompleting text field, using script.aculo.us
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class AutocompleteTextField extends TextField {
 	

forms/BankAccountField.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
 /**
  * Field for displaying bank account numbers. It separates the bank, branch, account-number and account-suffix.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class BankAccountField extends FormField {
 	

forms/CalendarDateField.php

@@ -1,7 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-datetime
+ */
+
 /**
  * This field creates a date field that shows a calendar on pop-up
+ * @package forms
+ * @subpackage fields-datetime
  */
 class CalendarDateField extends DateField {
 	protected $futureOnly;

forms/CheckboxField.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-basic
+ */
+
 /**
  * Single checkbox field.
+ * @package forms
+ * @subpackage fields-basic
  */
 class CheckboxField extends FormField {
 	/**

forms/CheckboxFieldDisabled.php

@@ -1,8 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-basic
+ */
 
 /**
- * Single checkbox field.
+ * Single checkbox field, disabled
+ * @package forms
+ * @subpackage fields-basic
  */
 class CheckboxFieldDisabled extends CheckboxField {
 	/**

forms/CheckboxSetField.php

@@ -1,9 +1,17 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-basic
+ */
+
 /**
  * Displays a set of checkboxes as a logical group.
  *
  * ASSUMPTION -> IF you pass your source as an array, you pass values as an array too.
  * 				Likewise objects are handled the same.
+ * @package forms
+ * @subpackage fields-basic
  */
 class CheckboxSetField extends OptionsetField {
 	

forms/ComplexRequiredFields.php

@@ -1,9 +1,16 @@
 <?php 
 
 /**
- * Bulk of the form system
+ * @package forms
+ * @subpackage validators
  */
 
+/**
+ * Validator that makes it easy to do required-fields while still allowing custom behaviour.
+ * @package forms
+ * @subpackage validators
+ * @deprecated How is this better than / different from {@link CustomRequiredFields}?
+ */
 class ComplexRequiredFields extends RequiredFields{
 	protected $required;
 

forms/ComplexTableField.php

@@ -1,8 +1,8 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fields-relational
  */
 
 /**
@@ -19,18 +19,20 @@
  *
  * Example-URL for a "DetailForm"-call explained:
  * "/admin/family/?executeForm=EditForm&action_callfieldmethod&fieldName=Individual&childID=7&methodName=edit"
- * - executeForm			Name of the form on the main rendering page (e.g. "FamilyAdmin")
+ *  - executeForm			Name of the form on the main rendering page (e.g. "FamilyAdmin")
- * - action_callfieldmethod	Trigger to call a method of a single field in "EditForm" instead of rendering the whole thing
+ *  - action_callfieldmethod	Trigger to call a method of a single field in "EditForm" instead of rendering the whole thing
- * - fieldName				Name of the targeted formField
+ *  - fieldName				Name of the targeted formField
- * - methodName				Method on the formfield (e.g. "ComplexTableField")
+ *  - methodName				Method on the formfield (e.g. "ComplexTableField")
- * - childID				Identifier of the database-record (the targeted table is determined by the $sourceClass parameter)
+ *  - childID				Identifier of the database-record (the targeted table is determined by the $sourceClass parameter)
  *
- * TODO Find a less fragile solution for accessing this field through the main controller and ReferencedField, e.g.
+ * @todo Find a less fragile solution for accessing this field through the main controller and ReferencedField, e.g.
  *      build a seperate CTF-instance (doesn't necessarly have to be connected to the original by ReferencedField)
- * TODO Control width/height of popup by constructor (hardcoded at the moment)
+ * @todo Control width/height of popup by constructor (hardcoded at the moment)
- * TODO Integrate search from MemberTableField.php
+ * @todo Integrate search from MemberTableField.php
- * TODO Less performance-hungry implementation of detail-view paging (don't return all items on a single view)
+ * @todo Less performance-hungry implementation of detail-view paging (don't return all items on a single view)
- * TODO Use automatic has-many and many-many functions to return a ComponentSet rather than building the join manually
+ * @todo Use automatic has-many and many-many functions to return a ComponentSet rather than building the join manually
+ * @package forms
+ * @subpackage fields-relational
  */
 class ComplexTableField extends TableListField {
 

forms/CompositeDateField.php

@@ -1,4 +1,15 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-datetime
+ */
+
+/**
+ * Date field that provides 3 dropdowns for entering a date
+ * @package forms
+ * @subpackage fields-datetime
+ */
 class CompositeDateField extends DateField {
 
 	function __construct($name, $title, $value = null, $yearRange = null){

forms/CompositeField.php

@@ -1,9 +1,16 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-structural
+ */
+
 /**
  * Base class for all fields that contain other fields.
  * Implements sequentialisation - so that when we're saving / loading data, we can populate
  * a tabbed form properly.  All of the children are stored in $this->children
+ * @package forms
+ * @subpackage fields-structural
  */
 class CompositeField extends FormField {
 	protected $children;

forms/ConfirmedFormAction.php

@@ -1,8 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage actions
+ */
+
 /**
  * Action button with confirmation text.
  * These button are useful for things like delete buttons.
+ * @package forms
+ * @subpackage actions
  */
 class ConfirmedFormAction extends FormAction {
 	protected $confirmation;

forms/ConfirmedPasswordField.php

@@ -1,8 +1,16 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
 /**
  * Shows two password-fields, and checks for matching passwords.
  * Optionally hides the fields by default and shows
  * a link to toggle their visibility.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class ConfirmedPasswordField extends FormField {
 	

forms/CountryDropdownField.php

@@ -1,8 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
+
 /**
  * A simple extension to dropdown field, pre-configured to list countries.
  * It will default to the country of the current visiotr.
+ * @package forms
+ * @subpackage fields-relational
  */
 class CountryDropdownField extends DropdownField {
 	function __construct($name, $title) {

forms/CreditCardField.php

@@ -1,9 +1,15 @@
 <?php
 
 /**
- * CreditCard field, contains validation and formspec for creditcard fields.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 
+/**
+ * CreditCard field, contains validation and formspec for creditcard fields.
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class CreditCardField extends TextField {
 	
 	function Field() {

forms/CurrencyField.php

@@ -1,7 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
 /**
  * Currency field.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class CurrencyField extends TextField {
 	/**

forms/CustomRequiredFields.php

@@ -1,7 +1,14 @@
 <?php
+
 /**
- * This class allows you to specify special required fields to be executed as 
+ * @package forms
- * part of form validation
+ * @subpackage validators
+ */
+
+/**
+ * Specify special required fields to be executed as part of form validation
+ * @package forms
+ * @subpackage validators
  */
 class CustomRequiredFields extends RequiredFields{
 	protected $required;

forms/CustomValidator.php

@@ -1,7 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage validators
+ */
+
 /**
  * Custom javascript validation
+ * @package forms
+ * @subpackage validators
+ * @deprecated How is this better than / different from {@link CustomRequiredFields}?
  */
 class CustomValidator extends Validator {
 	protected $javascriptCode;

forms/DMYCalendarDateField.php

@@ -1,7 +1,15 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-datetime
+ */
+
 /**
  * Displays a date field with day, month and year boxes, with a calendar to select
  * the date
+ * @package forms
+ * @subpackage fields-datetime
  */
 class DMYCalendarDateField extends CalendarDateField {
 	

forms/DMYDateField.php

@@ -1,7 +1,15 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-datetime
+ */
+
 /**
  * Displays a date field with day, month and year boxes, with a calendar to select
  * the date
+ * @package forms
+ * @subpackage fields-datetime
  */
 class DMYDateField extends CalendarDateField {
 	

forms/DataReport.php

@@ -1,7 +1,16 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-reports
+ */
+
 /**
  * Displays complex reports based on base Table of DataObject and available functions/fields provided to
  * the object.
+ * @package forms
+ * @subpackage fields-reports
+ * @deprecated This should be considered alpha code; reporting needs a clean-up.
  */
 class DataReport extends FormField {
 	

forms/DatalessField.php

@@ -1,8 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-dataless
+ */
+
 /**
  * Abstract class for all fields without data.
  * Labels, headings and the like should extend from this.
+ * @package forms
+ * @subpackage fields-dataless
  */
 class DatalessField extends FormField {
 	/**

forms/DateField.php

@@ -1,7 +1,15 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-datetime
+ */
+
 /**
  * Date field.
  * Default Value represented in the format
+ * @package forms
+ * @subpackage fields-datetime
  */
 class DateField extends TextField {
 	

forms/DisabledTransformation.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage transformations
+ */
+
+/**
+ * Transformation that disables all the fields on the form.
+ * @package forms
+ * @subpackage transformations
+ */
 class DisabledTransformation extends FormTransformation {
 	public function transform($field) {
 		return $field->performDisabledTransformation($this);

forms/DropdownField.php

@@ -1,7 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-basic
+ */
+
 /**
  * Dropdown field, created from a <select> tag.
+ * @package forms
+ * @subpackage fields-basic
  */
 class DropdownField extends FormField {
 	protected $source;

forms/DropdownTimeField.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-datetime
+ */
+
+/**
+ * Field for entering time that provides clock for selecting time.
+ * @package forms
+ * @subpackage fields-datetime
+ */
 class DropdownTimeField extends TimeField {
 	
 	function __construct( $name, $title = null, $value = "", $timeformat = 'H:i a' ){

forms/EditForm.php

@@ -1,8 +1,17 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage core
+ */
+
 /**
  * Creates an edit form on a site page.
  * Extends the basic form class to automatically look up, and save to, the data-object referred to
  * by controller->data().
+ * @package forms
+ * @subpackage core
+ * @deprecated I'm not sure if this is in production use?  Is this a legacy of a bygone era?
  */
 class EditForm extends Form {
 	function __construct($controller, $name, FieldSet $fields) {

forms/EditableButton.php

@@ -1,14 +1,14 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
-	/**
+/**
-	 * EditableButton
+ * EditableButton
-	 * Allows a user to modify the text on the button
+ * Allows a user to modify the text on the button
-	 */
+ */
 class EditableButton extends FormField {
 	
 	function Field() {

forms/EditableCheckbox.php

@@ -1,49 +1,51 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
-	/**
+/**
-	 * EditableCheckbox
+ * EditableCheckbox
-	 * A user modifiable checkbox on a UserDefinedForm
+ * A user modifiable checkbox on a UserDefinedForm
-	 */
+ * @package forms
-	class EditableCheckbox extends EditableFormField {
+ * @subpackage fieldeditor
+ */
+class EditableCheckbox extends EditableFormField {
+	
+	// Could remove this and just use value
+	static $db = array(
+		"Checked" => "Boolean"
+	);
+	
+	static $singular_name = 'Checkbox';
+	static $plural_name = 'Checkboxes';
+	
+	function CheckboxField() {
+		$checkbox = new CheckboxField("Fields[".$this->ID."][Default]", "Checked by default", $this->getField('Default'));
 		
-		// Could remove this and just use value
+		if( $this->readonly )
-		static $db = array(
+			$checkbox = $checkbox->performReadonlyTransformation();
-			"Checked" => "Boolean"
-		);
 		
-		static $singular_name = 'Checkbox';
+		return $checkbox->FieldHolder();
-		static $plural_name = 'Checkboxes';
-		
-		function CheckboxField() {
-			$checkbox = new CheckboxField("Fields[".$this->ID."][Default]", "Checked by default", $this->getField('Default'));
-			
-			if( $this->readonly )
-				$checkbox = $checkbox->performReadonlyTransformation();
-			
-			return $checkbox->FieldHolder();
-		}
-		
-		function populateFromPostData( $data ) {
-			$this->setField('Checked', isset($data['Checked']) ? $data['Checked'] : null);
-			parent::populateFromPostData( $data );
-		}
-		
-		function getFormField() {
-			return new CheckboxField( $this->Name, $this->Title, $this->getField('Default') );
-		}
-		
-		function getFilterField() {
-			return new OptionsetField( $this->Name, 
-																 $this->Title, 
-																 array( '-1' => '(Any)',
-																 				'on' => 'Selected',
-																 				'0' => 'Not selected' )
-			);
-		}
 	}
+	
+	function populateFromPostData( $data ) {
+		$this->setField('Checked', isset($data['Checked']) ? $data['Checked'] : null);
+		parent::populateFromPostData( $data );
+	}
+	
+	function getFormField() {
+		return new CheckboxField( $this->Name, $this->Title, $this->getField('Default') );
+	}
+	
+	function getFilterField() {
+		return new OptionsetField( $this->Name, 
+															 $this->Title, 
+															 array( '-1' => '(Any)',
+															 				'on' => 'Selected',
+															 				'0' => 'Not selected' )
+		);
+	}
+}
 ?>

forms/EditableCheckboxGroupField.php

@@ -1,15 +1,16 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
-	/**
+/**
  * EditableDropdown
  * Represents a set of selectable radio buttons
+ * @package forms
+ * @subpackage fieldeditor
  */
-
 class EditableCheckboxGroupField extends EditableFormField {
 	
 	protected $readonly;

forms/EditableCheckboxOption.php

@@ -1,82 +1,82 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
-	/**
+/**
-	 * EditableDropdownOption
+ * EditableDropdownOption
-	 * Represents a single entry in an EditableRadioField
+ * Represents a single entry in an EditableRadioField
-   */
+ * @package forms
-  
+ * @subpackage fieldeditor
-  class EditableCheckboxOption extends DataObject {
+ */
-  	
+class EditableCheckboxOption extends DataObject {
-  	static $default_sort = "Sort";
+	static $default_sort = "Sort";
+
+	// add required here?
+	static $db = array(
+		"Name" => "Varchar",
+		"Title" => "Varchar",
+		"Default" => "Boolean",
+		"Sort" => "Int"
+	);
+	static $has_one = array(
+		"Parent" => "EditableCheckboxGroupField",
+	);
+
+	static $singular_name = "Checkbox option";
+	static $plural_name = "Checkbox options";
+
+	function EditSegment() {
+		return $this->renderWith('EditableFormFieldOption');
+	}
+
+	function TitleField() {
+		return new TextField( "Fields[{$this->ParentID}][{$this->ID}][Title]", null, $this->Title );
+	}
+
+	function Name() {
+		return "Fields[{$this->ParentID}][{$this->ID}]";
+	}
+
+	function populateFromPostData( $data ) {
+		$this->Title = $data['Title'];
+		$this->setField('Default', $data['Default']);
+		$this->Sort = $data['Sort'];
+		$this->write();
+	}
+
+	function Option() {
+		// return new radio field
+		/*$title = Convert::raw2att( $this->Title );
 	
-		// add required here?
+		$default = "";
-		static $db = array(
+	
-			"Name" => "Varchar",
+		if( $this->getField('Default') )
-			"Title" => "Varchar",
+			$default = '+';
-			"Default" => "Boolean",
+		else
-			"Sort" => "Int"
+			$default = '-';
-		);
+	 
-		static $has_one = array(
+		//Debug::show($this);
-			"Parent" => "EditableCheckboxGroupField",
+		return '<input type="text" name="Fields['.$this->ParentID.']['.$this->ID.'][Title]" value="'.$default.$title.'" />';*/
-		);
+	
+		return $this->EditSegment();
+	}
+
+	function ReadonlyOption() {
+		$this->readonly = true;
+		return $this->EditSegment();
+	}
+
+	function DefaultSelect() {
+		if( $this->readonly )
+			$disabled = " disabled=\"disabled\"";
 		
-		static $singular_name = "Checkbox option";
+		if( $this->getField('Default') )
-		static $plural_name = "Checkbox options";
+			$default = " checked=\"checked\"";
 	
-		function EditSegment() {
+		return "<input class=\"checkbox\" type=\"checkbox\" name=\"Fields[{$this->ParentID}][{$this->ID}][Default]\" value=\"1\"".$disabled.$default." />";
-			return $this->renderWith('EditableFormFieldOption');
+	}
-		}
+}
-	
-		function TitleField() {
-			return new TextField( "Fields[{$this->ParentID}][{$this->ID}][Title]", null, $this->Title );
-		}
-	
-		function Name() {
-			return "Fields[{$this->ParentID}][{$this->ID}]";
-		}
-	
-		function populateFromPostData( $data ) {
-			$this->Title = $data['Title'];
-			$this->setField('Default', $data['Default']);
-			$this->Sort = $data['Sort'];
-			$this->write();
-		}
-  	
-  	function Option() {
-  		// return new radio field
-  		/*$title = Convert::raw2att( $this->Title );
-  		
-  		$default = "";
-  		
-  		if( $this->getField('Default') )
-  			$default = '+';
-  		else
-  			$default = '-';
-  		 
-  		//Debug::show($this);
-  		return '<input type="text" name="Fields['.$this->ParentID.']['.$this->ID.'][Title]" value="'.$default.$title.'" />';*/
-  		
-  		return $this->EditSegment();
-  	}
-  	
-  	function ReadonlyOption() {
-  		$this->readonly = true;
-  		return $this->EditSegment();
-  	}
-  	
-  	function DefaultSelect() {
-  		if( $this->readonly )
-  			$disabled = " disabled=\"disabled\"";
-  			
-  		if( $this->getField('Default') )
-  			$default = " checked=\"checked\"";
-  		
-  		return "<input class=\"checkbox\" type=\"checkbox\" name=\"Fields[{$this->ParentID}][{$this->ID}][Default]\" value=\"1\"".$disabled.$default." />";
-  	}
-  }
 ?>

forms/EditableDateField.php

@@ -1,13 +1,15 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
 /**
  * EditableDateField
  * Allows a user to add a date field to the Field Editor
+ * @package forms
+ * @subpackage fieldeditor
  */
 class EditableDateField extends EditableFormField {
 	static $singular_name = 'Date field';

forms/EditableDropdown.php

@@ -1,15 +1,16 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
-	/**
+/**
-	 * EditableDropdown
+ * EditableDropdown
-	 * Represents a modifiable dropdown box on a form
+ * Represents a modifiable dropdown box on a form
-	 */
+ * @package forms
-
+ * @subpackage fieldeditor
+ */
 class EditableDropdown extends EditableFormField {
 	
 	static $has_many = array(

forms/EditableDropdownOption.php

@@ -1,30 +1,30 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
-	/**
+/**
-	 * EditableDropdownOption
+ * EditableDropdownOption
-	 * Represents a single entry in an EditableDropdown
+ * Represents a single entry in an EditableDropdown
-   */
+ * @package forms
-  
+ * @subpackage fieldeditor
-  class EditableDropdownOption extends DataObject {
+ */  
-  	
+class EditableDropdownOption extends DataObject {
-  	protected $readonly;
+	protected $readonly;
-  	
+
-  	function ReadonlyOption() {
+	function ReadonlyOption() {
-  		$this->readonly = true;
+		$this->readonly = true;
-  		return $this->EditSegment();
+		return $this->EditSegment();
-  	}
+	}
-  	
+
-  	function isReadonly() {
+	function isReadonly() {
-  		return $this->readonly;
+		return $this->readonly;
-  	}
+	}
-  	
+
-  	static $default_sort = "Sort";
+	static $default_sort = "Sort";
-	
+
 	// add required here?
 	static $db = array(
 		"Name" => "Varchar",
@@ -35,7 +35,7 @@
 	static $has_one = array(
 		"Parent" => "EditableDropdown",
 	);
-	
+
 	static $singular_name = 'Dropdown option';
 	static $plural_name = 'Dropdown options';
 
@@ -56,29 +56,29 @@
 		$this->Sort = $data['Sort'];
 		$this->write();
 	}
-  	
+ 	
-  	function Option() {
+	function Option() {
-  		// return new radio field
+		// return new radio field
-  		/*$title = $this->Title;
+		/*$title = $this->Title;
-  		
+	
-  		$default = "";
+		$default = "";
-  		
+	
-  		if( $this->getField('Default') )
+		if( $this->getField('Default') )
-  			$default = 'class="default"';
+			$default = 'class="default"';
-  		 
+	 
-  		//Debug::show($this);
+		//Debug::show($this);
-  		return '<input type="text" name="Fields['.$this->ParentID.']['.$this->ID.'][Title]" value="'.$title.'" '.$default.' />';*/
+		return '<input type="text" name="Fields['.$this->ParentID.']['.$this->ID.'][Title]" value="'.$title.'" '.$default.' />';*/
-  		
+	
-  		return $this->EditSegment();
+		return $this->EditSegment();
-  	}
+	}
-  	
+
-  	function DefaultSelect() {
+	function DefaultSelect() {
-  		$disabled = ($this->readonly) ? " disabled=\"disabled\"" : '';		
+		$disabled = ($this->readonly) ? " disabled=\"disabled\"" : '';		
-  			
+		
-  		if( $this->Parent()->getField('Default') == $this->ID )
+		if( $this->Parent()->getField('Default') == $this->ID )
-  			$default = " checked=\"checked\"";
+			$default = " checked=\"checked\"";
-  		
+	
-  		return "<input class=\"radio\" type=\"radio\" name=\"Fields[{$this->ParentID}][Default]\" value=\"{$this->ID}\"".$disabled.$default." />";
+		return "<input class=\"radio\" type=\"radio\" name=\"Fields[{$this->ParentID}][Default]\" value=\"{$this->ID}\"".$disabled.$default." />";
-  	}
+	}
-  }
+}
 ?>

forms/EditableEmailField.php

@@ -1,14 +1,16 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
-	/**
+/**
-	 * EditableEmailField
+ * EditableEmailField
-	 * Allow users to define a validating editable email field for a UserDefinedForm
+ * Allow users to define a validating editable email field for a UserDefinedForm
-	 */
+ * @package forms
+ * @subpackage fieldeditor
+ */
 class EditableEmailField extends EditableFormField {
 	
 	static $db = array(

forms/EditableFileField.php

@@ -1,13 +1,15 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
 /**
  * EditableFileField
  * Allows a user to add a field that can be used to upload a file
+ * @package forms
+ * @subpackage fieldeditor
  */
 class EditableFileField extends EditableFormField {
 	

forms/EditableFormField.php

@@ -1,14 +1,15 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
 /**
  * Represents an editable form field
+ * @package forms
+ * @subpackage fieldeditor
  */
-	 
 class EditableFormField extends DataObject {
 	
 	static $default_sort = "Sort";

forms/EditableFormHeading.php

@@ -1,12 +1,14 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
 /**
  * Allows an editor to insert a generic heading into a field
+ * @package forms
+ * @subpackage fieldeditor
  */
 class EditableFormHeading extends EditableFormField {
 	static $singular_name = 'Form heading';

forms/EditableMemberListField.php

@@ -1,12 +1,14 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
 /**
  * Creates an editable field that displays members in a given group
+ * @package forms
+ * @subpackage fieldeditor
  */
 class EditableMemberListField extends EditableFormField {
 	

forms/EditableRadioField.php

@@ -1,15 +1,16 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
 /**
  * EditableDropdown
  * Represents a set of selectable radio buttons
+ * @package forms
+ * @subpackage fieldeditor
  */
-
 class EditableRadioField extends EditableFormField {
 	
 	static $has_many = array(

forms/EditableRadioOption.php

@@ -1,42 +1,42 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
 /**
  * EditableDropdownOption
  * Represents a single entry in an EditableRadioField
+ * @package forms
+ * @subpackage fieldeditor
  */
-  
+class EditableRadioOption extends DataObject {
-  class EditableRadioOption extends DataObject {
+	protected $readonly;
-  	
-  	protected $readonly;
-  	
-  	function ReadonlyOption() {
-  		$this->readonly = true;
-  		return $this->EditSegment();
-  	}
-  	
-  	function isReadonly() {
-  		return $this->readonly;
-  	}
-  	
-  	static $default_sort = "Sort";
 	
+	function ReadonlyOption() {
+		$this->readonly = true;
+		return $this->EditSegment();
+	}
+	
+	function isReadonly() {
+		return $this->readonly;
+	}
+	
+	static $default_sort = "Sort";
+
 	// add required here?
 	static $db = array(
 		"Name" => "Varchar",
 		"Title" => "Varchar",
 		"Default" => "Boolean",
-           "Value" => "Varchar",
+		"Value" => "Varchar",
 		"Sort" => "Int"
 	);
 	static $has_one = array(
 		"Parent" => "EditableRadioField",
 	);
-	
+
 	static $singular_name = 'Radio option';
 	static $plural_name = 'Radio options';
 
@@ -57,34 +57,34 @@
 		$this->Sort = $data['Sort'];
 		$this->write();
 	}
-  	
+	
-  	function Option() {
+	function Option() {
-  		// return new radio field
+		// return new radio field
-  		/*$title = Convert::raw2att( $this->Title );
+		/*$title = Convert::raw2att( $this->Title );
-  		
+		
-  		$default = "";
+		$default = "";
-  		
+		
-  		if( $this->getField('Default') )
+		if( $this->getField('Default') )
-  			$default = '+';
+			$default = '+';
-  		else
+		else
-  			$default = '-';
+			$default = '-';
-  		 
+		 
-  		//Debug::show($this);
+		//Debug::show($this);
-  		return '<input type="text" name="Fields['.$this->ParentID.']['.$this->ID.'][Title]" value="'.$default.$title.'" />';*/
+		return '<input type="text" name="Fields['.$this->ParentID.']['.$this->ID.'][Title]" value="'.$default.$title.'" />';*/
-  		
+		
-  		return $this->EditSegment();
+		return $this->EditSegment();
-  	}
+	}
-  	
+	
-  	function DefaultSelect() {
+	function DefaultSelect() {
-  		$disabled = ($this->readonly) ? " disabled=\"disabled\"" : '';
+		$disabled = ($this->readonly) ? " disabled=\"disabled\"" : '';
-  			
+			
-  		if($this->Parent()->getField('Default') == $this->ID) {
+		if($this->Parent()->getField('Default') == $this->ID) {
-  			$default = " checked=\"checked\"";
+			$default = " checked=\"checked\"";
 		} else {
 			$default = '';
 		}
-  		
+		
-  		return "<input class=\"radio\" type=\"radio\" name=\"Fields[{$this->ParentID}][Default]\" value=\"{$this->ID}\"".$disabled.$default." />";
+		return "<input class=\"radio\" type=\"radio\" name=\"Fields[{$this->ParentID}][Default]\" value=\"{$this->ID}\"".$disabled.$default." />";
-  	}
+	}
-  }
+}
 ?>

forms/EditableTextField.php

@@ -1,13 +1,15 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fieldeditor
  */
 
 /**
  * EditableTextField
  * This control represents a user-defined field in a user defined form
+ * @package forms
+ * @subpackage fieldeditor
  */
 class EditableTextField extends EditableFormField {
 	

forms/EmailField.php

@@ -1,7 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
 /**
  * Text field with Email Validation.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class EmailField extends TextField {
 	

forms/EncryptField.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
+/**
+ * Duplicate of {@link PasswordField}.
+ * @package forms
+ * @subpackage fields-formattedinput Use {@link PasswordField}
+ */
 class EncryptField extends TextField {
 	function Field() {
 		return "<input class=\"text\" type=\"password\" id=\"" . $this->id() . "\" name=\"{$this->name}\" value=\"" . $this->attrValue() . "\" />";

forms/FieldGroup.php

@@ -1,10 +1,18 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-structural
+ */
+
 /**
  * Lets you include a nested group of fields inside a template.
  * This control gives you more flexibility over form layout.
  * 
  * Note: the child fields within a field group aren't rendered using DefaultFieldHolder.  Instead,
  * SmallFieldHolder() is called, which just prefixes $Field with a <label> tag, if the Title is set.
+ * @package forms
+ * @subpackage fields-structural
  */
 class FieldGroup extends CompositeField {
 	protected $zebra;

forms/FieldSet.php

@@ -1,10 +1,15 @@
 <?php
 
-require_once("forms/Form.php");
+/**
+ * @package forms
+ * @subpackage fields-structural
+ */
 
 /**
  * DataObjectSet designed for form fields.
  * It extends the DataObjectSet with the ability to get a sequential set of fields.
+ * @package forms
+ * @subpackage fields-structural
  */
 class FieldSet extends DataObjectSet {
 	protected $sequentialSet;

forms/FileField.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-files
+ */
+
 /**
  * Represents a file type which can be added to a form.
+ * @package forms
+ * @subpackage fields-files
  */
 class FileField extends FormField {
 	public function Field() {

forms/FileIFrameField.php

@@ -1,7 +1,14 @@
 <?php 
+
 /**
- * A field that will upload files to a page
+ * @package forms
- * for use within the CMS.
+ * @subpackage fields-files
+ */
+
+/**
+ * A field that will upload files to a page for use within the CMS.
+ * @package forms
+ * @subpackage fields-files
  */
 class FileIFrameField extends FileField {
 	

forms/Form.php

@@ -1,8 +1,8 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage core
  */
 
 /**
@@ -19,6 +19,8 @@
  * resource-intensive.
  *
  * @example forms/Form.php See how you can create a form on your controller.
+ * @package forms
+ * @subpackage core
  */
 class Form extends ViewableData {
 	protected $fields, $actions, $controller, $name, $validator;

forms/FormAction.php

@@ -1,8 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage actions
+ */
+
 /**
  * Single action button.
  * The action buttons are <input type="submit"> tags.
+ * @package forms
+ * @subpackage actions
  */
 class FormAction extends FormField {
 	protected $extraData;

forms/FormField.php

@@ -1,8 +1,8 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage core
  */
 
 /**
@@ -10,6 +10,8 @@
  * A FieldSet contains a number of FormField objects which make up the whole of a form.
  * In addition to single fields, FormField objects can be "composite", for example, the {@link TabSet}
  * field.  Composite fields let us define complex forms without having to resort to custom HTML.
+ * @package forms
+ * @subpackage core
  */
 class FormField extends ViewableData {
 	protected $form;

forms/FormTransformation.php

@@ -1,8 +1,8 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage transformations
  */
 
 /**
@@ -16,6 +16,8 @@
  *   - Define transformFieldType($field) methods on your subclass of FormTransformation.
  * 
  * To actually perform the transformation, call $form->transform(new MyTransformation());
+ * @package forms
+ * @subpackage transformations
  */
 class FormTransformation extends Object {
 	function transform(FormField $field) {

forms/GSTNumberField.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
 /**
  * Field for displaying NZ GST numbers (usually 8-9 digits in the format ##-###-### or ##-###-####).
+ * @package forms
+ * @subpackage fields-formattedinput
  * @see http://www.ird.govt.nz/payroll-employers/software-developers/software-specs/
  */
 class GSTNumberField extends TextField {

forms/GroupedDropdownField.php

@@ -1,8 +1,17 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-basic
+ */
+
+/**
+ * Grouped dropdown, using <optgroup>s.
+ * Returns a <select> tag containing all the appropriate <option> tags, with <optgroup> tags around the <option> tags as required
+ * @package forms
+ * @subpackage fields-basic
+ */
 class GroupedDropdownField extends DropdownField {
-  /**
-  * @desc Returns a <select> tag containing all the appropriate <option> tags, with <optgroup> tags around the <option> tags as required
-  */
   function Field() {
 		// Initialisations
 		$options = '';

forms/HasManyComplexTableField.php

@@ -1,10 +1,15 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fields-relational
  */
 
+/**
+ * ComplexTableField designed to edit a has_many join.
+ * @package forms
+ * @subpackage fields-relational
+ */
 class HasManyComplexTableField extends ComplexTableField {
 		
 	public $joinField;

forms/HasOneComplexTableField.php

@@ -1,10 +1,15 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fields-relational
  */
 
+/**
+ * ComplexTableField with a radio button column, designed to edit a has_one join.
+ * @package forms
+ * @subpackage fields-relational
+ */
 class HasOneComplexTableField extends HasManyComplexTableField {
 	
 	public $itemClass = 'HasOneComplexTableField_Item';

forms/HeaderField.php

@@ -1,7 +1,15 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-dataless
+ */
+
 /**
  * Field that generates a heading tag.
  * This can be used to add extra text in your forms.
+ * @package forms
+ * @subpackage fields-dataless
  */
 class HeaderField extends DatalessField {
 	protected $headingLevel, $allowHTML;

forms/HiddenField.php

@@ -1,7 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-dataless
+ */
+
 /**
  * Hidden field.
+ * @package forms
+ * @subpackage fields-dataless
  */
 class HiddenField extends FormField {
 	/**

forms/HiddenFieldGroup.php

@@ -1,10 +1,18 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-structural
+ */
+
 /**
  * Lets you include a nested group of fields inside a template.
  * This control gives you more flexibility over form layout.
  * 
  * Note: the child fields within a field group aren't rendered using DefaultFieldHolder.  Instead,
  * SmallFieldHolder() is called, which just prefixes $Field with a <label> tag, if the Title is set.
+ * @package forms
+ * @subpackage fields-structural
  */
 class HiddenFieldGroup extends FieldGroup {
 	

forms/HtmlEditorField.php

@@ -1,14 +1,16 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fields-formattedinput
  */
 
 /**
  * A WYSIWYG editor field, powered by tinymce.
  * tinymce editor fields are created from <textarea> tags which are then converted with javascript.
  * The {@link Requirements} system is used to ensure that all necessary javascript is included.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class HtmlEditorField extends TextareaField {
 	protected $rows;

forms/HtmlOneLineField.php

@@ -1,9 +1,17 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
 /**
  * A WYSIWYG editor field, powered by tinymce.
  * tinymce editor fields are created from <textarea> tags which are then converted with javascript.
  * The {@link Requirements} system is used to ensure that all necessary javascript is included.
+ * @package forms
+ * @subpackage fields-formattedinput
+ * @deprecated It's not clear that this field works properly.  Just use {@link HtmlEditorField}.
  */
 class HtmlOneLineField extends TextField {
 	/**

forms/ImageField.php

@@ -1,7 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-files
+ */
+
 /**
  * A field that will upload attached images.
+ * @package forms
+ * @subpackage fields-files
  */
 class ImageField extends FileField {
 

forms/ImageFormAction.php

@@ -1,7 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage actions
+ */
+
 /**
  * Action that uses an image instead of a button
+ * @package forms
+ * @subpackage actions
  */
 class ImageFormAction extends FormAction {
 	protected $image, $hoverImage, $className;

forms/InlineFormAction.php

@@ -1,7 +1,15 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage actions
+ */
+
 /**
  * Render a button that will act as 
  * If you want to add custom behaviour, please set {inlcudeDefaultJS} to false and work with behaviour.js.
+ * @package forms
+ * @subpackage actions
  */
 class InlineFormAction extends FormField {
 	

forms/LabelField.php

@@ -1,8 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-dataless
+ */
+
 /**
  * Simple label tag.
  * This can be used to add extra text in your forms.
+ * @package forms
+ * @subpackage fields-dataless
  */
 class LabelField extends DatalessField {
 	protected $className;

forms/LabelledLiteralField.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-dataless
+ */
+
 /**
  * It's a LiteralField ... with a Label
+ * @package forms
+ * @subpackage fields-dataless
  */
 class LabelledLiteralField extends LiteralField {
 	

forms/LanguageDropdownField.php

@@ -1,8 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
+
 /**
  * An extension to dropdown field, pre-configured to list languages.
  * The languages already used in the site will be on top.
+ * @package forms
+ * @subpackage fields-relational
  */
 class LanguageDropdownField extends GroupedDropdownField {
 	

forms/ListboxField.php

@@ -1,7 +1,14 @@
 <?php
 
 /**
- * Dropdown field, created from a <select> tag.
+ * @package forms
+ * @subpackage fields-basic
+ */
+
+/**
+ * Multi-line listbox field, created from a <select> tag.
+ * @package forms
+ * @subpackage fields-basic
  */
 class ListboxField extends DropdownField {
 	protected $source;

forms/LiteralField.php

@@ -1,11 +1,17 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-dataless
+ */
+
 /**
  * This field lets you put an arbitrary piece of HTML into your forms.
  * If there's not much behaviour around the HTML, it might not be worth going to the effort of
  * making a special field type for it.  So you can use LiteralField.  If you pass it a viewabledata object,
  * it will turn it into a string for you. 
- * @pacakge forms
+ * @package forms
+ * @subpackage fields-dataless
  */
 class LiteralField extends DatalessField {
 	protected $content;

forms/LookupField.php

@@ -1,5 +1,17 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-basic
+ */
+
+
+/**
+ * Read-only complement of {@link DropdownField}.
+ * Shows the "human value" of the dropdown field for the currently selected value.
+ * @package forms
+ * @subpackage fields-basic
+ */
 class LookupField extends DropdownField {
 
 	/**

forms/ManyManyComplexTableField.php

@@ -1,10 +1,15 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fields-relational
  */
 
+/**
+ * Special ComplexTableField for editing a many_many relation.
+ * @package forms
+ * @subpackage fields-relational
+ */
 class ManyManyComplexTableField extends HasManyComplexTableField {
 	
 	private $manyManyParentClass;
@@ -77,6 +82,11 @@ HTML;
 	}
 }
 
+/**
+ * One record in a {@link ManyManyComplexTableField}.
+ * @package forms
+ * @subpackage fields-relational
+ */
 class ManyManyComplexTableField_Item extends ComplexTableField_Item {
 	
 	function MarkingCheckbox() {

forms/NamedLabelField.php

@@ -1,7 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-dataless
+ */
+
 /**
  * A {@link LabelField} that lets you give it a name; makes it easier to delete ;)
+ * @package forms
+ * @subpackage fields-dataless
  */
 class NamedLabelField extends LabelField {
 	protected $className;

forms/NoScriptField.php

@@ -1,11 +1,17 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-dataless
+ */
+
 /**
  * This field lets you put an arbitrary piece of HTML into your forms.
  * If there's not much behaviour around the HTML, it might not be worth going to the effort of
  * making a special field type for it.  So you can use LiteralField.  If you pass it a viewabledata object,
  * it will turn it into a string for you. 
- * @pacakge forms
+ * @package forms
+ * @subpackage fields-dataless
  */
 class NoScriptField extends LiteralField {
 	function Field() {

forms/NoScriptFormAction.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage actions
+ */
+
+/**
+ * Action that will only be shown if javascript is disabled.
+ * @package forms
+ * @subpackage actions
+ */
 class NoScriptFormAction extends FormAction {
 	
 	/**

forms/NumericField.php

@@ -1,7 +1,15 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
 /**
  * A Single Numeric field extending a typical 
  * TextField but with validation.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class NumericField extends TextField{
 	

forms/OptionsetField.php

@@ -1,8 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-basic
+ */
+
 /**
  * Set of radio buttons designed to emulate a dropdown.
  * It even uses the same constructor as a dropdown field.
+ * @package forms
+ * @subpackage fields-basic
  */
 class OptionsetField extends DropdownField {
 	
@@ -19,7 +26,7 @@ class OptionsetField extends DropdownField {
 	}
 
 	/**
-	 * Create a <ul> containing sets of radio buttons and labels.  The IDs are set to
+	 * Create a UL tag containing sets of radio buttons and labels.  The IDs are set to
 	 * FieldID_ItemKey, where ItemKey is the key with all non-alphanumerics removed.
 	 */
 	function Field() {

forms/PasswordField.php

@@ -1,7 +1,14 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
 /**
  * Password input field.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class PasswordField extends FormField {
 

forms/PhoneNumberField.php

@@ -1,7 +1,15 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
+
 /**
  * Field for displaying phone numbers. It separates the number, the area code and optionally the country code
  * and extension.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class PhoneNumberField extends FormField {
 	

forms/PopupDateTimeField.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-datetime
+ */
+
+/**
+ * Field for entering a date/time pair.
+ * @package forms
+ * @subpackage fields-datetime
+ */
 class PopupDateTimeField extends CalendarDateField {
 	
 	function Field() {

forms/PrintableTransformation.php

@@ -1,8 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage transformations
+ */
+
 /**
  * Transformation that will make a form printable.
  * Builds on readonly forms with different behaviour for tabsets.
+ * @package forms
+ * @subpackage transformations
  */
 class PrintableTransformation extends ReadonlyTransformation {
 	function transformTabSet($field) {
@@ -15,6 +22,8 @@ class PrintableTransformation extends ReadonlyTransformation {
 
 /**
  * Class representing printable tabsets
+ * @package forms
+ * @subpackage transformations
  */
 class PrintableTransformation_TabSet extends TabSet {
 	function __construct($tabs) {

forms/ProgressBar.php

@@ -1,7 +1,16 @@
 <?php
+
 /**
- * @desc Displays a progress bar in a form. These are currently only linked to Batch Processes (@see BatchProcess)
+ * @package forms
- *
+ * @subpackage fields-dataless
+ */
+
+/**
+ * Displays a progress bar in a form.
+ * These are currently only linked to Batch Processes.
+ * @see BatchProcess
+ * @package forms
+ * @subpackage fields-dataless
  */
 class ProgressBar extends FormField {
 

forms/ReadonlyField.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-basic
+ */
+
 /**
  * Read-only field, with <label> and <span>
+ * @package forms
+ * @subpackage fields-basic
  */
 class ReadonlyField extends FormField {
 

forms/ReadonlyTransformation.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage transformations
+ */
+
+/**
+ * Transformation that will turn a form into a readonly version of itself
+ * @package forms
+ * @subpackage transformations
+ */
 class ReadonlyTransformation extends FormTransformation {
 	// All of the ReadonlyTransformation's functionality is implemented in performReadonlyTransformation()
 	// methods on the individual FormField objects.	

forms/RelatedDataEditor.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
+
 /**
  * RelatedDataEditor puts a "sub-form" into a form that lets you edit a record on the other side of a
  * one-to-many relationship.  For example, you could be editing a workshop, and you want to provide fields
@@ -7,6 +12,8 @@
  *
  * RelatedDataEditor inserts a dropdown field and a number of developer-specified additional fields into the
  * system
+ * @package forms
+ * @subpackage fields-relational
  */
 class RelatedDataEditor extends FormField {
 	protected $children;

forms/ReportField.php

@@ -1,13 +1,15 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fields-reports
  */
 
 /**
  * Displays complex reports based on the list of tables and fields provided to
  * the object.
+ * @package forms
+ * @subpackage fields-reports
  */
 class ReportField extends FormField{
 
@@ -325,6 +327,8 @@ HTML;
 /**
  * Assisting class. Determines whether or not a column is hidden.
  * Not so helpful here, but we could overload it in other classes.
+ * @package forms
+ * @subpackage fields-reports
  */
 class ReportField_SimpleFilter extends Object {
 
@@ -352,6 +356,8 @@ class ReportField_SimpleFilter extends Object {
 /**
  * This class instantiates an instance of the report field and receives ajax requests
  * to the report field.
+ * @package forms
+ * @subpackage fields-reports
  */
 class ReportField_Controller extends Controller {
 

forms/RequiredFields.php

@@ -1,10 +1,18 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage validators
+ */
+
 /**
  * Required Fields allows you to set which fields
  * need to be present before submitting the form
  * Submit an array of arguments or each field as a
  * seperate argument. Validation is performed on a name by
  * name basis.
+ * @package forms
+ * @subpackage validators
  */
 class RequiredFields extends Validator{
 	protected $required;

forms/ResetFormAction.php

@@ -1,6 +1,15 @@
 <?php
+
 /**
- * Clears all fields on a form
+ * @package forms
+ * @subpackage actions
+ */
+
+/**
+ * Action that clears all fields on a form.
+ * Inserts an input tag with type=reset.
+ * @package forms
+ * @subpackage actions
  */
 class ResetFormAction extends FormAction {
 	

forms/RestrictedTextField.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-formatted
+ */
+
 /**
  * A Text field that cannot contain certain characters
+ * @package forms
+ * @subpackage fields-formatted
  */
 class RestrictedTextField extends TextField {
 

forms/SQLReport.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-reports
+ */
+
+/**
+ * @package forms
+ * @subpackage fields-reports
+ * @deprecated This should be considered alpha code; reporting needs a clean-up.
+ */
 class SQLReport extends DataReport {
 	protected $sql;
 	

forms/SelectionGroup.php

@@ -1,9 +1,16 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-structural
+ */
+
 /**
  * SelectionGroup represents a number of fields that are selectable by a radio button that appears at
  * the beginning of each item.  Using CSS, you can configure the field to only display its contents if
  * the corresponding radio button is selected.
+ * @package forms
+ * @subpackage fields-structural
  */
 class SelectionGroup extends CompositeField {
 	/**

forms/SimpleImageField.php

@@ -1,9 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-files
+ */
+
 /**
  * SimpleImageField provides an easy way of uploading images to Image has_one relationships.
  * Unlike ImageField, it doesn't use an iframe.
- *
+ * @package forms
+ * @subpackage fields-files
  */
 class SimpleImageField extends FileField {
   function saveInto(DataObject $record) {

forms/Tab.php

@@ -1,6 +1,14 @@
 <?php
+
 /**
- * Moved to seperate file for caching reasons 
+ * @package forms
+ * @subpackage fields-structural
+ */
+
+/**
+ * Implements a single tab in a {@link TabSet}.
+ * @package forms
+ * @subpackage fields-structural
  */
 class Tab extends CompositeField {
 	protected $tabSet;

forms/TabSet.php

@@ -1,12 +1,15 @@
 <?php
 /**
- * TabSet.php contains all of the classes used to build tabbed forms
+ * @package forms
+ * @subpackage fields-structural
  */
 
 /**
  * Defines a set of tabs in a form.
  * The tabs are build with our standard tabstrip javascript library.  By default, the HTML is
  * generated using FieldHolder.
+ * @package forms
+ * @subpackage fields-structural
  */
 class TabSet extends CompositeField {
 	public function __construct($id) {

forms/TableField.php

@@ -1,8 +1,8 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fields-relational
  */
 
 /**
@@ -26,7 +26,9 @@
  * @param $sourceSort string
  * @param $sourceJoin string
  * 
- * TODO We should refactor this to support a single FieldSet instead of evaluated Strings for building FormFields
+ * @todo We should refactor this to support a single FieldSet instead of evaluated Strings for building FormFields
+ * @package forms
+ * @subpackage fields-relational
  */
  
 class TableField extends TableListField {
@@ -596,8 +598,10 @@ JS;
 }
 
 /**
- * encapsulation object for the table field. it stores the dataobject, 
+ * Single record in a TableField.
- * and nessecary encapsulation fields
+ * @package forms
+ * @subpackage fields-relational
+ * @see TableField
  */ 
 class TableField_Item extends TableListField_Item {
 	

forms/TableListField.php

@@ -1,8 +1,8 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage fields-relational
  */
 
 /**
@@ -17,6 +17,8 @@
  * @param $sourceFilter string The filter field you wish to limit the objects by (eg. parentID)
  * @param $sourceSort string
  * @param $sourceJoin string
+ * @package forms
+ * @subpackage fields-relational
  */
 class TableListField extends FormField {
 	
@@ -1004,6 +1006,12 @@ JS
 	}
 }
 
+/**
+ * A single record in a TableListField.
+ * @package forms
+ * @subpackage fields-relational
+ * @see TableListField
+ */
 class TableListField_Item extends ViewableData {
 	protected $item, $parent;
 	

forms/TabularStyle.php

@@ -1,8 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage transformations
+ */
+
 /**
  * This is a form decorator (a class that wraps around a form) providing us with some functions
  * to display it in a Tabular style.
+ * @package forms
+ * @subpackage transformations
  */
 class TabularStyle extends Form {
 	protected $form;

forms/TextField.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-basic
+ */
+
 /**
  * Text input field.
+ * @package forms
+ * @subpackage fields-basic
  */
 class TextField extends FormField {
 	protected $maxLength;

forms/TextareaField.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-basic
+ */
+
 /**
  * Multi-line text area.
+ * @package forms
+ * @subpackage fields-basic
  */
 class TextareaField extends FormField {
 	protected $rows, $cols, $disabled = false, $readonly = false;

forms/TimeField.php

@@ -1,12 +1,16 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-datetime
+ */
+
 /**
  * Date field.
  * Default Value represented in the format passed as constructor.
  * 
- * @param name - The name of the field
+ * @package forms
- * @param title - The Title of the field
+ * @subpackage fields-datetime
- * @param value - the value for the field
- * @param format - The Time format in date php format e.g. G:ia
  */
 class TimeField extends TextField {
 	// Stores our time format;
@@ -15,6 +19,10 @@ class TimeField extends TextField {
 	/**
 	 * Constructor saves the format difference. Timefields shouldn't 
 	 * have a problem with length as times can only be represented in on way.
+	 * @param $name string The name of the field
+	 * @param $title string The Title of the field
+	 * @param $value string the value for the field
+	 * @param $timeformat string The Time format in date php format e.g. G:ia
 	 */
 	function __construct($name, $title = null, $value = "",$timeformat = "g:ia"){
 		parent::__construct($name,$title,$value);

forms/ToggleCompositeField.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-structural
+ */
+
 /**
  * Allows visibility of a group of fields to be toggled using '+' and '-' icons
+ * @package forms
+ * @subpackage fields-structural
  */
 class ToggleCompositeField extends CompositeField {
 	

forms/ToggleField.php

@@ -1,10 +1,17 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-dataless
+ */
+
 /**
  * ReadonlyField with added toggle-capabilities - will preview the first sentence of the contained text-value,
  * and show the full content by a javascript-switch.
  * 
  * Caution: Strips HTML-encoding for the preview.
+ * @package forms
+ * @subpackage fields-dataless
  */
 
 class ToggleField extends ReadonlyField {

forms/TreeDropdownField.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
+
+/**
+ * Dropdown-like field that gives you a tree of items, using ajax.
+ * @package forms
+ * @subpackage fields-relational
+ */
 class TreeDropdownField extends FormField {
 	protected $sourceObject, $keyField, $labelField, $filterFunc;
 	protected $treeBaseID = 0;

forms/TreeMultiselectField.php

@@ -1,8 +1,15 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
+
 /**
  * This formfield represents many-many joins using a tree selector shown in a dropdown styled element
  * which can be added to any form usually in the CMS. 
- *  
+ * @package forms
+ * @subpackage fields-relational
  */
 class TreeMultiselectField extends TreeDropdownField {
 	function __construct($name, $title, $sourceObject = "Group", $keyField = "ID", $labelField = "Title") {

forms/TreeSelectorField.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
+
+/**
+ * @deprecated Use {@link TreeDropdownField} or {@link TreeMultiselectField}
+ * @package forms
+ * @subpackage fields-relational
+ */
 class TreeSelectorField extends FormField {
 	protected $sourceObject;
 	

forms/TypeDropdown.php

@@ -1,6 +1,14 @@
 <?php
+
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
+
 /**
  * Create a dropdown from all instances of a class
+ * @package forms
+ * @subpackage fields-relational
  */
 class TypeDropdown extends DropdownField {
 	

forms/UniqueRestrictedTextField.php

@@ -1,8 +1,16 @@
 <?php
-	/**
+
-	 * Text field that automatically checks that the value entered is unique for the given
+/**
-	 * set of fields in a given set of tables
+ * @package forms
-	 */
+ * @subpackage fields-formattedinput
+ */
+
+/**
+ * Text field that automatically checks that the value entered is unique for the given
+ * set of fields in a given set of tables
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class UniqueRestrictedTextField extends UniqueTextField {
 	
 	protected $charRegex;

forms/UniqueTextField.php

@@ -1,8 +1,16 @@
 <?php
-	/**
+
-	 * Text field that automatically checks that the value entered is unique for the given
+/**
-	 * set of fields in a given set of tables
+ * @package forms
-	 */
+ * @subpackage fields-formattedinput
+ */
+
+/**
+ * Text field that automatically checks that the value entered is unique for the given
+ * set of fields in a given set of tables
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class UniqueTextField extends TextField {
 	
 	protected $restrictedField;

forms/Validator.php

@@ -1,8 +1,8 @@
 <?php
 
 /**
- * @package sapphire
+ * @package forms
- * @subpackage forms
+ * @subpackage validators
  */
 
 /**
@@ -14,8 +14,9 @@
  * FormResponse if the request was made by ajax.
  * 
  * @example forms/Form.php See how you can create a form on your controller.
- */
+ * @package forms
- 
+ * @subpackage validators
+ */ 
 abstract class Validator extends Object {
 	protected $form;
 	protected $errors;

forms/editor/FieldEditor.php

@@ -1,8 +1,15 @@
 <?php
-	/**
+
-	 * FieldEditor
+/**
-	 * Allows CMS user to create forms dynamically
+ * @package forms
-	 */
+ * @subpackage fieldeditor
+ */
+
+/**
+ * Allows CMS user to create forms dynamically.
+ * @package forms
+ * @subpackage fieldeditor
+ */
 class FieldEditor extends FormField {
 	
 	protected $readonly = false;

integration/XML.php

@@ -7,6 +7,8 @@
 
 /**
  * Base class for XML parsers
+ * @package sapphire
+ * @subpackage misc
  */
 class XML extends Object {
 	protected $parser;

main.php

@@ -1,10 +1,40 @@
 <?php
 
 /**
- * Main file that handles every page request.  .htaccess must be configured to send all requests to main.php
+ * Main file that handles every page request.
+ *
+ * The main.php does a number of set-up activities for the request.
+ * 
+ *  - Includes the first one of the following files that it finds: (root)/_ss_environment.php, (root)/../_ss_environment.php, or (root)/../../_ss_environment.php
+ *  - Gets an up-to-date manifest from {@link ManifestBuilder}
+ *  - Sets up error handlers with {@link Debug::loadErrorHandlers()}
+ *  - Calls {@link DB::connect()}, passing it the global variable $databaseConfig that should be defined in an _config.php
+ *  - Sets up the default director rules using {@link Director::addRules()}
+ * 
+ * After that, it calls {@link Director::direct()}, which is responsible for doing most of the real work.
+ *
+ * Finally, main.php will use {@link Profiler} to show a profile if the querystring variable "debug_profile" is set.
+ *
+ * CONFIGURING THE WEBSERVER
+ *
+ * To use Sapphire, every request that doesn't point directly to a file should be rewritten to sapphire/main.php?url=(url).
+ * For example, http://www.example.com/about-us/rss would be rewritten to http://www.example.com/sapphire/main.php?url=about-us/rss
+ *
+ * It's important that requests that point directly to a file aren't rewritten; otherwise, visitors won't be able to download
+ * any CSS, JS, image files, or other downloads.
+ *
+ * On Apache, RewriteEngine can be used to do this.
+ *
+ * @package sapphire
+ * @subpackage core
+ * @see Director::direct()
  */
 
+/**
+ * Include Sapphire's core code
+ */
 require_once("core/Core.php");
+
 header("Content-type: text/html; charset=\"utf-8\"");
 if(function_exists('mb_http_output')) {
 	mb_http_output('UTF-8');

main.php5

@@ -1,3 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage core
+ * Alternative main.php file for servers that need the php5 extension
+ */
+
 include("main.php");
 ?>

misc/Browscap.php

@@ -29,6 +29,8 @@
  * @version    0.7
  * @license    http://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License
  * @link       http://garetjax.info/projects/browscap/
+ * @package sapphire
+ * @subpackage misc
  */
 class Browscap
 {

misc/GoogleSitemap.php

@@ -9,6 +9,8 @@
  * Initial implementation of Sitemap support.
  * GoogleSitemap should handle requests to 'sitemap.xml'
  * the other two classes are used to render the sitemap
+ * @package sapphire
+ * @subpackage misc
  */
 class GoogleSitemap extends Controller {
 	protected $Pages;

misc/IPS.php

@@ -7,6 +7,8 @@
 
 /**
  * Ioncube Performance Suite management
+ * @package sapphire
+ * @subpackage misc
  */
 class IPS extends Controller {
 	function index() {

misc/Statistics.php

@@ -7,6 +7,7 @@
 /**
  * Statistics class for gathering and formatting of statistical data for tables and charts in
  * both public and administrative contexts.
+ * @package cms
  */
 
 class Statistics extends Controller {

parsers/BBCodeParser.php

@@ -5,6 +5,9 @@
  * @subpackage misc
  */
 
+/**
+ *
+ */
 require_once('HTML/HTMLBBCodeParser.php');
 /*Seting up the PEAR bbcode parser*/  
 $config = parse_ini_file('BBCodeParser.ini', true);
@@ -17,6 +20,8 @@ unset($options);
 /**
  * BBCode parser object.
  * Use on a text field in a template with $Content.Parse(BBCodeParser).
+ * @package sapphire
+ * @subpackage misc
  */
 class BBCodeParser extends TextParser {
 

parsers/TextParser.php

@@ -27,7 +27,9 @@
  * This will (mostly) be used to create helper blocks - telling users what things will be parsed.
  * Again, @see BBCodeParser for an example of the syntax
  * 
- * TODO Define a proper syntax for (or refactor) usable_tags that can be extended as needed.
+ * @todo Define a proper syntax for (or refactor) usable_tags that can be extended as needed.
+ * @package sapphire
+ * @subpackage misc
  */
 abstract class TextParser extends Object {
 	protected $content;

profiler/Profiler.php

@@ -15,6 +15,8 @@
 
 /**
  * Execution time profiler.
+ * @package sapphire
+ * @subpackage misc
  */
 class Profiler {
     var $description;

search/AdvancedSearchForm.php

@@ -7,6 +7,8 @@
 
 /**
  * More advanced search form
+ * @package sapphire
+ * @subpackage search
  */
 class AdvancedSearchForm extends SearchForm {
 	

search/SearchForm.php

@@ -7,6 +7,8 @@
 
 /**
  * Standard basic search form
+ * @package sapphire
+ * @subpackage search
  */
 class SearchForm extends Form {
 	

security/Authenticator.php

@@ -12,6 +12,8 @@
  * methods like {@link MemberAuthenticator} or {@link OpenIDAuthenticator}.
  *
  * @author Markus Lanthaler <markus@silverstripe.com>
+ * @package sapphire
+ * @subpackage security
  */
 abstract class Authenticator extends Object {
 

security/BasicAuth.php

@@ -7,6 +7,8 @@
 
 /**
  * Provides an interface to HTTP basic authentication.
+ * @package sapphire
+ * @subpackage security
  */
 class BasicAuth extends Object {
 	/**

security/ChangePasswordForm.php

@@ -7,6 +7,8 @@
 
 /**
  * Standard Change Password Form
+ * @package sapphire
+ * @subpackage security
  */
 class ChangePasswordForm extends Form {
 

security/Geoip.php

@@ -5,23 +5,19 @@
  * @subpackage misc
  */
 
-/* Geoip.php 
-
- Known to work with the following versions of GeoIP:
- - GEO-106FREE 20030401 Build 1 Copyright (c) 2003 MaxMind.com All Rights Reserved
- - GEO-106FREE 20030803 Build 1 Copyright (c) 2003 MaxMind LLC All Rights Reserved
-
- Routines for DNS to country resolution;
 
+/**
+ * Routines for DNS to country resolution
+ * 
+ *  - convert address (either ip or domainname) to country.
+ *  - returns false if IP address not found / not known;
+ *  - otherwise an array 
+ *  - set $codeOnly to true if you just want the country code
+ *  - give a default for IP
+ *
+ * @package sapphire
+ * @subpackage misc
  */
-
-// convert address (either ip or domainname) to country.
-
-// returns false if IP address not found / not known;
-// otherwise an array 
-// set $codeOnly to true if you just want the country code
-// give a default for IP/
-
 class Geoip extends Object {
 	
 	public static $default_country_code = false;

security/Group.php

@@ -7,6 +7,8 @@
 
 /**
  * A security group.
+ * @package sapphire
+ * @subpackage security
  */
 class Group extends DataObject {
 	// This breaks too many things for upgraded sites

security/LoginForm.php

@@ -13,6 +13,8 @@
  * {@link MemberLoginForm} or {@link OpenIDLoginForm}.
  *
  * @author Markus Lanthaler <markus@silverstripe.com>
+ * @package sapphire
+ * @subpackage security
  */
 abstract class LoginForm extends Form {
 	function __construct($controller, $name, $fields, $actions) {

security/Member.php

@@ -8,6 +8,8 @@
 
 /**
  * The member class which represents the users of the system
+ * @package sapphire
+ * @subpackage security
  */
 class Member extends DataObject {
 

security/MemberAuthenticator.php

@@ -10,6 +10,8 @@
  * Authenticator for the default "member" method
  *
  * @author Markus Lanthaler <markus@silverstripe.com>
+ * @package sapphire
+ * @subpackage security
  */
 class MemberAuthenticator extends Authenticator {
 

security/MemberLoginForm.php

@@ -7,6 +7,8 @@
 
 /**
  * Log-in form for the "member" authentication method
+ * @package sapphire
+ * @subpackage security
  */
 class MemberLoginForm extends LoginForm {
 

security/Permission.php

@@ -7,6 +7,8 @@
 
 /**
  * Represents a permission assigned to a group.
+ * @package sapphire
+ * @subpackage security
  */
 class Permission extends DataObject {
 

security/PermissionDropdownField.php

@@ -9,8 +9,9 @@
  * Special kind of dropdown field that has all permission codes as its dropdown source.
  * Note: This would ordinarily be overkill; the main reason we have it is that TableField doesn't let you specify a dropdown source;
  * only a classname
+ * @package sapphire
+ * @subpackage security
  */
-
 class PermissionDropdownField extends DropdownField {
 	function __construct($name, $title = "") {
 		parent::__construct($name, $title, Permission::get_codes(true)); 

security/PermissionProvider.php

@@ -8,6 +8,8 @@
 /**
  * Used to let classes provide new permission codes.
  * Every implementor of PermissionProvider is accessed and providePermissions() called to get the full list of permission codes.
+ * @package sapphire
+ * @subpackage security
  */
 interface PermissionProvider {
 	/**

security/Security.php

@@ -7,6 +7,8 @@
 
 /**
  * Implements a basic security model
+ * @package sapphire
+ * @subpackage security
  */
 class Security extends Controller {
 
@@ -848,4 +850,4 @@ class Security extends Controller {
 }
 
 
-?>
+?>

synchronise/Synchronise.php

@@ -7,6 +7,8 @@
 
 /**
  * Synchroniser controller - used to let two servers communicate
+ * @package sapphire
+ * @subpackage synchronisation
  */
 class Synchronise extends Controller {
 	

synchronise/Synchronised.php

@@ -8,6 +8,8 @@
 /**
  * Functions to provide synchronisation between two Silverstripe implementations. This allows the same entry to have two different
  * IDs on each installation
+ * @package sapphire
+ * @subpackage synchronisation
  */
 class Synchronised extends DataObjectDecorator {
 

tests/InstallerTest.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
+/**
+ * Simple controller that the installer uses to test that URL rewriting is working.
+ * @package sapphire
+ * @subpackage misc
+ */
 class InstallerTest extends Controller {
 	function testRewrite() {
 		echo "OK";

tests/TestRunner.php

@@ -14,11 +14,15 @@ foreach($paths as $path) {
 
 if($hasPhpUnit) {
 
+/**
+ */
 require_once 'PHPUnit/Framework.php';
 require_once 'PHPUnit/TextUI/TestRunner.php';
 
 /**
  * Controller that executes PHPUnit tests
+ * @package sapphire
+ * @subpackage testing
  */
 class TestRunner extends Controller {
 	/**
@@ -64,6 +68,9 @@ class TestRunner extends Controller {
 
 } else {
 
+/**
+ * @ignore
+ */
 class TestRunner extends Controller {
 	function index() {
 		echo "Please install PHPUnit using pear.";

widgets/Widget.php

@@ -8,6 +8,8 @@
 /**
  * Base class for widgets.
  * Widgets let CMS authors drag and drop small pieces of functionality into defined areas of their websites.
+ * @package sapphire
+ * @subpackage widgets
  */
 class Widget extends DataObject {
 	static $db = array(

widgets/WidgetArea.php

@@ -2,11 +2,13 @@
 
 /**
  * @package sapphire
- * @subpackage synchronisation
+ * @subpackage widgets
  */
 
 /**
  * Represents a set of widgets shown on a page.
+ * @package sapphire
+ * @subpackage widgets
  */
 class WidgetArea extends DataObject {
 	static $db = array();