tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity

MINOR phpdoc documentation

Browse Source 
git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@73509 467b73ca-7a2a-4603-9d3b-597d59a354a9
This commit is contained in:
Ingo Schommer 2009-03-22 22:59:14 +00:00
parent a970382924
commit b12a00c391
38 changed files with 117 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
api/DataFormatter.php
View File

@ -1,10 +1,11 @@
<?php
/**
* A DataFormatter object handles transformation of data from Sapphire model objects to a particular output format, and vice versa.
* This is most commonly used in developing RESTful APIs.
*
* @package sapphire
* @subpackage formatters
*/
abstract class DataFormatter extends Object {
/**

5
api/JSONDataFormatter.php
View File

@ -1,5 +1,8 @@
<?php
/**
* @package sapphire
* @subpackage formatters
*/
class JSONDataFormatter extends DataFormatter {
/**
* @todo pass this from the API to the data formatter somehow

4
api/VersionedRestfulServer.php
View File

@ -1,7 +1,9 @@
<?php
/**
* Simple wrapper to allow access to the live site via REST
*
* @package sapphire
* @subpackage integration
*/
class VersionedRestfulServer extends Controller {
function handleRequest($request) {

5
api/XMLDataFormatter.php
View File

@ -1,5 +1,8 @@
<?php
/**
* @package sapphire
* @subpackage formatters
*/
class XMLDataFormatter extends DataFormatter {
/**
* @todo pass this from the API to the data formatter somehow

4
core/ClassInfo.php
View File

@ -108,14 +108,14 @@ class ClassInfo {
* through the $class parameter as the first array value.
*
* Example usage:
* <example>
* <code>
* ClassInfo::subclassesFor('BaseClass');
* array(
* 0 => 'BaseClass',
* 'ChildClass' => 'ChildClass',
* 'GrandChildClass' => 'GrandChildClass'
* )
* </example>
* </code>
*
* @param mixed $class string of the classname or instance of the class
* @return array Names of all subclasses as an associative array.

1
core/Convert.php
View File

@ -17,7 +17,6 @@
* Objects of type {@link ViewableData} can have an "escaping type",
* which determines if they are automatically escaped before output by {@link SSViewer}.
*
* @usedby ViewableData::XML_val()
* @package sapphire
* @subpackage misc
*/

2
core/Requirements.php
View File

@ -315,8 +315,6 @@ class Requirements_Backend {
/**
* Remembers the filepaths of all cleared Requirements
* through {@link clear()}.
*
* @usedby {@link restore()}
*
* @var array $disabled
*/

3
core/ValidationException.php
View File

@ -3,6 +3,9 @@
* Exception thrown by {@link DataObject}::write if validation fails. By throwing an
* exception rather than a user error, the exception can be caught in unit tests and as such
* can be used as a successful test.
*
* @package sapphire
* @subpackage validation
*/
class ValidationException extends Exception {

5
core/ViewableData.php
View File

@ -281,7 +281,6 @@ class ViewableData extends Object implements IteratorAggregate {
/**
* Return the string-format type for the given field.
*
* @usedby ViewableData::XML_val()
* @param string $fieldName
* @return string 'xml'|'raw'
*/
@ -870,9 +869,9 @@ class ViewableData extends Object implements IteratorAggregate {
* Avoids having to subclass just to built templates with new css-classes,
* and allows for versatile css inheritance and overrides.
*
* <example>
* <code>
* <body class="$CSSClasses">
* </example>
* </code>
*
* @uses ClassInfo
*

3
core/control/ContentNegotiator.php
View File

@ -51,9 +51,6 @@ class ContentNegotiator {
return self::$encoding;
}
/**
* @usedby Controller->handleRequest()
*/
static function process(HTTPResponse $response) {
if(!self::enabled_for($response)) return;

1
core/control/ModelAsController.php
View File

@ -5,6 +5,7 @@
* that controller will be used instead. It should be a subclass of ContentController.
*
* @package sapphire
* @subpackage control
*/
class ModelAsController extends Controller implements NestedController {

3
core/control/RequestHandler.php
View File

@ -24,6 +24,9 @@
* Matching $url_handlers: "$Action/$ID" => "handleItem" (defined in TreeMultiSelectField class)
*
* {@link RequestHandler::handleRequest()} is where this behaviour is implemented.
*
* @package sapphire
* @subpackage control
*/
class RequestHandler extends ViewableData {
protected $request = null;

9
core/model/DataObject.php
View File

@ -426,8 +426,6 @@ class DataObject extends ViewableData implements DataObjectInterface, i18nEntity
* }
* </code>
*
* @usedby {@link DataObjectSet->toDropDownMap()}
*
* @return string
*/
public function getTitle() {
@ -1581,7 +1579,6 @@ class DataObject extends ViewableData implements DataObjectInterface, i18nEntity
* Generates a SearchContext to be used for building and processing
* a generic search form for properties on this object.
*
* @usedby {@link ModelAdmin}
* @return SearchContext
*/
public function getDefaultSearchContext() {
@ -1600,7 +1597,7 @@ class DataObject extends ViewableData implements DataObjectInterface, i18nEntity
* Some additional logic is included for switching field labels, based on
* how generic or specific the field type is.
*
* @usedby {@link SearchContext}
* Used by {@link SearchContext}.
*
* @param array $_params
* 'fieldClasses': Associative array of field names as keys and FormField classes as values
@ -1693,7 +1690,7 @@ class DataObject extends ViewableData implements DataObjectInterface, i18nEntity
* generate this set. To customize, overload this method in a subclass
* or decorate onto it by using {@link DataObjectDecorator->updateCMSFields()}.
*
* <example>
* <code>
* klass MyCustomClass extends DataObject {
* static $db = array('CustomProperty'=>'Boolean');
*
@ -1703,7 +1700,7 @@ class DataObject extends ViewableData implements DataObjectInterface, i18nEntity
* return $fields;
* }
* }
* </example>
* </code>
*
* @see Good example of complex FormField building: SiteTree::getCMSFields()
*

4
core/model/Image.php
View File

@ -462,8 +462,8 @@ class Image_Cached extends Image {
* Is connected to the URL routing "/image" through sapphire/_config.php,
* and used by all iframe-based upload-fields in the CMS.
*
* @usedby FileIFrameField
* @usedby ImageField
* Used by {@link FileIFrameField}, {@link ImageField}.
*
* @todo Refactor to using FileIFrameField and ImageField as a controller for the upload,
* rather than something totally disconnected from the original Form and FormField
* context. Without the original context its impossible to control permissions etc.

20
core/model/MySQLDatabase.php
View File

@ -489,7 +489,7 @@ class MySQLDatabase extends Database {
/**
* Return a boolean type-formatted string
*
* @params array $values Contains a tokenised list of info about this data type
* @param array $values Contains a tokenised list of info about this data type
* @return string
*/
public function boolean($values){
@ -504,7 +504,7 @@ class MySQLDatabase extends Database {
* Return a date type-formatted string
* For MySQL, we simply return the word 'date', no other parameters are necessary
*
* @params array $values Contains a tokenised list of info about this data type
* @param array $values Contains a tokenised list of info about this data type
* @return string
*/
public function date($values){
@ -518,7 +518,7 @@ class MySQLDatabase extends Database {
/**
* Return a decimal type-formatted string
*
* @params array $values Contains a tokenised list of info about this data type
* @param array $values Contains a tokenised list of info about this data type
* @return string
*/
public function decimal($values){
@ -539,7 +539,7 @@ class MySQLDatabase extends Database {
/**
* Return a enum type-formatted string
*
* @params array $values Contains a tokenised list of info about this data type
* @param array $values Contains a tokenised list of info about this data type
* @return string
*/
public function enum($values){
@ -554,7 +554,7 @@ class MySQLDatabase extends Database {
* Return a float type-formatted string
* For MySQL, we simply return the word 'date', no other parameters are necessary
*
* @params array $values Contains a tokenised list of info about this data type
* @param array $values Contains a tokenised list of info about this data type
* @return string
*/
public function float($values){
@ -568,7 +568,7 @@ class MySQLDatabase extends Database {
/**
* Return a int type-formatted string
*
* @params array $values Contains a tokenised list of info about this data type
* @param array $values Contains a tokenised list of info about this data type
* @return string
*/
public function int($values){
@ -583,7 +583,7 @@ class MySQLDatabase extends Database {
* Return a datetime type-formatted string
* For MySQL, we simply return the word 'datetime', no other parameters are necessary
*
* @params array $values Contains a tokenised list of info about this data type
* @param array $values Contains a tokenised list of info about this data type
* @return string
*/
public function ssdatetime($values){
@ -597,7 +597,7 @@ class MySQLDatabase extends Database {
/**
* Return a text type-formatted string
*
* @params array $values Contains a tokenised list of info about this data type
* @param array $values Contains a tokenised list of info about this data type
* @return string
*/
public function text($values){
@ -612,7 +612,7 @@ class MySQLDatabase extends Database {
* Return a time type-formatted string
* For MySQL, we simply return the word 'time', no other parameters are necessary
*
* @params array $values Contains a tokenised list of info about this data type
* @param array $values Contains a tokenised list of info about this data type
* @return string
*/
public function time($values){
@ -626,7 +626,7 @@ class MySQLDatabase extends Database {
/**
* Return a varchar type-formatted string
*
* @params array $values Contains a tokenised list of info about this data type
* @param array $values Contains a tokenised list of info about this data type
* @return string
*/
public function varchar($values){

24
core/model/Translatable.php
View File

@ -10,40 +10,40 @@
* <h2>Configuration</h2>
*
* You can enable {Translatable} for any subclass of {@link DataObject}:
* <example>
* <code>
* class MyClass extends DataObject {
* static $extensions = array(
* "Translatable"
* );
* }
* </example>
* </code>
* Make sure to rebuild the database through /dev/build after enabling translatable.
*
* <h2>Usage</h2>
*
* Getting a translation for an existing instance:
* <example>
* <code>
* $translatedObj = DataObject::get_one_by_locale('MyObject', 'de_DE');
* </example>
* </code>
*
* Getting a translation for an existing instance:
* <example>
* <code>
* $obj = DataObject::get_by_id('MyObject', 99); // original language
* $translatedObj = $obj->getTranslation('de_DE');
* </example>
* </code>
*
* Getting translations through {@link Translatable::set_reading_locale()}.
* This is *not* a recommended approach, but sometimes inavoidable (e.g. for {@link Versioned} methods).
* <example>
* <code>
* $obj = DataObject::get_by_id('MyObject', 99); // original language
* $translatedObj = $obj->getTranslation('de_DE');
* </example>
* </code>
*
* Creating a translation:
* <example>
* <code>
* $obj = new MyObject();
* $translatedObj = $obj->createTranslation('de_DE');
* </example>
* </code>
*
* <h2>Usage for SiteTree</h2>
*
@ -62,14 +62,14 @@
* Note: You can't get Children() for a parent page in a different language
* through set_reading_lang(). Get the translated parent first.
*
* <example>
* <code>
* // wrong
* Translatable::set_reading_lang('de');
* $englishParent->Children();
* // right
* $germanParent = $englishParent->getTranslation('de');
* $germanParent->Children();
* </example>
* </code>
*
* <h2>Translation groups</h2>
*

8
core/model/fieldtypes/DBField.php
View File

@ -218,9 +218,7 @@ abstract class DBField extends ViewableData {
* Returns a FormField instance used as a default
* for form scaffolding.
*
* @usedby {@link SearchContext}
* @usedby {@link ModelAdmin}
* @usedby {@link DataObject::scaffoldFormFields()}
* Used by {@link SearchContext}, {@link ModelAdmin}, {@link DataObject::scaffoldFormFields()}
*
* @param string $title Optional. Localized title of the generated instance
* @return FormField
@ -235,9 +233,7 @@ abstract class DBField extends ViewableData {
* Returns a FormField instance used as a default
* for searchform scaffolding.
*
* @usedby {@link SearchContext}
* @usedby {@link ModelAdmin}
* @usedby {@link DataObject::scaffoldFormFields()}
* Used by {@link SearchContext}, {@link ModelAdmin}, {@link DataObject::scaffoldFormFields()}.
*
* @param string $title Optional. Localized title of the generated instance
* @return FormField

2
core/model/fieldtypes/Double.php
View File

@ -1,6 +1,8 @@
<?php
/**
*
* @package sapphire
* @subpackage model
*/
class Double extends DBField {

9
core/model/fieldtypes/PrimaryKey.php
View File

@ -1,12 +1,11 @@
<?php
/**
* A special type Int field used for primary keys.
*
* @todo Allow for custom limiting/filtering of scaffoldFormField dropdown
*
* @param string $name
* @param DataOject $object The object that this is primary key for (should have a relation with $name)
* @package sapphire
* @subpackage model
*/
class PrimaryKey extends Int {
/**
@ -16,6 +15,10 @@ class PrimaryKey extends Int {
protected static $default_search_filter_class = 'ExactMatchMultiFilter';
/**
* @param string $name
* @param DataOject $object The object that this is primary key for (should have a relation with $name)
*/
function __construct($name, $object) {
$this->object = $object;
parent::__construct($name);

5
dev/BulkLoader.php
View File

@ -190,15 +190,14 @@ abstract class BulkLoader extends ViewableData {
* Useful for generation of spec documents for technical end users.
*
* Return Format:
* <example>
* <code>
* array(
* 'fields' => array('myFieldName'=>'myDescription'),
* 'relations' => array('myRelationName'=>'myDescription'),
* )
* </example>
* </code>
*
* @todo Mix in custom column mappings
* @usedby {@link ModelAdmin}
*
* @return array
**/

4
dev/CSVParser.php
View File

@ -1,5 +1,4 @@
<?php
/**
* Class to handle parsing of CSV files, where the column headers are in the first row.
* The idea is that you pass it another object to handle the actual procesing of the data in the CSV file.
@ -19,6 +18,9 @@
* $obj->write();
* }
* </code>
*
* @package sapphire
* @subpackage bulkloading
*/
class CSVParser extends Object implements Iterator {
protected $filename;

4
dev/CliTestReporter.php
View File

@ -1,7 +1,9 @@
<?php
/**
* Test reporter optimised for CLI (ie, plain-text) output
*
* @package sapphire
* @subpackage testing
*/
class CliTestReporter extends SapphireTestReporter {

4
dev/CodeViewer.php
View File

@ -1,7 +1,9 @@
<?php
/**
* Allows human reading of a test in a format suitable for agile documentation
*
* @package sapphire
* @subpackage tools
*/
class CodeViewer extends Controller {
/**

4
dev/JSTestRunner.php
View File

@ -5,7 +5,7 @@
* and includes them as iFrames.
*
* To create your own tests, please use this template:
* <example>
* <code>
* <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
* <html>
* <head>
@ -28,7 +28,7 @@
* <div id="main"></div>
* </body>
* </html>
* </example>
* </code>
*
* @package sapphire
* @subpackage testing

4
dev/ModelViewer.php
View File

@ -1,8 +1,10 @@
<?php
/**
* Gives you a nice way of viewing your data model.
* Access at dev/viewmodel
*
* @package sapphire
* @subpackage tools
*/
class ModelViewer extends Controller {
static $url_handlers = array(

4
dev/SSCli.php
View File

@ -1,8 +1,10 @@
<?php
/**
* Class to facilitate command-line output.
* Support less-trivial output stuff such as colours (on xterm-color)
*
* @package sapphire
* @subpackage dev
*/
class SSCli extends Object {
/**

5
dev/SapphireREPL.php
View File

@ -18,7 +18,10 @@ define('8192',E_DEPRECATED);
define('16384',E_USER_DEPRECATED);
define('30719',E_ALL);
*/
/**
* @package sapphire
* @subpackage dev
*/
class SapphireREPL extends Controller {
private function error_handler( $errno, $errstr, $errfile, $errline, $errctx ) {

3
dev/SapphireTestReporter.php
View File

@ -9,6 +9,9 @@
* Changelog:
* 0.6 First created [David Spurr]
* 0.7 Added fix to getTestException provided [Glen Ogilvie]
*
* @package sapphire
* @subpackage testing
*
* @version 0.7 2006-03-12
* @author David Spurr

4
email/Email.php
View File

@ -486,9 +486,7 @@ class Email extends ViewableData {
* unless overwritten. Also shown to users on live environments
* as a contact address on system error pages.
*
* @usedby Email->send()
* @usedby Email->sendPlain()
* @usedby Debug->friendlyError()
* Used by {@link Email->send()}, {@link Email->sendPlain()}, {@link Debug->friendlyError()}.
*
* @param string $newEmail
*/

4
forms/NestedForm.php
View File

@ -1,8 +1,10 @@
<?php
/**
* This is a form decorator that lets you place a form inside another form.
* The actions will be appropriately rewritten so that the nested form gets called, rather than the parent form.
*
* @package sapphire
* @subpackage forms
*/
class NestedForm extends ViewableData {
protected $form;

7
main.php
View File

@ -1,5 +1,4 @@
<?php
/************************************************************************************
************************************************************************************
** **
@ -9,6 +8,10 @@
************************************************************************************
************************************************************************************/
/**
* @package sapphire
* @subpackage core
*/
$majorVersion = strtok(phpversion(),'.');
if($majorVersion < 5) {
header("HTTP/1.1 500 Server Error");
@ -26,7 +29,7 @@ if($majorVersion < 5) {
* - 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
* 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

3
main.php5
View File

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

1
parsers/SQLFormatter.php
View File

@ -8,7 +8,6 @@
* @package sapphire
* @subpackage parsers
* @author Ingo Schommer, Silverstripe Ltd. (<firstname>@silverstripe.com)
* @usedby Database->databaseError()
*/
class SQLFormatter extends Object {

22
search/SearchContext.php
View File

@ -11,15 +11,9 @@
*
* In case you need multiple contexts, consider namespacing your request parameters
* by using {@link FieldSet->namespace()} on the $fields constructor parameter.
*
* @usedby {@link ModelAdmin}
*
* @param string $modelClass The base {@link DataObject} class that search properties related to.
* Also used to generate a set of result objects based on this class.
* @param FieldSet $fields Optional. FormFields mapping to {@link DataObject::$db} properties
* which are to be searched. Derived from modelclass using
* {@link DataObject::scaffoldSearchFields()} if left blank.
* @param array $filters Optional. Derived from modelclass if left blank
*
* @package sapphire
* @subpackage search
*/
class SearchContext extends Object {
@ -58,8 +52,14 @@ class SearchContext extends Object {
* Usually these values come from a submitted searchform
* in the form of a $_REQUEST object.
* CAUTION: All values should be treated as insecure client input.
*/
*
* @param string $modelClass The base {@link DataObject} class that search properties related to.
* Also used to generate a set of result objects based on this class.
* @param FieldSet $fields Optional. FormFields mapping to {@link DataObject::$db} properties
* which are to be searched. Derived from modelclass using
* {@link DataObject::scaffoldSearchFields()} if left blank.
* @param array $filters Optional. Derived from modelclass if left blank
*/
function __construct($modelClass, $fields = null, $filters = null) {
$this->modelClass = $modelClass;
$this->fields = ($fields) ? $fields : new FieldSet();

9
search/filters/NegationFilter.php
View File

@ -1,14 +1,9 @@
<?php
/**
* @package search
* @subpackage filters
*/
/**
* Matches on rows where the field is not equal to the given value.
*
* @package search
* @subpackage filters
* @package sapphire
* @subpackage search
*/
class NegationFilter extends SearchFilter {

2
search/filters/SearchFilter.php
View File

@ -184,8 +184,6 @@ abstract class SearchFilter extends Object {
* Relies on the field being populated with
* {@link setValue()}
*
* @usedby SearchContext
*
* @return boolean
*/
public function isEmpty() {

3
security/BasicAuth.php
View File

@ -16,7 +16,8 @@ class BasicAuth extends Object {
/**
* Require basic authentication. Will request a username and password if none is given.
*
* @usedby Controller::init()
* Used by {@link Controller::init()}.
*
* @param string $realm
* @param string|array $permissionCode
* @return Member $member

5
tasks/MigrateTranslatableTask.php
View File

@ -1,5 +1,8 @@
<?php
/**
* @package sapphire
* @subpackage tasks
*/
class MigrateTranslatableTask extends BuildTask {
protected $title = "Migrate Translatable Task";