Permalink
Browse files

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
  • Loading branch information...
1 parent 0fe3528 commit 32afc2923ebbaafe4cc8f1b9153f6baa1d12fab1 @chillu chillu committed Oct 14, 2010
@@ -1,6 +1,7 @@
<?php
/**
* Represents a boolean field.
+ *
* @package sapphire
* @subpackage model
*/
@@ -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)";
@@ -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
*/
@@ -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) {
@@ -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));
}
@@ -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.
*/
@@ -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);
}
@@ -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
*/
@@ -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);
}
@@ -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) . '%';
}
@@ -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
*/
@@ -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
@@ -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

0 comments on commit 32afc29

Please sign in to comment.