MINOR Migrated various API-style documentation from doc.ss.org (from …

…r104157)

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

core/model/fieldtypes/Boolean.php

@@ -1,6 +1,7 @@
 <?php
 /**
  * Represents a boolean field.
+ * 
  * @package sapphire
  * @subpackage model
  */

core/model/fieldtypes/Currency.php

@@ -2,6 +2,14 @@
 /**
  * Represents a decimal field containing a currency amount.
  * Currency the currency class only supports single currencies.
+ * 
+ * Example definition via {@link DataObject::$db}:
+ * <code>
+ * static $db = array(
+ * 	"Price" => "Currency",
+ * 	"Tax" => "Currency(5)",
+ * );
+ * </code>
  *
  * @deprecated 2.5 Use Money class
  * 
@@ -11,13 +19,19 @@
 class Currency extends Decimal {
 	protected static $currencySymbol = '$';
 
+	/**
+	 * Returns the number as a currency, eg “$1,000.00”.
+	 */
 	function Nice() {
 		// return "<span title=\"$this->value\">$" . number_format($this->value, 2) . '</span>';
 		$val = self::$currencySymbol . number_format(abs($this->value), 2);
 		if($this->value < 0) return "($val)";
 		else return $val;
 	}
 
+	/**
+	 * Returns the number as a whole-number currency, eg “$1,000”.
+	 */
 	function Whole() {
 		$val = self::$currencySymbol . number_format(abs($this->value), 0);
 		if($this->value < 0) return "($val)";

core/model/fieldtypes/DBField.php

@@ -3,13 +3,26 @@
  * Single field in the database.
  * Every field from the database is represented as a sub-class of DBField.
  * 
- * <h2>Multi-value DBField objects</h2>
+ * <b>Multi-value DBField objects</b>
+ * 
  * Sometimes you will want to make DBField classes that don't have a 1-1 match to database fields.  To do this, there are a
  * number of fields for you to overload.
  *  - Overload {@link writeToManipulation} to add the appropriate references to the INSERT or UPDATE command
  *  - Overload {@link addToQuery} to add the appropriate items to a SELECT query's field list
  *  - Add appropriate accessor methods 
  * 
+ * <b>Subclass Example</b>
+ * 
+ * The class is easy to overload with custom types, e.g. the MySQL "BLOB" type (http://dev.mysql.com/doc/refman/5.0/en/blob.html).
+ * 
+ * <code>
+ * class Blob extends DBField {                                                                                                   
+ * 	function requireField() {                                                                                                         
+ * 		DB::requireField($this->tableName, $this->name, "blob");
+ *  }
+ * }
+ * </code>
+ * 
  * @package sapphire
  * @subpackage model
  */

core/model/fieldtypes/Date.php

@@ -6,6 +6,13 @@
  * Alternatively you can set a timestamp that is evaluated through
  * PHP's built-in date() function according to your system locale.
  * 
+ * Example definition via {@link DataObject::$db}:
+ * <code>
+ * static $db = array(
+ * 	"Expires" => "Date",
+ * );
+ * </code>
+ * 
  * @todo Add localization support, see http://open.silverstripe.com/ticket/2931
  * 
  * @package sapphire
@@ -41,6 +48,9 @@ function Nice() {
 		if($this->value) return date('d/m/Y', strtotime($this->value));
 	}
 
+	/**
+	 * Returns the date in US format: “01/18/2006”
+	 */
 	function NiceUS() {
 		if($this->value) return date('m/d/Y', strtotime($this->value));
 	}
@@ -91,7 +101,7 @@ function Full() {
 	/**
 	 * Return the date using a particular formatting string.
 	 * 
-	 * @param string $format Format code string. e.g. "d M Y"
+	 * @param string $format Format code string. e.g. "d M Y" (see http://php.net/date)
 	 * @return string The date in the requested format
 	 */
 	function Format($format) {

core/model/fieldtypes/Datetime.php

@@ -11,6 +11,13 @@
  * methods. This ensures that all time-based computations are testable with mock dates
  * through {@link SS_Datetime::set_mock_now()}.
  * 
+ * Example definition via {@link DataObject::$db}:
+ * <code>
+ * static $db = array(
+ *  "Expires" => "SSDatetime",
+ * );
+ * </code>
+ * 
  * @todo Add localization support, see http://open.silverstripe.com/ticket/2931
  * 
  * @package sapphire
@@ -31,6 +38,9 @@ function setValue($value) {
 		}
 	}
 
+	/**
+	 * Returns the date in the raw SQL-format, e.g. “2006-01-18 16:32:04”
+	 */
 	function Nice() {
 		return date('d/m/Y g:ia', strtotime($this->value));
 	}

core/model/fieldtypes/Enum.php

@@ -1,6 +1,8 @@
 <?php
 /**
- * Represents an enumeration field.
+ * Class Enum represents an enumeration of a set of strings.
+ * See {@link DropdownField} for a {@link FormField} to select enum values.
+ * 
  * @package sapphire
  * @subpackage model
  */
@@ -12,10 +14,17 @@ class Enum extends DBField {
 
 	/**
 	 * Create a new Enum field.
-	 * You should create an enum field like this: 
-	 *      		"MyField" => "Enum('Val1, Val2, Val3', 'Val1')"
-	 *	or: 		"MyField" => "Enum(Array('Val1', 'Val2', 'Val3'), 'Val1')"
-	 *  but NOT: 	"MyField" => "Enum('Val1', 'Val2', 'Val3', 'Val1')"
+	 * 
+	 * Example usage in {@link DataObject::$db} with comma-separated string notation ('Val1' is default)
+	 * <code>
+	 *  "MyField" => "Enum('Val1, Val2, Val3', 'Val1')"
+	 * </code>
+	 * 
+	 * Example usage in in {@link DataObject::$db} with array notation ('Val1' is default)
+	 * <code>
+	 * "MyField" => "Enum(array('Val1', 'Val2', 'Val3'), 'Val1')"
+	 * </code>
+	 * 
 	 * @param enum: A string containing a comma separated list of options or an array of Vals.
 	 * @param default The default option, which is either NULL or one of the items in the enumeration.
 	 */

core/model/fieldtypes/Float.php

@@ -1,6 +1,7 @@
 <?php
 /**
  * Represents a floating point field.
+ * 
  * @package sapphire
  * @subpackage model
  */
@@ -18,6 +19,11 @@ function requireField() {
 		DB::requireField($this->tableName, $this->name, $values);
 	}
 
+	/**
+	 * Returns the number, with commas and decimal places as appropriate, eg “1,000.00”.
+	 * 
+	 * @uses number_format()
+	 */
 	function Nice() {
 		return number_format($this->value, 2);
 	}

core/model/fieldtypes/HTMLText.php

@@ -1,8 +1,12 @@
 <?php
 /**
  * Represents a large text field that contains HTML content.
+ * This behaves similarly to {@link Text}, but the template processor won't escape any HTML content within it.
+ * 
+ * @see HTMLVarchar
+ * @see Text
+ * @see Varchar
  * 
- * This behaves similarly to Text, but the template processor won't escape any HTML content within it.
  * @package sapphire
  * @subpackage model
  */

core/model/fieldtypes/Int.php

@@ -1,6 +1,7 @@
 <?php
 /**
- * Represents an integer field.
+ * Represents a signed 32 bit integer field.
+ * 
  * @package sapphire
  * @subpackage model
  */
@@ -12,6 +13,9 @@ function __construct($name, $defaultVal = 0) {
 		parent::__construct($name);
 	}
 
+	/**
+	 * Returns the number, with commas added as appropriate, eg “1,000”.
+	 */
 	function Formatted() {
 		return number_format($this->value);
 	}

core/model/fieldtypes/Percentage.php

@@ -1,6 +1,15 @@
 <?php
 /**
  * Represents a decimal field from 0-1 containing a percentage value.
+ * 
+ * Example instantiation in {@link DataObject::$db}:
+ * <code>
+ * static $db = array(
+ * 	"SuccessRatio" => "Percentage",
+ * 	"ReallyAccurate" => "Percentage(6)",
+ * );
+ * </code>
+ * 
  * @package sapphire
  * @subpackage model
  */
@@ -15,6 +24,9 @@ function __construct($name, $precision = 4) {
 		parent::__construct($name, $precision + 1, $precision);
 	}
 
+	/**
+	 * Returns the number, expressed as a percentage. For example, “36.30%”
+	 */
 	function Nice() {
 		return number_format($this->value * 100, $this->decimalSize - 2) . '%';
 	}

core/model/fieldtypes/Text.php

@@ -1,6 +1,18 @@
 <?php
 /**
- * Represents a long text field.
+ * Represents a variable-length string of up to 2 megabytes, designed to store raw text
+ * 
+ * Example definition via {@link DataObject::$db}:
+ * <code>
+ * static $db = array(
+ * 	"MyDescription" => "Text",
+ * );
+ * </code>
+ * 
+ * @see HTMLText
+ * @see HTMLVarchar
+ * @see Varchar
+ * 
  * @package sapphire
  * @subpackage model
  */

core/model/fieldtypes/Time.php

@@ -2,6 +2,13 @@
 /**
  * Represents a column in the database with the type 'Time'.
  * 
+ * Example definition via {@link DataObject::$db}:
+ * <code>
+ * static $db = array(
+ * 	"StartTime" => "Time",
+ * );
+ * </code>
+ * 
  * @todo Add localization support, see http://open.silverstripe.com/ticket/2931
  * 
  * @package sapphire

core/model/fieldtypes/Varchar.php

@@ -1,6 +1,11 @@
 <?php
 /**
- * Represents a short text field.
+ * Class Varchar represents a variable-length string of up to 255 characters, designed to store raw text
+ * 
+ * @see HTMLText
+ * @see HTMLVarchar
+ * @see Text
+ * 
  * @package sapphire
  * @subpackage model
  */
@@ -10,6 +15,7 @@ class Varchar extends StringField {
 
  	/**
  	 * Construct a new short text field
+ 	 * 
  	 * @param $name string The name of the field
  	 * @param $size int The maximum size of the field, in terms of characters
  	 * @param $options array Optional parameters, e.g. array("nullifyEmpty"=>false). See {@link StringField::setOptions()} for information on the available options