Merge pull request #1962 from wilr/api-links

Update @package, @subpackage labels

admin/code/LeftAndMain.php

@@ -6,8 +6,8 @@
  * This is essentially an abstract class which should be subclassed.
  * See {@link CMSMain} for a good example.
  * 
- * @package cms
+ * @package framework
- * @subpackage core
+ * @subpackage admin
  */
 class LeftAndMain extends Controller implements PermissionProvider {
 	
@@ -1769,6 +1769,9 @@ class LeftAndMainMarkingFilter {
 
 /**
  * Allow overriding finished state for faux redirects.
+ *
+ * @package framework
+ * @subpackage admin
  */
 class LeftAndMain_HTTPResponse extends SS_HTTPResponse {
 
@@ -1788,7 +1791,10 @@ class LeftAndMain_HTTPResponse extends SS_HTTPResponse {
  * Wrapper around objects being displayed in a tree.
  * Caution: Volatile API.
  *
- * @todo Implement recursive tree node rendering
+ * @todo Implement recursive tree node rendering.
+ *
+ * @package framework
+ * @subpackage admin
  */
 class LeftAndMain_TreeNode extends ViewableData {
 	

admin/code/LeftAndMainExtension.php

@@ -2,8 +2,8 @@
 /**
  * Plug-ins for additional functionality in your LeftAndMain classes.
  * 
- * @package    cms
+ * @package framework
- * @subpackage core
+ * @subpackage admin
  */
 abstract class LeftAndMainExtension extends Extension {
 

admin/code/ModelAdmin.php

@@ -26,8 +26,8 @@
  * 
  * @uses SearchContext
  * 
- * @package cms
+ * @package framework
- * @subpackage core
+ * @subpackage admin
  */
 abstract class ModelAdmin extends LeftAndMain {
 

control/PjaxResponseNegotiator.php

@@ -1,14 +1,21 @@
 <?php
 /**
  * Handle the X-Pjax header that AJAX responses may provide, returning the 
- * fragment, or, in the case of non-AJAX form submissions, redirecting back to the submitter.
+ * fragment, or, in the case of non-AJAX form submissions, redirecting back 
+ * to the submitter.
+ *
+ * X-Pjax ensures that users won't end up seeing the unstyled form HTML in 
+ * their browser.
+ *
+ * If a JS error prevents the Ajax overriding of form submissions from happening.
  *
- * X-Pjax ensures that users won't end up seeing the unstyled form HTML in their browser
- * If a JS error prevents the Ajax overriding of form submissions from happening. 
  * It also provides better non-JS operation.
  * 
  * Caution: This API is volatile, and might eventually be replaced by a generic
  * action helper system for controllers.
+ *
+ * @package framework 
+ * @subpackage control
  */
 class PjaxResponseNegotiator {
 

control/RequestProcessor.php

@@ -1,10 +1,8 @@
 <?php
 
 /**
- * Description of RequestProcessor
+ * @package framework
- *
+ * @subpackage control
- * @author marcus@silverstripe.com.au
- * @license BSD License http://silverstripe.org/bsd-license/
  */
 class RequestProcessor {
 

control/injector/AopProxyService.php

@@ -2,13 +2,10 @@
 
 /**
  * A class that proxies another, allowing various functionality to be
- * injected
+ * injected.
  * 
- * @author marcus@silverstripe.com.au
  * @package framework
  * @subpackage injector
- * 
- * @license http://silverstripe.org/bsd-license/
  */
 class AopProxyService {
 	public $beforeCall = array();

control/injector/BeforeCallAspect.php

@@ -1,15 +1,13 @@
 <?php
 
 /**
- * A BeforeCallAspect is run before a method is executed
+ * A BeforeCallAspect is run before a method is executed.
  *
  * This is a declared interface, but isn't actually required
  * as PHP doesn't really care about types... 
  * 
- * @author Marcus Nyeholt <marcus@silverstripe.com.au>
  * @package framework
  * @subpackage injector
- * @license BSD http://silverstripe.org/BSD-license
  */
 interface BeforeCallAspect {
 	

control/injector/InjectionCreator.php

@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * A class for creating new objects by the injector.
+ *
+ * @package framework
+ * @subpackage injector
+ */
+class InjectionCreator {
+
+	/**
+	 * @param string $object
+	 *					A string representation of the class to create
+	 * @param array $params
+	 *					An array of parameters to be passed to the constructor
+	 */
+	public function create($class, $params = array()) {
+		$reflector = new ReflectionClass($class);
+
+		if (count($params)) {
+			return $reflector->newInstanceArgs($params); 
+		}
+		
+		return $reflector->newInstance();
+	}
+}

control/injector/ServiceConfigurationLocator.php

@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * Used to locate configuration for a particular named service. 
+ * 
+ * If it isn't found, return null.
+ *
+ * @package framework
+ * @subpackage injector
+ */
+class ServiceConfigurationLocator {
+	public function locateConfigFor($name) {
+		
+	}
+}

control/injector/SilverStripeInjectonCreator.php

@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * @package framework
+ * @subpackage injector
+ */
+
+class SilverStripeInjectionCreator {
+	/**
+	 *
+	 * @param string $object
+	 *					A string representation of the class to create
+	 * @param array $params
+	 *					An array of parameters to be passed to the constructor
+	 */
+	public function create($class, $params = array()) {
+		$class = Object::getCustomClass($class);
+		$reflector = new ReflectionClass($class);
+		
+		return $reflector->newInstanceArgs($params);
+	}
+}

control/injector/SilverStripeServiceConfigurationLocator.php

@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * Use the SilverStripe configuration system to lookup config for a 
+ * particular service.
+ *
+ * @package framework
+ * @subpackage injector
+ */
+class SilverStripeServiceConfigurationLocator {
+	
+	private $configs = array();
+	
+	public function locateConfigFor($name) {
+		
+		if (isset($this->configs[$name])) {
+			return $this->configs[$name];
+		}
+		
+		$config = Config::inst()->get('Injector', $name);
+		if ($config) {
+			$this->configs[$name] = $config;
+			return $config;
+		}
+		
+		// do parent lookup if it's a class
+		if (class_exists($name)) {
+			$parents = array_reverse(array_keys(ClassInfo::ancestry($name)));
+			array_shift($parents);
+			foreach ($parents as $parent) {
+				// have we already got for this? 
+				if (isset($this->configs[$parent])) {
+					return $this->configs[$parent];
+				}
+				$config = Config::inst()->get('Injector', $parent);
+				if ($config) {
+					$this->configs[$name] = $config;
+					return $config;
+				} else {
+					$this->configs[$parent] = false;
+				}
+			}
+			
+			// there is no parent config, so we'll record that as false so we don't do the expensive
+			// lookup through parents again
+			$this->configs[$name] = false;
+		}
+	}
+}

core/Config.php

@@ -10,166 +10,215 @@
  * - An array
  * - A non-array value
  *
- * If the value is an array, each value in the array may also be one of those three types
+ * If the value is an array, each value in the array may also be one of those 
+ * three types.
  *
- * A property can have a value specified in multiple locations, each of which have a hardcoded or explicit priority.
+ * A property can have a value specified in multiple locations, each of which 
- * We combine all these values together into a "composite" value using rules that depend on the priority order of the
+ * have a hard coded or explicit priority. We combine all these values together 
- * locations to give the final value, using these rules:
+ * into a "composite" value using rules that depend on the priority order of 
+ * the locations to give the final value, using these rules:
  *
- * - If the value is an array, each array is added to the _beginning_ of the composite array in ascending priority
+ * - If the value is an array, each array is added to the _beginning_ of the 
- *   order. If a higher priority item has a non-integer key which is the same as a lower priority item, the value of
+ *	composite array in ascending priority order. If a higher priority item has 
- *   those items  is merged using these same rules, and the result of the merge is located in the same location the
+ *	a non-integer key which is the same as a lower priority item, the value of
- *   higher priority item would be if there was no key clash. Other than in this key-clash situation, within the
+ * 	those items  is merged using these same rules, and the result of the merge 
- *   particular array, order is preserved.
+ *	is located in the same location the higher priority item would be if there 
+ *	was no key clash. Other than in this key-clash situation, within the
+ * 	particular array, order is preserved.
  *
- * - If the value is not an array, the highest priority value is used without any attempt to merge
+ * - If the value is not an array, the highest priority value is used without 
+ *	any attempt to merge.
  *
- * It is an error to have mixed types of the same named property in different locations (but an error will not
+ * It is an error to have mixed types of the same named property in different 
- * necessarily be raised due to optimisations in the lookup code)
+ * locations (but an error will not necessarily be raised due to optimizations 
+ * in the lookup code).
  *
- * The exception to this is "false-ish" values - empty arrays, empty strings, etc. When merging a non-false-ish value
+ * The exception to this is "false-ish" values - empty arrays, empty strings, 
- * with a false-ish value, the result will be the non-false-ish value regardless of priority. When merging two
+ * etc. When merging a non-false-ish value with a false-ish value, the result 
+ * will be the non-false-ish value regardless of priority. When merging two
  * false-ish values the result will be the higher priority false-ish value.
  *
- * The locations that configuration values are taken from in highest -> lowest priority order
+ * The locations that configuration values are taken from in highest -> lowest 
+ * priority order.
  *
- * - Any values set via a call to Config#update
+ * - Any values set via a call to Config#update.
  *
- * - The configuration values taken from the YAML files in _config directories (internally sorted in before / after
+ * - The configuration values taken from the YAML files in _config directories 
- *   order, where the item that is latest is highest priority)
+ *	(internally sorted in before / after order, where the item that is latest 
+ *	is highest priority).
  *
- * - Any static set on an "additional static source" class (such as an extension) named the same as the name of the
+ * - Any static set on an "additional static source" class (such as an 
- *   property
+ *	extension) named the same as the name of the property.
  *
- * - Any static set on the class named the same as the name of the property
+ * - Any static set on the class named the same as the name of the property.
  *
- * - The composite configuration value of the parent class of this class
+ * - The composite configuration value of the parent class of this class.
  *
- * At some of these levels you can also set masks. These remove values from the composite value at their priority
+ * At some of these levels you can also set masks. These remove values from the 
- * point rather than add. They are much simpler. They consist of a list of key / value pairs. When applied against the
+ * composite value at their priority point rather than add. They are much 
- * current composite value:
+ * simpler. They consist of a list of key / value pairs. When applied against 
+ * the current composite value:
  *
- * - If the composite value is a sequential array, any member of that array that matches any value in the mask is
+ * - If the composite value is a sequential array, any member of that array 
- *   removed
+ *	that matches any value in the mask is removed.
  *
- * - If the composite value is an associative array, any member of that array that matches both the key and value of
+ * - If the composite value is an associative array, any member of that array 
- *   any pair in the mask is removed
+ *	that matches both the key and value of any pair in the mask is removed.
  *
- * - If the composite value is not an array, if that value matches any value in the mask it is removed
+ * - If the composite value is not an array, if that value matches any value 
+ * in the mask it is removed.
+ *
+ * @package framework
+ * @subpackage core
  */
 class Config {
 
 	/**
-	 * [A marker instance for the "anything" singleton value. Don't access directly, even in-class, always use
+	 * A marker instance for the "anything" singleton value. Don't access 
-	 * self::anything()
+	 * directly, even in-class, always use self::anything()
+	 *
 	 * @var Object
 	 */
-	static private $_anything = null;
+	private static $_anything = null;
 
 	/**
-	 * Get a marker class instance that is used to do a "remove anything with this key" by adding
+	 * Get a marker class instance that is used to do a "remove anything with 
-	 * $key => Config::anything() to the suppress array
+	 * this key" by adding $key => Config::anything() to the suppress array
 	 * 
-	 * @todo Does this follow the SS coding conventions? Config::get_anything_marker_instance() is a lot less elegant.
 	 * @return Object
 	 */
-	static public function anything() {
+	public static function anything() {
-		if (self::$_anything === null) self::$_anything = new stdClass();
+		if (self::$_anything === null) {
+			self::$_anything = new stdClass();
+		}
+
 		return self::$_anything;
 	}
 
 	// -- Source options bitmask --
 
 	/**
-	 * source options bitmask value - merge all parent configuration in as lowest priority
+	 * source options bitmask value - merge all parent configuration in as 
+	 * lowest priority.
+	 *
 	 * @const
 	 */
 	const INHERITED = 0;
+
 	/**
-	 * source options bitmask value - only get configuration set for this specific class, not any of it's parents
+	 * source options bitmask value - only get configuration set for this 
+	 * specific class, not any of it's parents.
+	 *
 	 * @const
 	 */
 	const UNINHERITED = 1;
+
 	/**
-	 * source options bitmask value - inherit, but stop on the first class that actually provides a value (event an
+	 * source options bitmask value - inherit, but stop on the first class 
-	 * empty value)
+	 * that actually provides a value (event an empty value).
+	 *
 	 * @const
 	 */
 	const FIRST_SET = 2;
-	/** @const source options bitmask value - do not use additional statics sources (such as extension) */
+
+	/** 
+	 * @const source options bitmask value - do not use additional statics 
+	 * sources (such as extension) 
+	 */
 	const EXCLUDE_EXTRA_SOURCES = 4;
 
 	// -- get_value_type response enum --
 
 	/**
-	 * Return flag for get_value_type indicating value is a scalar (or really just not-an-array, at least ATM)
+	 * Return flag for get_value_type indicating value is a scalar (or really 
+	 * just not-an-array, at least ATM)
+	 *
 	 * @const
 	 */
 	const ISNT_ARRAY = 1;
+
 	/**
-	 * Return flag for get_value_type indicating value is an array
+	 * Return flag for get_value_type indicating value is an array.
 	 * @const
 	 */
 	const IS_ARRAY = 2;
 
 	/**
-	 * Get whether the value is an array or not. Used to be more complicated, but still nice sugar to have an enum
+	 * Get whether the value is an array or not. Used to be more complicated, 
-	 * to compare and not just a true/false value
+	 * but still nice sugar to have an enum to compare and not just a true /
+	 * false value.
+	 *
 	 * @param $val any - The value
+	 *
 	 * @return int - One of ISNT_ARRAY or IS_ARRAY
 	 */
-	static protected function get_value_type($val) {
+	protected static function get_value_type($val) {
-		if (is_array($val)) return self::IS_ARRAY;
+		if (is_array($val)) {
+			return self::IS_ARRAY;
+		}
+
 		return self::ISNT_ARRAY;
 	}
 
 	/**
-	 * What to do if there's a type mismatch
+	 * What to do if there's a type mismatch.
+	 *
 	 * @throws UnexpectedValueException
 	 */
-	static protected function type_mismatch() {
+	protected static function type_mismatch() {
 		throw new UnexpectedValueException('Type mismatch in configuration. All values for a particular property must'
 			. ' contain the same type (or no value at all).');
 	}
 
-	/* @todo If we can, replace next static & static methods with DI once that's in */
+	/**
-	static protected $instance;
+	 * @todo If we can, replace next static & static methods with DI once that's in 
+	 */
+	protected static $instance;
 
 	/**
 	 * Get the current active Config instance.
 	 *
 	 * Configs should not normally be manually created.
-	 * In general use you will use this method to obtain the current Config instance.
+	 *
+	 * In general use you will use this method to obtain the current Config 
+	 * instance.
 	 *
 	 * @return Config
 	 */
-	static public function inst() {
+	public static function inst() {
-		if (!self::$instance) self::$instance = new Config();
+		if (!self::$instance) {
+			self::$instance = new Config();
+		}
+
 		return self::$instance;
 	}
 
 	/**
-	 * Set the current active Config instance.
+	 * Set the current active {@link Config} instance.
 	 *
-	 * Configs should not normally be manually created.
+	 * {@link Config} objects should not normally be manually created.
-	 * A use case for replacing the active configuration set would be for creating an isolated environment for
+	 *
-	 * unit tests
+	 * A use case for replacing the active configuration set would be for 
+	 * creating an isolated environment for unit tests.
 	 *
 	 * @return Config
 	 */
-	static public function set_instance($instance) {
+	public static function set_instance($instance) {
 		self::$instance = $instance;
+
 		global $_SINGLETONS;
 		$_SINGLETONS['Config'] = $instance;
 	}
 
 	/**
-	 * Make the newly active Config be a copy of the current active Config instance.
+	 * Make the newly active {@link Config} be a copy of the current active 
+	 * {@link Config} instance.
 	 *
-	 * You can then make changes to the configuration by calling update and remove on the new
+	 * You can then make changes to the configuration by calling update and 
-	 * value returned by Config::inst(), and then discard those changes later by calling unnest
+	 * remove on the new value returned by Config::inst(), and then discard 
+	 * those changes later by calling unnest.
 	 */
-	static public function nest() {
+	public static function nest() {
 		$current = self::$instance;
 
 		$new = clone $current;
@@ -178,17 +227,21 @@ class Config {
 	}
 
 	/**
-	 * Change the active Config back to the Config instance the current active Config object
+	 * Change the active Config back to the Config instance the current active 
-	 * was copied from
+	 * Config object was copied from.
 	 */
-	static public function unnest() {
+	public static function unnest() {
 		self::set_instance(self::$instance->nestedFrom);
 	}
 
+	/**
+	 * @var array
+	 */
 	protected $cache;
 
 	/**
-	 * Each copy of the Config object need's it's own cache, so changes don't leak through to other instances
+	 * Each copy of the Config object need's it's own cache, so changes don't 
+	 * leak through to other instances.
 	 */
 	public function __construct() {
 		$this->cache = new Config_LRU();
@@ -198,21 +251,37 @@ class Config {
 		$this->cache = clone $this->cache;
 	}
 
-	/** @var Config - The config instance this one was copied from when Config::nest() was called */
+	/** 
+	 * @var Config - The config instance this one was copied from when 
+	 * Config::nest() was called.
+	 */
 	protected $nestedFrom = null;
 
-	/** @var [array] - Array of arrays. Each member is an nested array keyed as $class => $name => $value,
+	/** 
-	 * where value is a config value to treat as the highest priority item */
+	 * @var array - Array of arrays. Each member is an nested array keyed as 
+	 * $class => $name => $value, where value is a config value to treat as 
+	 * the highest priority item.
+	 */
 	protected $overrides = array();
 
-	/** @var [array] - Array of arrays. Each member is an nested array keyed as $class => $name => $value,
+	/** 
-	 * where value is a config value suppress from any lower priority item */
+	 * @var array $suppresses Array of arrays. Each member is an nested array 
+	 * keyed as $class => $name => $value, where value is a config value suppress 
+	 * from any lower priority item.
+	 */
 	protected $suppresses = array();
 
+	/**
+	 * @var array
+	 */
 	protected $staticManifests = array();
 
+	/**
+	 * @param SS_ConfigStaticManifest
+	 */
 	public function pushConfigStaticManifest(SS_ConfigStaticManifest $manifest) {
 		array_unshift($this->staticManifests, $manifest);
+		
 		$this->cache->clean();
 	}
 
@@ -596,6 +665,10 @@ class Config {
 
 }
 
+/**
+ * @package framework
+ * @subpackage core
+ */
 class Config_LRU {
 	const SIZE = 1000;
 
@@ -701,25 +774,54 @@ class Config_LRU {
 	}
 }
 
+/**
+ * @package framework
+ * @subpackage core
+ */
 class Config_ForClass {
+
+	/**
+	 * @var string $class
+	 */
 	protected $class;
 
+	/**
+	 * @param string $class
+	 */
 	public function __construct($class) {
 		$this->class = $class;
 	}
 
+	/**
+	 * @param string $name
+	 */
 	public function __get($name) {
 		return Config::inst()->get($this->class, $name);
 	}
 
+	/**
+	 * @param string $name
+	 * @param mixed $val
+	 */
 	public function __set($name, $val) {
 		return Config::inst()->update($this->class, $name, $val);
 	}
 
+	/**
+	 * @param string $name
+	 * @param int $sourceOptions
+	 *
+	 * @return array|scalar
+	 */
 	public function get($name, $sourceOptions = 0) {
 		return Config::inst()->get($this->class, $name, $sourceOptions);
 	}
 
+	/**
+	 * @param string
+	 *
+	 * @return Config_ForClass
+	 */
 	public function forClass($class) {
 		return Config::inst()->forClass($class);
 	}

forms/gridfield/GridField.php

@@ -16,7 +16,7 @@
  * @see SS_List
  * 
  * @package framework
- * @subpackage fields-relational
+ * @subpackage fields-gridfield
  */
 class GridField extends FormField {
 	
@@ -761,12 +761,11 @@ class GridField extends FormField {
 
 
 /**
- * This class is the base class when you want to have an action that alters the state of the gridfield,
+ * This class is the base class when you want to have an action that alters 
- * rendered as a button element. 
+ * the state of the {@link GridField}, rendered as a button element. 
  * 
  * @package framework
- * @subpackage forms
+ * @subpackage fields-gridfield
- * 
  */
 class GridField_FormAction extends FormAction {
 

forms/gridfield/GridFieldAddExistingAutocompleter.php

@@ -1,14 +1,25 @@
 <?php
 /**
- * This class is is responsible for adding objects to another object's has_many and many_many relation,
+ * This class is is responsible for adding objects to another object's has_many 
- * as defined by the {@link RelationList} passed to the GridField constructor.
+ * and many_many relation, as defined by the {@link RelationList} passed to the 
- * Objects can be searched through an input field (partially matching one or more fields).
+ * {@link GridField} constructor.
+ *
+ * Objects can be searched through an input field (partially matching one or 
+ * more fields).
+ *
  * Selecting from the results will add the object to the relation.
- * Often used alongside {@link GridFieldDeleteAction} for detaching existing records from a relatinship.
+ *
- * For easier setup, have a look at a sample configuration in {@link GridFieldConfig_RelationEditor}.
+ * Often used alongside {@link GridFieldDeleteAction} for detaching existing 
+ * records from a relationship.
+ *
+ * For easier setup, have a look at a sample configuration in 
+ * {@link GridFieldConfig_RelationEditor}.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
-class GridFieldAddExistingAutocompleter
+class GridFieldAddExistingAutocompleter 
-		implements GridField_HTMLProvider, GridField_ActionProvider, GridField_DataManipulator, GridField_URLHandler {
+	implements GridField_HTMLProvider, GridField_ActionProvider, GridField_DataManipulator, GridField_URLHandler {
 	
 	/**
 	 * Which template to use for rendering

forms/gridfield/GridFieldAddNewButton.php

@@ -1,10 +1,13 @@
 <?php
 /**
- * This component provides a button for opening the add new form provided by {@link GridFieldDetailForm}.
+ * This component provides a button for opening the add new form provided by 
- * Only returns a button if {@link DataObject->canCreate()} for this record returns true.
+ * {@link GridFieldDetailForm}.
+ *
+ * Only returns a button if {@link DataObject->canCreate()} for this record 
+ * returns true.
  *
  * @package framework
- * @subpackage gridfield
+ * @subpackage fields-gridfield
  */
 class GridFieldAddNewButton implements GridField_HTMLProvider {
 
@@ -14,6 +17,7 @@ class GridFieldAddNewButton implements GridField_HTMLProvider {
 
 	public function setButtonName($name) {
 		$this->buttonName = $name;
+
 		return $this;
 	}
 
@@ -23,7 +27,10 @@ class GridFieldAddNewButton implements GridField_HTMLProvider {
 
 	public function getHTMLFragments($gridField) {
 		$singleton = singleton($gridField->getModelClass());
-		if(!$singleton->canCreate()) return array();
+
+		if(!$singleton->canCreate()) {
+			return array();
+		}
 
 		if(!$this->buttonName) {
 			// provide a default button name, can be changed by calling {@link setButtonName()} on this component

forms/gridfield/GridFieldButtonRow.php

@@ -1,14 +1,18 @@
 <?php
 /**
- * Adding this class to a {@link GridFieldConfig} of a {@link GridField} adds a buttonrow to that field.
+ * Adding this class to a {@link GridFieldConfig} of a {@link GridField} adds 
+ * a button row to that field.
+ * 
  * The button row provides a space for actions on this grid.
  * 
- * This row provides two new HTML fragment spaces: 'toolbar-header-left' and 'toolbar-header-right'.
+ * This row provides two new HTML fragment spaces: 'toolbar-header-left' and 
+ * 'toolbar-header-right'.
  *
  * @package framework
- * @subpackage gridfield
+ * @subpackage fields-gridfield
  */
 class GridFieldButtonRow implements GridField_HTMLProvider {
+
 	protected $targetFragment;
 	
 	public function __construct($targetFragment = 'before') {
@@ -20,6 +24,7 @@ class GridFieldButtonRow implements GridField_HTMLProvider {
 			"LeftFragment" => "\$DefineFragment(buttons-{$this->targetFragment}-left)",
 			"RightFragment" => "\$DefineFragment(buttons-{$this->targetFragment}-right)",
 		));
+		
 		return array(
 			$this->targetFragment => $data->renderWith('GridFieldButtonRow')
 		);

forms/gridfield/GridFieldComponent.php

@@ -1,42 +1,58 @@
 <?php
 
 /**
- * Base interface for all components that can be added to GridField. 
+ * Base interface for all components that can be added to GridField.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 interface GridFieldComponent {	
 }
 
 /**
- * A GridField manipulator that provides HTML for the header/footer rows, or for before/after the template 
+ * A GridField manipulator that provides HTML for the header/footer rows, or f
+ * or before/after the template.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 interface GridField_HTMLProvider extends GridFieldComponent {
 	
 	/**
-	 * Returns a map where the keys are fragment names and the values are pieces of HTML to add to these fragments.
+	 * Returns a map where the keys are fragment names and the values are 
+	 * pieces of HTML to add to these fragments.
 	 *
-	 * Here are 4 built-in fragments: 'header', 'footer', 'before', and 'after', but components may also specify
+	 * Here are 4 built-in fragments: 'header', 'footer', 'before', and 
-	 * fragments of their own.
+	 * 'after', but components may also specify fragments of their own.
 	 * 
-	 * To specify a new fragment, specify a new fragment by including the text "$DefineFragment(fragmentname)" in the
+	 * To specify a new fragment, specify a new fragment by including the 
-	 * HTML that you return.  Fragment names should only contain alphanumerics, -, and _.
+	 * text "$DefineFragment(fragmentname)" in the HTML that you return. 
 	 *
-	 * If you attempt to return HTML for a fragment that doesn't exist, an exception will be thrown when the GridField
+	 * Fragment names should only contain alphanumerics, -, and _.
-	 * is rendered.
 	 *
-	 * @return Array
+	 * If you attempt to return HTML for a fragment that doesn't exist, an 
+	 * exception will be thrown when the {@link GridField} is rendered.
+	 *
+	 * @return array
 	 */
 	public function getHTMLFragments($gridField);
 }
 
 /**
  * Add a new column to the table display body, or modify existing columns.
+ *
  * Used once per record/row.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 interface GridField_ColumnProvider extends GridFieldComponent {
 
 	/**
 	 * Modify the list of columns displayed in the table.
-	 * See {@link GridFieldDataColumns->getDisplayFields()} and {@link GridFieldDataColumns}.
+	 *
+	 * @see {@link GridFieldDataColumns->getDisplayFields()}
+	 * @see {@link GridFieldDataColumns}.
 	 * 
 	 * @param GridField $gridField
 	 * @param array - List reference of all column names.
@@ -83,16 +99,29 @@ interface GridField_ColumnProvider extends GridFieldComponent {
 }
 
 /**
- * An action is defined by two things: an action name, and zero or more named arguments.  
+ * An action is defined by two things: an action name, and zero or more named 
+ * arguments.  
+ *
  * There is no built-in notion of a record-specific or column-specific action, 
- * but you may choose to define an argument such as ColumnName or RecordID in order to implement these.
+ * but you may choose to define an argument such as ColumnName or RecordID in 
- * Does not provide interface elements to call those actions, see {@link GridField_FormAction}.
+ * order to implement these.
+ *
+ * Does not provide interface elements to call those actions.
+ *
+ * @see {@link GridField_FormAction}.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 interface GridField_ActionProvider extends GridFieldComponent {
 	/**
 	 * Return a list of the actions handled by this action provider.
-	 * Used to identify the action later on through the $actionName parameter in {@link handleAction}.
+	 *
-	 * There is no namespacing on these actions, so you need to ensure that they don't conflict with other components.
+	 * Used to identify the action later on through the $actionName parameter 
+	 * in {@link handleAction}.
+	 *
+	 * There is no namespacing on these actions, so you need to ensure that 
+	 * they don't conflict with other components.
 	 * 
 	 * @param GridField
 	 * @return Array with action identifier strings. 
@@ -100,9 +129,10 @@ interface GridField_ActionProvider extends GridFieldComponent {
 	public function getActions($gridField);
 	
 	/**
-	 * Handle an action on the given grid field.
+	 * Handle an action on the given {@link GridField}.
-	 * Calls ALL components for every action handled, so the component
+	 *
-	 * needs to ensure it only accepts actions it is actually supposed to handle.
+	 * Calls ALL components for every action handled, so the component needs 
+	 * to ensure it only accepts actions it is actually supposed to handle.
 	 * 
 	 * @param GridField
 	 * @param String Action identifier, see {@link getActions()}.
@@ -113,14 +143,21 @@ interface GridField_ActionProvider extends GridFieldComponent {
 }
 
 /**
- * Can modify the data list.  
+ * Can modify the data list. 
- * For example, a paginating component can apply a limit, or a sorting component can apply a sort.  
+ *
- * Generally, the data manipulator will make use of to `GridState` variables to decide 
+ * For example, a paginating component can apply a limit, or a sorting 
- * how to modify the data list (see {@link GridState}).
+ * component can apply a sort.  
+ *
+ * Generally, the data manipulator will make use of to {@link GridState} 
+ * variables to decide how to modify the {@link DataList}.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 interface GridField_DataManipulator extends GridFieldComponent {
+
 	/**
-	 * Manipulate the datalist as needed by this grid modifier.
+	 * Manipulate the {@link DataList} as needed by this grid modifier.
 	 * 
 	 * @param GridField
 	 * @param SS_List
@@ -130,21 +167,37 @@ interface GridField_DataManipulator extends GridFieldComponent {
 }
 
 /**
- * Sometimes an action isn't enough: you need to provide additional support URLs for the grid.  
+ * Sometimes an action isn't enough: you need to provide additional support 
- * These URLs may return user-visible content, for example a pop-up form for editing a record's details, 
+ * URLs for the {@link GridField}.
- * or they may be support URLs for front-end functionality. 
+ *
- * For example a URL that will return JSON-formatted data for a javascript grid control.
+ * These URLs may return user-visible content, for example a pop-up form for 
+ * editing a record's details, or they may be support URLs for front-end 
+ * functionality. 
+ *
+ * For example a URL that will return JSON-formatted data for a javascript 
+ * grid control.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 interface GridField_URLHandler extends GridFieldComponent {
+
 	/**
-	 * Return URLs to be handled by this grid field, in an array the same form as $url_handlers.
+	 * Return URLs to be handled by this grid field, in an array the same form 
-	 * Handler methods will be called on the component, rather than the grid field.
+	 * as $url_handlers.
+	 *
+	 * Handler methods will be called on the component, rather than the 
+	 * {@link GridField}.
 	 */
 	public function getURLHandlers($gridField);
 }
 
 /**
- * A component which is used to handle when a grid field is saved into a record.
+ * A component which is used to handle when a {@link GridField} is saved into 
+ * a record.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 interface GridField_SaveHandler extends GridFieldComponent {
 

forms/gridfield/GridFieldConfig.php

@@ -1,21 +1,27 @@
 <?php
 /**
- * Encapsulates a collection of components following the {@link GridFieldComponent} interface.
+ * Encapsulates a collection of components following the 
- * While the {@link GridField} itself has some configuration in the form of setters,
+ * {@link GridFieldComponent} interface. While the {@link GridField} itself 
- * most of the details are dealt with through components.
+ * has some configuration in the form of setters, most of the details are 
+ * dealt with through components.
  * 
  * For example, you would add a {@link GridFieldPaginator} component to enable
- * pagination on the listed records, and configure it through {@link GridFieldPaginator->setItemsPerPage()}.
+ * pagination on the listed records, and configure it through 
+ * {@link GridFieldPaginator->setItemsPerPage()}.
  * 
- * In order to reduce the amount of custom code required, the framework provides
+ * In order to reduce the amount of custom code required, the framework 
- * some default configurations for common use cases:
+ * provides some default configurations for common use cases:
+ *
  * - {@link GridFieldConfig_Base} (added by default to GridField)
  * - {@link GridFieldConfig_RecordEditor}
  * - {@link GridFieldConfig_RelationEditor}
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 class GridFieldConfig {
+
 	/**
-	 *
 	 * @var ArrayList
 	 */
 	protected $components = null;
@@ -129,12 +135,15 @@ class GridFieldConfig {
 }
 
 /**
- * A simple readonly, paginated view of records,
+ * A simple readonly, paginated view of records, with sortable and searchable 
- * with sortable and searchable headers.
+ * headers.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 class GridFieldConfig_Base extends GridFieldConfig {
+
 	/**
-	 *
 	 * @param int $itemsPerPage - How many items per page should show up
 	 */
 	public function __construct($itemsPerPage=null) {
@@ -153,6 +162,9 @@ class GridFieldConfig_Base extends GridFieldConfig {
 
 /**
  * Allows viewing readonly details of individual records.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 class GridFieldConfig_RecordViewer extends GridFieldConfig_Base {
 
@@ -166,7 +178,8 @@ class GridFieldConfig_RecordViewer extends GridFieldConfig_Base {
 }
 
 /**
- * 
+ * @package framework
+ * @subpackage fields-gridfield
  */
 class GridFieldConfig_RecordEditor extends GridFieldConfig {
 	/**
@@ -195,22 +208,28 @@ class GridFieldConfig_RecordEditor extends GridFieldConfig {
 
 
 /**
- * Similar to {@link GridFieldConfig_RecordEditor}, but adds features
+ * Similar to {@link GridFieldConfig_RecordEditor}, but adds features to work 
- * to work on has-many or many-many relationships. 
+ * on has-many or many-many relationships. 
- * Allows to search for existing records to add to the relationship,
+ *
- * detach listed records from the relationship (rather than removing them from the database),
+ * Allows to search for existing records to add to the relationship, detach 
- * and automatically add newly created records to it.
+ * listed records from the relationship (rather than removing them from the 
+ * database), and automatically add newly created records to it.
  * 
- * To further configure the field, use {@link getComponentByType()},
+ * To further configure the field, use {@link getComponentByType()}, for 
- * for example to change the field to search.
+ * example to change the field to search.
+ *
  * <code>
  * GridFieldConfig_RelationEditor::create()
- * 	->getComponentByType('GridFieldAddExistingAutocompleter')->setSearchFields('MyField');
+ * 	->getComponentByType('GridFieldAddExistingAutocompleter')
+ * 	->setSearchFields('MyField');
  * </code>
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 class GridFieldConfig_RelationEditor extends GridFieldConfig {
+	
 	/**
-	 *
 	 * @param int $itemsPerPage - How many items per page should show up
 	 */
 	public function __construct($itemsPerPage=null) {

forms/gridfield/GridFieldDataColumns.php

@@ -1,17 +1,20 @@
 <?php
 /**
- * 
  * @see GridField
  * 
  * @package framework
- * @subpackage fields-relational
+ * @subpackage fields-gridfield
  */
 class GridFieldDataColumns implements GridField_ColumnProvider {
 
-	/** @var array */
+	/** 
+	 * @var array 
+	 */
 	public $fieldCasting = array();
 
-	/** @var array */
+	/** 
+	 * @var array 
+	 */
 	public $fieldFormatting = array();
 	
 	/**

forms/gridfield/GridFieldDeleteAction.php

@@ -1,24 +1,31 @@
 <?php
 /**
- * This class is a {@link GridField} component that adds a delete action for objects.
+ * This class is a {@link GridField} component that adds a delete action for 
+ * objects.
+ *
+ * This component also supports unlinking a relation instead of deleting the 
+ * object.
  *
- * This component also supports unlinking a relation instead of deleting the object.
  * Use the {@link $removeRelation} property set in the constructor.
  *
  * <code>
  * $action = new GridFieldDeleteAction(); // delete objects permanently
- * $action = new GridFieldDeleteAction(true); // removes the relation to object, instead of deleting
+ *
+ * // removes the relation to object instead of deleting
+ * $action = new GridFieldDeleteAction(true); 
  * </code>
  *
  * @package framework
- * @subpackage gridfield
+ * @subpackage fields-gridfield
  */
 class GridFieldDeleteAction implements GridField_ColumnProvider, GridField_ActionProvider {
 	
 	/**
-	 * If this is set to true, this actionprovider will remove the object from the list, instead of 
+	 * If this is set to true, this {@link GridField_ActionProvider} will 
-	 * deleting. In the case of a has one, has many or many many list it will uncouple the item from 
+	 * remove the object from the list, instead of deleting. 
-	 * the list.
+	 *
+	 * In the case of a has one, has many or many many list it will uncouple 
+	 * the item from the list.
 	 *
 	 * @var boolean
 	 */

forms/gridfield/GridFieldDetailForm.php

@@ -1,14 +1,20 @@
 <?php
 
 /**
- * Provides view and edit forms at GridField-specific URLs.  
+ * Provides view and edit forms at GridField-specific URLs. 
+ *
  * These can be placed into pop-ups by an appropriate front-end.
- * Usually added to a grid field alongside of {@link GridFieldEditButton}
+ *
- * which takes care of linking the individual rows to their edit view.
+ * Usually added to a {@link GridField} alongside of a
+ * {@link GridFieldEditButton} which takes care of linking the 
+ * individual rows to their edit view.
  * 
  * The URLs provided will be off the following form:
  *  - <FormURL>/field/<GridFieldName>/item/<RecordID>
  *  - <FormURL>/field/<GridFieldName>/item/<RecordID>/edit
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 class GridFieldDetailForm implements GridField_URLHandler {
 
@@ -183,6 +189,10 @@ class GridFieldDetailForm implements GridField_URLHandler {
 	}
 }
 
+/**
+ * @package framework
+ * @subpackage fields-gridfield
+ */
 class GridFieldDetailForm_ItemRequest extends RequestHandler {
 	
 	/**

forms/gridfield/GridFieldEditButton.php

@@ -1,10 +1,17 @@
 <?php
+
 /**
- * Provides the entry point to editing a single record presented by the grid.
+ * Provides the entry point to editing a single record presented by the 
- * Doesn't show an edit view on its own or modifies the record, but rather relies on routing conventions
+ * {@link GridField}.
- * established in {@link getColumnContent()}. The default routing applies to
+ *
- * the {@link GridFieldDetailForm} component, which has to be added separately
+ * Doesn't show an edit view on its own or modifies the record, but rather 
- * to the grid field configuration.
+ * relies on routing conventions established in {@link getColumnContent()}. 
+ *
+ * The default routing applies to the {@link GridFieldDetailForm} component, 
+ * which has to be added separately to the {@link GridField} configuration.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
 class GridFieldEditButton implements GridField_ColumnProvider {
 	
@@ -55,7 +62,7 @@ class GridFieldEditButton implements GridField_ColumnProvider {
 	}
 	
 	/**
-	 * Which GridField actions are this component handling
+	 * Which GridField actions are this component handling.
 	 *
 	 * @param GridField $gridField
 	 * @return array 
@@ -65,10 +72,10 @@ class GridFieldEditButton implements GridField_ColumnProvider {
 	}
 	
 	/**
-	 *
 	 * @param GridField $gridField
 	 * @param DataObject $record
 	 * @param string $columnName
+	 *
 	 * @return string - the HTML for the column 
 	 */
 	public function getColumnContent($gridField, $record, $columnName) {
@@ -83,12 +90,13 @@ class GridFieldEditButton implements GridField_ColumnProvider {
 	}
 	
 	/**
-	 * Handle the actions and apply any changes to the GridField
+	 * Handle the actions and apply any changes to the GridField.
 	 *
 	 * @param GridField $gridField
 	 * @param string $actionName
 	 * @param mixed $arguments
 	 * @param array $data - form data
+	 *
 	 * @return void
 	 */
 	public function handleAction(GridField $gridField, $actionName, $arguments, $data) {

forms/gridfield/GridFieldExportButton.php

@@ -1,12 +1,12 @@
 <?php
-/**
- * @package framework
- * @subpackage gridfield
- */
 
 /**
- * Adds an "Export list" button to the bottom of a GridField.
+ * Adds an "Export list" button to the bottom of a {@link GridField}.
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
+
 class GridFieldExportButton implements GridField_HTMLProvider, GridField_ActionProvider, GridField_URLHandler {
 
 	/**

forms/gridfield/GridFieldFilterHeader.php

@@ -1,11 +1,12 @@
 <?php
 /**
- * GridFieldFilterHeader alters the gridfield with some filtering fields in the header of each column
+ * GridFieldFilterHeader alters the {@link GridField} with some filtering 
+ * fields in the header of each column.
  * 
  * @see GridField
  * 
  * @package framework
- * @subpackage fields-relational
+ * @subpackage fields-gridfield
  */
 class GridFieldFilterHeader implements GridField_HTMLProvider, GridField_DataManipulator, GridField_ActionProvider {
 

forms/gridfield/GridFieldFooter.php

@@ -1,13 +1,19 @@
 <?php
 /**
- * Adding this class to a {@link GridFieldConfig} of a {@link GridField} adds a footer bar to that field.
+ * Adding this class to a {@link GridFieldConfig} of a {@link GridField} adds 
- * The footer looks just like the {@link GridFieldPaginator} control, except without the pagination controls.
+ * a footer bar to that field.
- * It only display the "Viewing 1-8 of 8" status text and (optionally) a configurable status message.
  *
- * The purpose of this class is to have a footer that can round off GridField without having to use pagination.
+ * The footer looks just like the {@link GridFieldPaginator} control, except 
+ * without the pagination controls.
+ *
+ * It only display the "Viewing 1-8 of 8" status text and (optionally) a 
+ * configurable status message.
+ *
+ * The purpose of this class is to have a footer that can round off 
+ * {@link GridField} without having to use pagination.
  *
  * @package framework
- * @subpackage gridfield
+ * @subpackage fields-gridfield
  */
 class GridFieldFooter implements GridField_HTMLProvider {
 
@@ -21,7 +27,9 @@ class GridFieldFooter implements GridField_HTMLProvider {
 	 * @param string $message - a message to display in the footer
 	 */
 	public function __construct($message = null) {
-		if($message) $this->message = $message;
+		if($message) {
+			$this->message = $message;
+		}
 	}
 
 
@@ -36,7 +44,12 @@ class GridFieldFooter implements GridField_HTMLProvider {
 		));
 
 		return array(
-			'footer' => $forTemplate->renderWith('GridFieldFooter', array('Colspan'=>count($gridField->getColumns()))),
+			'footer' => $forTemplate->renderWith(
+				'GridFieldFooter', 
+				array(
+					'Colspan' => count($gridField->getColumns())
+				)
+			)
 		);
 	}
 }

forms/gridfield/GridFieldLevelup.php

@@ -1,10 +1,13 @@
 <?php
 /**
- * Adds a "level up" link to a GridField table, which is useful
+ * Adds a "level up" link to a GridField table, which is useful when viewing 
- * when viewing hierarchical data. Requires the managed record 
+ * hierarchical data. Requires the managed record to have a "getParent()" 
- * to have a "getParent()" method or has_one relationship called "Parent".
+ * method or has_one relationship called "Parent".
+ *
+ * @package framework
+ * @subpackage fields-gridfield
  */
-class GridFieldLevelup extends Object implements GridField_HTMLProvider{
+class GridFieldLevelup extends Object implements GridField_HTMLProvider {
 	
 	/**
 	 * @var integer - the record id of the level up to

forms/gridfield/GridFieldPageCount.php

@@ -4,10 +4,10 @@
  * GridFieldPage displays a simple current page count summary.
  * E.g. "View 1 - 15 of 32"
  * 
- * Depends on GridFieldPaginator being added to the same gridfield
+ * Depends on {@link GridFieldPaginator} being added to the {@link GridField}.
  * 
  * @package framework
- * @subpackage fields-relational
+ * @subpackage fields-gridfield
  */
 class GridFieldPageCount implements GridField_HTMLProvider {
 	/**

forms/gridfield/GridFieldPaginator.php

@@ -1,10 +1,10 @@
 <?php
 /**
- * GridFieldPaginator paginates the gridfields list and adds controlls to the
+ * GridFieldPaginator paginates the {@link GridField} list and adds controls 
- * bottom of the gridfield.
+ * to the bottom of the {@link GridField}.
  * 
  * @package framework
- * @subpackage fields-relational
+ * @subpackage fields-gridfield
  */
 class GridFieldPaginator implements GridField_HTMLProvider, GridField_DataManipulator, GridField_ActionProvider {
 	

forms/gridfield/GridFieldPrintButton.php

@@ -1,11 +1,11 @@
 <?php
+
 /**
  * Adds an "Print" button to the bottom or top of a GridField.
  *
  * @package framework
- * @subpackage gridfield
+ * @subpackage fields-gridfield
  */
-
 class GridFieldPrintButton implements GridField_HTMLProvider, GridField_ActionProvider, GridField_URLHandler {
 
 	/**

forms/gridfield/GridFieldSortableHeader.php

@@ -1,11 +1,13 @@
 <?php
+
 /**
- * GridFieldSortableHeader adds column headers to a gridfield that can also sort the columns
+ * GridFieldSortableHeader adds column headers to a {@link GridField} that can 
+ * also sort the columns.
  * 
  * @see GridField
  * 
  * @package framework
- * @subpackage fields-relational
+ * @subpackage fields-gridfield
  */
 class GridFieldSortableHeader implements GridField_HTMLProvider, GridField_DataManipulator, GridField_ActionProvider {
 
@@ -14,7 +16,9 @@ class GridFieldSortableHeader implements GridField_HTMLProvider, GridField_DataM
 	 */
 	protected $throwExceptionOnBadDataType = true;
 
-	/** @var array */
+	/** 
+	 * @var array 
+	 */
 	public $fieldSorting = array();
 	
 	/**

forms/gridfield/GridFieldToolbarHeader.php

@@ -1,12 +1,16 @@
 <?php
+
 /**
- * Adding this class to a {@link GridFieldConfig} of a {@link GridField} adds a header title to that field.
+ * Adding this class to a {@link GridFieldConfig} of a {@link GridField} adds 
+ * a header title to that field.
+ *
  * The header serves to display the name of the data the GridField is showing.
  *
  * @package framework
- * @subpackage gridfield
+ * @subpackage fields-gridfield
  */
 class GridFieldToolbarHeader implements GridField_HTMLProvider {
+	
 	public function getHTMLFragments( $gridField) {
 		return array(
 			'header' => $gridField->renderWith('GridFieldToolbarHeader')

forms/gridfield/GridFieldViewButton.php

@@ -1,9 +1,11 @@
 <?php
 /**
  * A button that allows a user to view readonly details of a record. This is
- * disabled by default and intended for use in readonly grid fields.
+ * disabled by default and intended for use in readonly {@link GridField}
+ * instances.
  *
  * @package framework
+ * @subpackage fields-gridfield
  */
 class GridFieldViewButton implements GridField_ColumnProvider {
 
@@ -31,5 +33,4 @@ class GridFieldViewButton implements GridField_ColumnProvider {
 	public function getColumnMetadata($gridField, $col) {
 		return array('title' => null);
 	}
-
 }

forms/gridfield/GridState.php

@@ -1,13 +1,14 @@
 <?php
 /**
- * This class is a snapshot of the current status of a {@link GridField}. It's 
+ * This class is a snapshot of the current status of a {@link GridField}. 
- * designed to be inserted into a Form as a HiddenField and passed through to
+ *
- * actions such as the {@link GridField_FormAction}
+ * It's designed to be inserted into a Form as a HiddenField and passed through 
+ * to actions such as the {@link GridField_FormAction}.
  * 
  * @see GridField
  * 
  * @package framework
- * @subpackage fields-relational
+ * @subpackage fields-gridfield
  */
 class GridState extends HiddenField {
 
@@ -115,12 +116,13 @@ class GridState extends HiddenField {
 }
 
 /**
- * Simple set of data, similar to stdClass, but without the notice-level errors.
+ * Simple set of data, similar to stdClass, but without the notice-level 
+ * errors.
  *
  * @see GridState
  * 
  * @package framework
- * @subpackage fields-relational
+ * @subpackage fields-gridfield
  */
 class GridState_Data {
 
@@ -174,7 +176,7 @@ class GridState_Data {
  * @see GridState
  * 
  * @package framework
- * @subpackage fields-relational
+ * @subpackage fields-gridfield
  */
 class GridState_Component implements GridField_HTMLProvider {
 	

model/DataList.php

@@ -991,7 +991,10 @@ class DataList extends ViewableData implements SS_List, SS_Filterable, SS_Sortab
 	 */
 	public function removeByID($itemID) {
 		$item = $this->byID($itemID);
-		if($item) return $item->delete();
+
+		if($item) {
+			return $item->delete();
+		}
 	}
 	
 	/**

model/DataModel.php

@@ -1,45 +1,73 @@
 <?php
 
 /**
- * Representation of a DataModel - a collection of DataLists for each different data type.
+ * Representation of a DataModel - a collection of DataLists for each different 
+ * data type.
  * 
  * Usage:
- * 
+ * <code>
  * $model = new DataModel;
  * $mainMenu = $model->SiteTree->where('"ParentID" = 0 AND "ShowInMenus" = 1');
+ * </code>
+ *
+ * @package framework
+ * @subpackage model
  */
 class DataModel {
+
+	/**
+	 * @var DataModel
+	 */
 	protected static $inst;
 	
+	/**
+	 * @var array $customDataLists
+	 */
+	protected $customDataLists = array();
+
 	/**
 	 * Get the global DataModel.
+	 *
+	 * @return DataModel
 	 */
 	public static function inst() {
-		if(!self::$inst) self::$inst = new self;
+		if(!self::$inst) {
+			self::$inst = new self;
+		}
+		
 		return self::$inst;
 	}
 	
 	/**
-	 * Set the global DataModel, used when data is requested from static methods.
+	 * Set the global DataModel, used when data is requested from static 
+	 * methods.
+	 *
+	 * @return DataModel
 	 */
 	public static function set_inst(DataModel $inst) {
 		self::$inst = $inst;
 	}
 	
-	////////////////////////////////////////////////////////////////////////
+	/**
-
+	 * @param string
-	protected $customDataLists = array();
+	 *
-	
+	 * @return DataList
+	 */
 	public function __get($class) {
 		if(isset($this->customDataLists[$class])) {
 			return clone $this->customDataLists[$class];
 		} else {
 			$list = DataList::create($class);
 			$list->setDataModel($this);
+
 			return $list;
 		}
 	}
 	
+	/**
+	 * @param string
+	 * @param DataList
+	 */
 	public function __set($class, $item) {
 		$item = clone $item;
 		$item->setDataModel($this);

model/DataQuery.php

@@ -14,7 +14,7 @@
 class DataQuery {
 	
 	/**
-	 * @var String
+	 * @var string
 	 */
 	protected $dataClass;
 	
@@ -756,11 +756,16 @@ class DataQuery {
 /**
  * Represents a subgroup inside a WHERE clause in a {@link DataQuery}
  *
- * Stores the clauses for the subgroup inside a specific {@link SQLQuery} object.
+ * Stores the clauses for the subgroup inside a specific {@link SQLQuery} 
+ * object.
+ *
  * All non-where methods call their DataQuery versions, which uses the base
  * query object.
+ *
+ * @package framework
  */
 class DataQuery_SubGroup extends DataQuery {
+
 	protected $whereQuery;
 
 	public function __construct(DataQuery $base, $connective) {
@@ -790,6 +795,7 @@ class DataQuery_SubGroup extends DataQuery {
 		if($filter) {
 			$this->whereQuery->addWhere($filter);
 		}
+
 		return $this;
 	}
 
@@ -806,6 +812,7 @@ class DataQuery_SubGroup extends DataQuery {
 		if($filter) {
 			$this->whereQuery->addWhereAny($filter);
 		}
+
 		return $this;
 	}
 
@@ -814,8 +821,14 @@ class DataQuery_SubGroup extends DataQuery {
 			// We always need to have something so we don't end up with something like '... AND () AND ...'
 			return '1=1';
 		}
-		$sql = DB::getConn()->sqlWhereToString($this->whereQuery->getWhere(), $this->whereQuery->getConnective());
+
+		$sql = DB::getConn()->sqlWhereToString(
+			$this->whereQuery->getWhere(), 
+			$this->whereQuery->getConnective()
+		);
+		
 		$sql = preg_replace('[^\s*WHERE\s*]', '', $sql);
+
 		return $sql;
 	}
 }

model/HasManyList.php

@@ -1,9 +1,13 @@
 <?php
 
 /**
- * Subclass of {@link DataList} representing a has_many relation
+ * Subclass of {@link DataList} representing a has_many relation.
+ *
+ * @package framework
+ * @subpackage model
  */
 class HasManyList extends RelationList {
+
 	protected $foreignKey;
 	
 	/**
@@ -18,6 +22,7 @@ class HasManyList extends RelationList {
 	 */
 	public function __construct($dataClass, $foreignKey) {
 		parent::__construct($dataClass);
+
 		$this->foreignKey = $foreignKey;
 	}
 	
@@ -36,7 +41,9 @@ class HasManyList extends RelationList {
 
 	/**
 	 * Adds the item to this relation.
+	 *
 	 * It does so by setting the relationFilters.
+	 *
 	 * @param $item The DataObject to be added, or its ID 
 	 */
 	public function add($item) {
@@ -66,11 +73,14 @@ class HasManyList extends RelationList {
 
 	/**
 	 * Remove an item from this relation.
+	 *
 	 * Doesn't actually remove the item, it just clears the foreign key value.
-	 * @param $itemID The ID of the item to be removed
+	 *
+	 * @param $itemID The ID of the item to be removed.
 	 */
 	public function removeByID($itemID) {
 		$item = $this->byID($itemID);
+
 		return $this->remove($item);
 	}
 	

model/ManyManyList.php

@@ -1,7 +1,10 @@
 <?php
 
 /**
- * Subclass of {@link DataList} representing a many_many relation
+ * Subclass of {@link DataList} representing a many_many relation.
+ *
+ * @package framework
+ * @subpackage model
  */
 class ManyManyList extends RelationList {
 	

model/RelationList.php

@@ -2,9 +2,11 @@
 
 /**
  * A DataList that represents a relation.
+ *
  * Adds the notion of a foreign ID that can be optionally set.
  * 
- * @todo Is this additional class really necessary?
+ * @package framework
+ * @subpackage model
  */
 abstract class RelationList extends DataList {
 
@@ -13,8 +15,10 @@ abstract class RelationList extends DataList {
 	}
 
 	/**
-	 * Returns a copy of this list with the ManyMany relationship linked to the given foreign ID.
+	 * Returns a copy of this list with the ManyMany relationship linked to 
-	 * @param $id An ID or an array of IDs.
+	 * the given foreign ID.
+	 *
+	 * @param int|array $id An ID or an array of IDs.
 	 */
 	public function forForeignID($id) {
 		// Turn a 1-element array into a simple value
@@ -43,7 +47,9 @@ abstract class RelationList extends DataList {
 	}
 
 	/**
-	 * Returns a where clause that filters the members of this relationship to just the related items
+	 * Returns a where clause that filters the members of this relationship to 
+	 * just the related items.
+	 *
 	 * @param $id (optional) An ID or an array of IDs - if not provided, will use the current ids as per getForeignID
 	 */
 	abstract protected function foreignIDFilter($id = null);

model/UnsavedRelationList.php

@@ -1,19 +1,23 @@
 <?php
 
 /**
- * An ArrayList that represents an unsaved relation.
+ * An {@link ArrayList} that represents an unsaved relation.
  *
- * has_many and many_many relations cannot be saved until after the DataObject they're
+ * has_many and many_many relations cannot be saved until after the DataObject 
- * on has been written. This List pretends to be a RelationList and stores the related
+ * they're on has been written. This List pretends to be a RelationList and 
- * objects in memory.
+ * stores the related objects in memory.
  *
- * It can store both saved objects (as IDs) or unsaved objects (as instances of
+ * It can store both saved objects (as IDs) or unsaved objects (as instances 
- * $dataClass). Unsaved objects are then written when the list is saved into an instance
+ * of $dataClass). Unsaved objects are then written when the list is saved 
- * of RelationList.
+ * into an instance of {@link RelationList}.
  *
  * Most methods that alter the list of objects throw LogicExceptions.
+ *
+ * @package framework
+ * @subpackage model
  */
 class UnsavedRelationList extends ArrayList {
+	
 	/**
 	 * The DataObject class name that this relation is on
 	 * 

oembed/Oembed.php

@@ -1,15 +1,24 @@
 <?php
 /**
  * Format of the Oembed config. Autodiscover allows discovery of all URLs.
- * Endpoint set to true means autodiscovery for this specific provider is allowed
- * (even if autodiscovery in general has been disabled).
  *
+ * Endpoint set to true means autodiscovery for this specific provider is 
+ * allowed (even if autodiscovery in general has been disabled).
+ *
+ * <code>
+ * 
+ * name: Oembed
+ * ---
  * Oembed:
  *   providers:
- *     {pattern}:
+ *     'http://*.youtube.com/watch*':
- *        {endpoint}/true
+ *     'http://www.youtube.com/oembed/'
  *   autodiscover:
- *     true/false
+ *     true
+ * </code>
+ *
+ * @package framework
+ * @subpackage oembed
  */
 
 class Oembed {
@@ -178,6 +187,10 @@ class Oembed {
 	}
 }
 
+/**
+ * @package framework
+ * @subpackage oembed
+ */
 class Oembed_Result extends ViewableData {
 	/**
 	 * JSON data fetched from the Oembed URL.