From b1d2e3906b068d616f3d7626ff4f25ad4e6de359 Mon Sep 17 00:00:00 2001 From: Sam Minnee Date: Wed, 9 Jan 2008 04:18:36 +0000 Subject: [PATCH] API Documentation updates git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@47766 467b73ca-7a2a-4603-9d3b-597d59a354a9 --- _config.php | 5 +- api/RSSFeed.php | 4 + api/RestfulService.php | 30 +++--- api/SapphireSoapServer.php | 2 + api/SimplePie.php | 70 ++++++++---- api/Spyc.php | 6 +- cli-script.php | 11 +- cli/CliController.php | 6 +- cli/DailyTask.php | 2 + cli/MonthlyTask.php | 2 + cli/ScheduledTask.php | 2 + cli/WeeklyTask.php | 2 + core/ArrayData.php | 2 + core/ArrayLib.php | 2 + core/ClassInfo.php | 6 ++ core/Convert.php | 5 + core/Cookie.php | 2 + core/Debug.php | 7 +- core/Email.php | 15 ++- core/Extension.php | 6 +- core/HTTP.php | 5 + core/ManifestBuilder.php | 13 ++- core/Object.php | 2 + core/Requirements.php | 2 + core/SSViewer.php | 8 +- core/Session.php | 2 + core/ViewableData.php | 8 ++ core/control/ContentController.php | 6 ++ core/control/ContentNegotiator.php | 2 + core/control/Controller.php | 27 ++++- core/control/Director.php | 121 +++++++++++++++++---- core/control/FormResponse.php | 12 ++- core/control/HTTPResponse.php | 5 + core/control/ModelAsController.php | 6 +- core/control/NestedController.php | 3 +- core/control/RootURLController.php | 5 + core/i18n.php | 6 +- core/model/ComponentSet.php | 2 + core/model/CurrentPageIdentifier.php | 1 + core/model/DB.php | 2 + core/model/DataObject.php | 15 ++- core/model/DataObjectDecorator.php | 2 + core/model/DataObjectInterface.php | 2 + core/model/DataObjectLog.php | 2 + core/model/DataObjectSet.php | 2 + core/model/Database.php | 2 + core/model/DatabaseAdmin.php | 2 + core/model/ErrorPage.php | 1 + core/model/GhostPage.php | 1 + core/model/HiddenClass.php | 1 + core/model/Hierarchy.php | 4 +- core/model/Image.php | 2 + core/model/MySQLDatabase.php | 2 + core/model/PDODatabase.php | 2 + core/model/PageView.php | 1 + core/model/RedirectorPage.php | 1 + core/model/SQLMap.php | 2 + core/model/SQLQuery.php | 2 + core/model/SiteTree.php | 1 + core/model/Translatable.php | 5 +- core/model/Versioned.php | 5 + core/model/VirtualPage.php | 4 +- core/model/fieldtypes/Boolean.php | 4 +- core/model/fieldtypes/Currency.php | 2 + core/model/fieldtypes/DBField.php | 2 + core/model/fieldtypes/Date.php | 2 + core/model/fieldtypes/Datetime.php | 5 + core/model/fieldtypes/Decimal.php | 2 + core/model/fieldtypes/Enum.php | 2 + core/model/fieldtypes/Float.php | 2 + core/model/fieldtypes/HTMLText.php | 2 + core/model/fieldtypes/HTMLVarchar.php | 2 + core/model/fieldtypes/Int.php | 4 +- core/model/fieldtypes/Percentage.php | 2 + core/model/fieldtypes/SSDatetime.php | 2 + core/model/fieldtypes/Text.php | 2 + core/model/fieldtypes/Time.php | 2 + core/model/fieldtypes/Varchar.php | 2 + email/Notifications.php | 1 + email/QueuedEmail.php | 2 + email/QueuedEmailDispatchTask.php | 2 + filesystem/Archive.php | 2 + filesystem/File.php | 2 + filesystem/Filesystem.php | 2 + filesystem/Folder.php | 2 + filesystem/GD.php | 2 + filesystem/PostBackup.php | 6 +- filesystem/TarballArchive.php | 2 + forms/AjaxFormAction.php | 6 ++ forms/AjaxUniqueTextField.php | 16 ++- forms/AutocompleteTextField.php | 10 +- forms/BankAccountField.php | 8 ++ forms/CalendarDateField.php | 7 ++ forms/CheckboxField.php | 8 ++ forms/CheckboxFieldDisabled.php | 8 +- forms/CheckboxSetField.php | 8 ++ forms/ComplexRequiredFields.php | 9 +- forms/ComplexTableField.php | 26 ++--- forms/CompositeDateField.php | 11 ++ forms/CompositeField.php | 7 ++ forms/ConfirmedFormAction.php | 7 ++ forms/ConfirmedPasswordField.php | 8 ++ forms/CountryDropdownField.php | 7 ++ forms/CreditCardField.php | 8 +- forms/CurrencyField.php | 7 ++ forms/CustomRequiredFields.php | 11 +- forms/CustomValidator.php | 8 ++ forms/DMYCalendarDateField.php | 8 ++ forms/DMYDateField.php | 8 ++ forms/DataReport.php | 9 ++ forms/DatalessField.php | 7 ++ forms/DateField.php | 8 ++ forms/DisabledTransformation.php | 10 ++ forms/DropdownField.php | 7 ++ forms/DropdownTimeField.php | 10 ++ forms/EditForm.php | 9 ++ forms/EditableButton.php | 12 +-- forms/EditableCheckbox.php | 82 ++++++++------- forms/EditableCheckboxGroupField.php | 9 +- forms/EditableCheckboxOption.php | 146 +++++++++++++------------- forms/EditableDateField.php | 6 +- forms/EditableDropdown.php | 15 +-- forms/EditableDropdownOption.php | 96 ++++++++--------- forms/EditableEmailField.php | 14 +-- forms/EditableFileField.php | 6 +- forms/EditableFormField.php | 7 +- forms/EditableFormHeading.php | 6 +- forms/EditableMemberListField.php | 6 +- forms/EditableRadioField.php | 7 +- forms/EditableRadioOption.php | 92 ++++++++-------- forms/EditableTextField.php | 6 +- forms/EmailField.php | 7 ++ forms/EncryptField.php | 10 ++ forms/FieldGroup.php | 8 ++ forms/FieldSet.php | 7 +- forms/FileField.php | 8 ++ forms/FileIFrameField.php | 11 +- forms/Form.php | 6 +- forms/FormAction.php | 7 ++ forms/FormField.php | 6 +- forms/FormTransformation.php | 6 +- forms/GSTNumberField.php | 8 ++ forms/GroupedDropdownField.php | 15 ++- forms/HasManyComplexTableField.php | 9 +- forms/HasOneComplexTableField.php | 9 +- forms/HeaderField.php | 8 ++ forms/HiddenField.php | 7 ++ forms/HiddenFieldGroup.php | 8 ++ forms/HtmlEditorField.php | 6 +- forms/HtmlOneLineField.php | 8 ++ forms/ImageField.php | 7 ++ forms/ImageFormAction.php | 7 ++ forms/InlineFormAction.php | 8 ++ forms/LabelField.php | 7 ++ forms/LabelledLiteralField.php | 8 ++ forms/LanguageDropdownField.php | 7 ++ forms/ListboxField.php | 9 +- forms/LiteralField.php | 8 +- forms/LookupField.php | 12 +++ forms/ManyManyComplexTableField.php | 14 ++- forms/NamedLabelField.php | 7 ++ forms/NoScriptField.php | 8 +- forms/NoScriptFormAction.php | 10 ++ forms/NumericField.php | 8 ++ forms/OptionsetField.php | 9 +- forms/PasswordField.php | 7 ++ forms/PhoneNumberField.php | 8 ++ forms/PopupDateTimeField.php | 10 ++ forms/PrintableTransformation.php | 9 ++ forms/ProgressBar.php | 13 ++- forms/ReadonlyField.php | 8 ++ forms/ReadonlyTransformation.php | 10 ++ forms/RelatedDataEditor.php | 7 ++ forms/ReportField.php | 10 +- forms/RequiredFields.php | 8 ++ forms/ResetFormAction.php | 11 +- forms/RestrictedTextField.php | 8 ++ forms/SQLReport.php | 10 ++ forms/SelectionGroup.php | 7 ++ forms/SimpleImageField.php | 8 +- forms/Tab.php | 10 +- forms/TabSet.php | 5 +- forms/TableField.php | 14 ++- forms/TableListField.php | 12 ++- forms/TabularStyle.php | 7 ++ forms/TextField.php | 8 ++ forms/TextareaField.php | 8 ++ forms/TimeField.php | 16 ++- forms/ToggleCompositeField.php | 8 ++ forms/ToggleField.php | 7 ++ forms/TreeDropdownField.php | 10 ++ forms/TreeMultiselectField.php | 9 +- forms/TreeSelectorField.php | 10 ++ forms/TypeDropdown.php | 8 ++ forms/UniqueRestrictedTextField.php | 16 ++- forms/UniqueTextField.php | 16 ++- forms/Validator.php | 9 +- forms/editor/FieldEditor.php | 15 ++- integration/XML.php | 2 + main.php | 32 +++++- main.php5 | 7 ++ misc/Browscap.php | 2 + misc/GoogleSitemap.php | 2 + misc/IPS.php | 2 + misc/Statistics.php | 1 + parsers/BBCodeParser.php | 5 + parsers/TextParser.php | 4 +- profiler/Profiler.php | 2 + search/AdvancedSearchForm.php | 2 + search/SearchForm.php | 2 + security/Authenticator.php | 2 + security/BasicAuth.php | 2 + security/ChangePasswordForm.php | 2 + security/Geoip.php | 26 ++--- security/Group.php | 2 + security/LoginForm.php | 2 + security/Member.php | 2 + security/MemberAuthenticator.php | 2 + security/MemberLoginForm.php | 2 + security/Permission.php | 2 + security/PermissionDropdownField.php | 3 +- security/PermissionProvider.php | 2 + security/Security.php | 4 +- synchronise/Synchronise.php | 2 + synchronise/Synchronised.php | 2 + tests/InstallerTest.php | 10 ++ tests/TestRunner.php | 7 ++ widgets/Widget.php | 2 + widgets/WidgetArea.php | 4 +- 229 files changed, 1621 insertions(+), 441 deletions(-) diff --git a/_config.php b/_config.php index 211048e54..86dbfe158 100644 --- a/_config.php +++ b/_config.php @@ -12,10 +12,11 @@ * * Authenticator::register_authenticator('OpenIDAuthenticator'); * + * + * @package sapphire + * @subpackage core */ - - /** * Add pear parser to include path */ diff --git a/api/RSSFeed.php b/api/RSSFeed.php index 8e446b385..1553ecb53 100755 --- a/api/RSSFeed.php +++ b/api/RSSFeed.php @@ -9,6 +9,8 @@ * RSSFeed class * * This class is used to create an RSS feed. + * @package sapphire + * @subpackage integration */ class RSSFeed extends ViewableData { @@ -191,6 +193,8 @@ class RSSFeed extends ViewableData { * This class is used for entries of an RSS feed. * * @see RSSFeed + * @package sapphire + * @subpackage integration */ class RSSFeed_Entry extends ViewableData { diff --git a/api/RestfulService.php b/api/RestfulService.php index 7cd905cd8..484c0d532 100644 --- a/api/RestfulService.php +++ b/api/RestfulService.php @@ -8,6 +8,8 @@ /** * RestfulService class allows you to consume various RESTful APIs. * Through this you could connect and aggregate data of various web services. + * @package sapphire + * @subpackage integration */ class RestfulService extends ViewableData { protected $baseURL; @@ -24,7 +26,7 @@ class RestfulService extends ViewableData { /** * Sets the Query string parameters to send a request. - * @param params An array passed with necessary parameters. + * @param $params array An array passed with necessary parameters. */ function setQueryString($params=NULL){ $this->queryString = http_build_query($params,'','&'); @@ -85,9 +87,9 @@ class RestfulService extends ViewableData { /** * Gets attributes as an array, of a particular type of element. - * @params xml - the source xml to parse, this could be the original response received. - * @params collection - parent node which wraps the elements, if available - * @params element - element we need to extract the attributes. + * @param $xml string The source xml to parse, this could be the original response received. + * @param $collection string The name of parent node which wraps the elements, if available + * @param $element string The element we need to extract the attributes. * Example : * returns id, owner,secret and sever attribute values of all such photo elements. */ @@ -117,10 +119,10 @@ class RestfulService extends ViewableData { /** * Gets an attribute of a particular element. - * @params xml - the source xml to parse, this could be the original response received. - * @params collection - parent node which wraps the element, if available - * @params element - element we need to extract the attribute - * @params attr - name of the attribute + * @param $xml string The source xml to parse, this could be the original response received. + * @param $collection string The name of the parent node which wraps the element, if available + * @param $element string The element we need to extract the attribute + * @param $attr string The name of the attribute */ function getAttribute($xml, $collection=NULL, $element=NULL, $attr){ @@ -142,9 +144,9 @@ class RestfulService extends ViewableData { /** * Gets set of node values as an array. * When you get to the depth in the hierachchy use node_child_subchild syntax to get the value. - * @params xml - the source xml to parse, this could be the original response received. - * @params collection - parent node which wraps the elements, if available - * @params element - element we need to extract the node values. + * @param $xml string The the source xml to parse, this could be the original response received. + * @param $collection string The name of parent node which wraps the elements, if available + * @param $element string The element we need to extract the node values. */ function getValues($xml, $collection=NULL, $element=NULL){ @@ -182,9 +184,9 @@ class RestfulService extends ViewableData { /** * Gets a single node value. - * @params xml - the source xml to parse, this could be the original response received. - * @params collection - parent node which wraps the elements, if available - * @params element - element we need to extract the node value. + * @param $xml string The source xml to parse, this could be the original response received. + * @param $collection string The name of parent node which wraps the elements, if available + * @param $element string The element we need to extract the node value. */ function getValue($xml, $collection=NULL, $element=NULL){ diff --git a/api/SapphireSoapServer.php b/api/SapphireSoapServer.php index 043519446..e851d7f41 100755 --- a/api/SapphireSoapServer.php +++ b/api/SapphireSoapServer.php @@ -7,6 +7,8 @@ /** * Soap server class + * @package sapphire + * @subpackage integration */ class SapphireSoapServer extends Controller { static $methods = array(); diff --git a/api/SimplePie.php b/api/SimplePie.php index cf8f5170f..eda5b46db 100755 --- a/api/SimplePie.php +++ b/api/SimplePie.php @@ -5,28 +5,18 @@ * @subpackage integration */ -/**************************************************** -SIMPLEPIE -A PHP-Based RSS and Atom Feed Framework -Takes the hard work out of managing a complete RSS/Atom solution. - -Version: "Lemon Meringue" -Updated: 3 November 2006 -Copyright: 2004-2006 Ryan Parman, Geoffrey Sneddon -http://simplepie.org - -***************************************************** -LICENSE: - -GNU Lesser General Public License 2.1 (LGPL) -http://creativecommons.org/licenses/LGPL/2.1/ - -***************************************************** -Please submit all bug reports and feature requests to the SimplePie forums. -http://simplepie.org/support/ - -****************************************************/ - +/** + * A PHP-Based RSS and Atom Feed Framework + * Takes the hard work out of managing a complete RSS/Atom solution. + * Version: "Lemon Meringue" + * Updated: 3 November 2006 + * Copyright: 2004-2006 Ryan Parman, Geoffrey Sneddon + * http://simplepie.org + * LICENSE: GNU Lesser General Public License 2.1 (LGPL) + * Please submit all bug reports and feature requests to the SimplePie forums. http://simplepie.org/support/ + * @package sapphire + * @subpackage integration + */ class SimplePie { // SimplePie Info @@ -1178,6 +1168,10 @@ EOT; } } +/** + * @package sapphire + * @subpackage integration + */ class SimplePie_Item { var $data; @@ -1687,6 +1681,10 @@ class SimplePie_Item } } +/** + * @package sapphire + * @subpackage integration + */ class SimplePie_Author { var $name; @@ -1738,6 +1736,10 @@ class SimplePie_Author } } +/** + * @package sapphire + * @subpackage integration + */ class SimplePie_Enclosure { var $link; @@ -2125,6 +2127,10 @@ class SimplePie_Enclosure } } +/** + * @package sapphire + * @subpackage integration + */ class SimplePie_File { var $url; @@ -2383,6 +2389,10 @@ class SimplePie_File } } +/** + * @package sapphire + * @subpackage integration + */ class SimplePie_Cache { var $location; @@ -2450,6 +2460,10 @@ class SimplePie_Cache } } +/** + * @package sapphire + * @subpackage integration + */ class SimplePie_Misc { function absolutize_url($relative, $base) @@ -3560,6 +3574,10 @@ class SimplePie_Misc } } +/** + * @package sapphire + * @subpackage integration + */ class SimplePie_Locator { var $useragent; @@ -3764,6 +3782,10 @@ class SimplePie_Locator } } +/** + * @package sapphire + * @subpackage integration + */ class SimplePie_Parser { var $encoding; @@ -4396,6 +4418,10 @@ class SimplePie_Parser } } +/** + * @package sapphire + * @subpackage integration + */ class SimplePie_Sanitize { // Private vars diff --git a/api/Spyc.php b/api/Spyc.php index 20a96aed3..4e6a41b4f 100644 --- a/api/Spyc.php +++ b/api/Spyc.php @@ -13,6 +13,8 @@ /** * A node, used by Spyc for parsing YAML. + * @package sapphire + * @subpackage misc */ class YAMLNode { /**#@+ @@ -60,6 +62,8 @@ class YAMLNode { * $parser = new Spyc; * $array = $parser->load($file); * + * @package sapphire + * @subpackage misc */ class Spyc { @@ -842,7 +846,7 @@ class Spyc { * An ever-so-slightly modified version of the array_kmerge() function posted * to php.net by mail at nospam dot iaindooley dot com on 2004-04-08. * - * http://us3.php.net/manual/en/function.array-merge.php#41394 + * http://us3.php.net/manual/en/function.array-merge.php * * @access private * @param array $arr1 diff --git a/cli-script.php b/cli-script.php index c6afb0ca8..8f4644166 100755 --- a/cli-script.php +++ b/cli-script.php @@ -1,8 +1,17 @@ #!/usr/bin/php5 disableBasicAuth(); diff --git a/cli/DailyTask.php b/cli/DailyTask.php index 0065c4dba..92e00dbee 100755 --- a/cli/DailyTask.php +++ b/cli/DailyTask.php @@ -7,6 +7,8 @@ /** * Classes that must be run daily extend this class + * @package sapphire + * @subpackage cron */ class DailyTask extends ScheduledTask { diff --git a/cli/MonthlyTask.php b/cli/MonthlyTask.php index 7ae3bc6b0..f029a1d60 100755 --- a/cli/MonthlyTask.php +++ b/cli/MonthlyTask.php @@ -7,6 +7,8 @@ /** * Classes that must be run monthly extend this class + * @package sapphire + * @subpackage cron */ class MonthlyTask extends ScheduledTask { diff --git a/cli/ScheduledTask.php b/cli/ScheduledTask.php index 6bd4749a3..17b047f03 100755 --- a/cli/ScheduledTask.php +++ b/cli/ScheduledTask.php @@ -7,6 +7,8 @@ /** * Abstract task representing scheudled tasks + * @package sapphire + * @subpackage cron */ abstract class ScheduledTask extends CliController { // this class exists as a logical extension diff --git a/cli/WeeklyTask.php b/cli/WeeklyTask.php index f8bdb9054..178816353 100755 --- a/cli/WeeklyTask.php +++ b/cli/WeeklyTask.php @@ -7,6 +7,8 @@ /** * Classes that must be run weekly extend this class + * @package sapphire + * @subpackage cron */ class WeeklyTask extends ScheduledTask { diff --git a/core/ArrayData.php b/core/ArrayData.php index b2cb6e243..d4662a007 100755 --- a/core/ArrayData.php +++ b/core/ArrayData.php @@ -15,6 +15,8 @@ * "ClassName" => "Page", * "AddAction" => "Add a new Page page", * )); + * @package sapphire + * @subpackage view */ class ArrayData extends ViewableData { diff --git a/core/ArrayLib.php b/core/ArrayLib.php index 3f4e9eda7..776c1ab5c 100755 --- a/core/ArrayLib.php +++ b/core/ArrayLib.php @@ -7,6 +7,8 @@ /** * Library of static methods for manipulating arrays. + * @package sapphire + * @subpackage misc */ class ArrayLib extends Object { static function invert($arr) { diff --git a/core/ClassInfo.php b/core/ClassInfo.php index a1e3e86a1..4f95c5d66 100755 --- a/core/ClassInfo.php +++ b/core/ClassInfo.php @@ -1,4 +1,10 @@ 'Varchar', @@ -924,6 +933,8 @@ class Email_BounceRecord extends DataObject { /** * This class is responsible for ensuring that members who are on it receive NO email * communication at all. any correspondance is caught before the email is sent. + * @package sapphire + * @subpackage email */ class Email_BlackList extends DataObject{ static $db = array( diff --git a/core/Extension.php b/core/Extension.php index 198e577f5..5152d6a35 100644 --- a/core/Extension.php +++ b/core/Extension.php @@ -1,5 +1,10 @@ customise() to create. + * @package sapphire + * @subpackage view */ class ViewableData_Customised extends ViewableData { public function castingHelperPair($field) { @@ -991,6 +995,8 @@ class ViewableData_Customised extends ViewableData { /** * A ViewableData object that has been customised with an extra object. Use * ViewableData->customise() to create. + * @package sapphire + * @subpackage view */ class ViewableData_ObjectCustomised extends ViewableData { function __construct($obj, $extraObj) { @@ -1060,6 +1066,8 @@ class ViewableData_ObjectCustomised extends ViewableData { /** * Debugger helper. + * @package sapphire + * @subpackage view * @todo Finish this off */ class ViewableData_Debugger extends ViewableData { diff --git a/core/control/ContentController.php b/core/control/ContentController.php index 7666fe3c0..57f07bf58 100644 --- a/core/control/ContentController.php +++ b/core/control/ContentController.php @@ -1,4 +1,10 @@ urlParams; @@ -59,11 +61,32 @@ class Controller extends ViewableData { } /** + * Executes this controller, and return an {@link HTTPResponse} object with the result. + * + * This method first does a few set-up activities: + * - Push this controller ont to the controller stack - see {@link Controller::curr()} for information about this. + * - Call {@link init()} + * + * Then it looks for the action method. The action is taken from $this->urlParams['Action'] - for this reason, it's important + * to have $Action included in your Director rule + * + * If $requestParams['executeForm'] is set, then the Controller assumes that we're processing a form. This is usually + * set by adding ?executeForm=XXX to the form's action URL. Form processing differs in the following ways: + * - The action name will be the name of the button clicked. If no button-click can be detected, the first button in the + * list will be assumed. + * - If the given action method doesn't exist on the controller, Controller will look for that method on the Form object. + * this lets developers package both a form and its action handlers in a single subclass of Form. + * + * NOTE: You should rarely need to overload run() - this kind of change is only really appropriate for things like nested + * controllers - {@link ModelAsController} and {@link RootURLController} are two examples here. If you want to make more + * orthodox functionality, it's better to overload {@link init()} or {@link index()}. + * + * + * * Execute the appropriate action handler. If none is given, use defaultAction to display * a template. The default action will be appropriate in most cases where displaying data * is the core goal; the Viewer can call methods on the controller to get the data it needs. * - * @param array $urlParams named parameters extracted from the URL, including Action. * @param array $requestParams GET and POST variables. * @return HTTPResponse The response that this controller produces, including HTTP headers such as redirection info */ diff --git a/core/control/Director.php b/core/control/Director.php index a4a566da6..d9071cb00 100644 --- a/core/control/Director.php +++ b/core/control/Director.php @@ -1,14 +1,21 @@ class; @@ -1408,7 +1404,10 @@ class DataObject extends Controller implements DataObjectInterface { } /** - * Get a bunch of fields in a list - a