Merge pull request #7994 from creative-commoners/pulls/3.6/phpdocs

Update some phpdocs that had typos, missing parts or incorrect formats
This commit is contained in:
Damian Mooyman 2018-04-13 09:07:40 +12:00 committed by GitHub
commit a761056021
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
31 changed files with 142 additions and 101 deletions

View File

@ -25,18 +25,22 @@ abstract class CMSBatchAction extends Object {
/**
* Run this action for the given set of pages.
* Return a set of status-updated JavaScript to return to the CMS.
*
* @param SS_List $objs
*/
abstract public function run(SS_List $objs);
/**
* Helper method for responding to a back action request
* @param $successMessage string - The message to return as a notification.
* Can have up to two %d's in it. The first will be replaced by the number of successful
* changes, the second by the number of failures
* @param $status array - A status array like batchactions builds. Should be
* key => value pairs, the key can be any string: "error" indicates errors, anything
* else indicates a type of success. The value is an array. We don't care what's in it,
* we just use count($value) to find the number of items that succeeded or failed
*
* @param string $successMessage The message to return as a notification.
* Can have up to two %d's in it. The first will be replaced by the number of
* successful changes, the second by the number of failures
* @param array $status A status array like batchactions builds. Should be
* key => value pairs, the key can be any string: "error" indicates errors, anything
* else indicates a type of success. The value is an array. We don't care what's in it,
* we just use count($value) to find the number of items that succeeded or failed
* @return string JSON response
*/
public function response($successMessage, $status) {
$count = 0;
@ -69,10 +73,9 @@ abstract class CMSBatchAction extends Object {
* Helper method for processing batch actions.
* Returns a set of status-updating JavaScript to return to the CMS.
*
* @param $objs The SS_List of objects to perform this batch action
* on.
* @param $helperMethod The method to call on each of those objects.
* @return JSON encoded map in the following format:
* @param SS_List $objs The SS_List of objects to perform this batch action on.
* @param string $helperMethod The method to call on each of those objects.
* @return string JSON encoded map in the following format:
* {
* 'modified': {
* 3: {'TreeTitle': 'Page3'},
@ -117,10 +120,10 @@ abstract class CMSBatchAction extends Object {
/**
* Helper method for applicablePages() methods. Acts as a skeleton implementation.
*
* @param $ids The IDs passed to applicablePages
* @param $methodName The canXXX() method to call on each page to check if the action is applicable
* @param $checkStagePages Set to true if you want to check stage pages
* @param $checkLivePages Set to true if you want to check live pages (e.g, for deleted-from-draft)
* @param array $ids The IDs passed to applicablePages
* @param string $methodName The canXXX() method to call on each page to check if the action is applicable
* @param boolean $checkStagePages Set to true if you want to check stage pages
* @param boolean $checkLivePages Set to true if you want to check live pages (e.g, for deleted-from-draft)
*/
public function applicablePagesHelper($ids, $methodName, $checkStagePages = true, $checkLivePages = true) {
if(!is_array($ids)) user_error("Bad \$ids passed to applicablePagesHelper()", E_USER_WARNING);
@ -153,13 +156,19 @@ abstract class CMSBatchAction extends Object {
}
// if your batchaction has parameters, return a FieldList here
/**
* If your batchaction has parameters, return a FieldList here
*
* @return FieldList|boolean
*/
public function getParameterFields() {
return false;
}
/**
* If you wish to restrict the batch action to some users, overload this function.
*
* @return boolean
*/
public function canView() {
return true;

View File

@ -104,6 +104,7 @@ class CMSMenu extends Object implements IteratorAggregate, i18nEntityProvider {
* @param string $controllerClass The controller class for this menu, used to check permisssions.
* If blank, it's assumed that this is public, and always shown to users who
* have the rights to access some other part of the admin area.
* @param int $priority
* @param array $attributes an array of attributes to include on the link.
*
* @return boolean Success
@ -235,6 +236,7 @@ class CMSMenu extends Object implements IteratorAggregate, i18nEntityProvider {
* @param string $controllerClass The controller class for this menu, used to check permisssions.
* If blank, it's assumed that this is public, and always shown to users who
* have the rights to access some other part of the admin area.
* @param int $priority
* @param array $attributes an array of attributes to include on the link.
*
* @return boolean Success

View File

@ -821,12 +821,12 @@ class LeftAndMain extends Controller implements PermissionProvider {
/**
* Get a site tree HTML listing which displays the nodes under the given criteria.
*
* @param $className The class of the root object
* @param $rootID The ID of the root object. If this is null then a complete tree will be
* @param string $className The class of the root object
* @param int $rootID The ID of the root object. If this is null then a complete tree will be
* shown
* @param $childrenMethod The method to call to get the children of the tree. For example,
* @param string $childrenMethod The method to call to get the children of the tree. For example,
* Children, AllChildrenIncludingDeleted, or AllHistoricalChildren
* @return String Nested unordered list with links to each page
* @return string Nested unordered list with links to each page
*/
public function getSiteTreeFor($className, $rootID = null, $childrenMethod = null, $numChildrenMethod = null,
$filterFunction = null, $nodeCountThreshold = 30) {

View File

@ -229,6 +229,7 @@ class ArrayLib {
*
* @param array $array
* @param boolean $preserveKeys
* @param array $out
*
* @return array
*/

View File

@ -602,9 +602,9 @@ class Config {
* Configuration is modify only. The value passed is merged into the existing configuration. If you want to
* replace the current array value, you'll need to call remove first.
*
* @param $class string - The class to update a configuration value for
* @param $name string - The configuration property name to update
* @param $value any - The value to update with
* @param string $class The class to update a configuration value for
* @param string $name The configuration property name to update
* @param mixed $value The value to update with
*
* Arrays are recursively merged into current configuration as "latest" - for associative arrays the passed value
* replaces any item with the same key, for sequential arrays the items are placed at the end of the array, for
@ -648,13 +648,6 @@ class Config {
*
* @param string $class The class to remove a configuration value from
* @param string $name The configuration name
* @param mixed $key An optional key to filter against.
* If referenced config value is an array, only members of that array that match this key will be removed
* Must also match value if provided to be removed
* @param mixed $value And optional value to filter against.
* If referenced config value is an array, only members of that array that match this value will be removed
* If referenced config value is not an array, value will be removed only if it matches this argument
* Must also match key if provided and referenced config value is an array to be removed
*
* Matching is always by "==", not by "==="
*/

View File

@ -47,7 +47,9 @@ abstract class Extension {
* Called when this extension is added to a particular class
*
* @static
* @param $class
* @param string $class
* @param string $extensionClass
* @param mixed $args
*/
public static function add_to_class($class, $extensionClass, $args = null) {
// NOP

View File

@ -1045,7 +1045,13 @@ abstract class Object {
* The extension methods are defined during {@link __construct()} in {@link defineMethods()}.
*
* @param string $method the name of the method to call on each extension
* @param mixed $a1,... up to 7 arguments to be passed to the method
* @param mixed $a1
* @param mixed $a2
* @param mixed $a3
* @param mixed $a4
* @param mixed $a5
* @param mixed $a6
* @param mixed $a7
* @return array
*/
public function extend($method, &$a1=null, &$a2=null, &$a3=null, &$a4=null, &$a5=null, &$a6=null, &$a7=null) {

View File

@ -80,6 +80,7 @@ class SS_ConfigManifest {
* from the cache or re-scanning for classes.
*
* @param string $base The project base path.
* @param bool $includeTests
* @param bool $forceRegen Force the manifest to be regenerated.
*/
public function __construct($base, $includeTests = false, $forceRegen = false ) {
@ -192,6 +193,7 @@ class SS_ConfigManifest {
*
* Does _not_ build the actual variant
*
* @param bool $includeTests
* @param bool $cache Cache the result.
*/
public function regenerate($includeTests = false, $cache = true) {

View File

@ -92,7 +92,7 @@ class Upload extends Controller {
/**
* Get current validator
*
* @return Upload_Validator $validator
* @return Upload_Validator
*/
public function getValidator() {
return $this->validator;

View File

@ -122,6 +122,7 @@ class DropdownField extends FormField {
* @param array|ArrayAccess $source A map of the dropdown items
* @param string $value The current value
* @param Form $form The parent form
* @param string $emptyString Empty string value, e.g. "please choose"
*/
public function __construct($name, $title=null, $source=array(), $value='', $form=null, $emptyString=null) {
$this->setSource($source);

View File

@ -131,9 +131,9 @@ class FieldList extends ArrayList {
* This is most commonly used when overloading getCMSFields()
*
* @param string $tabName The name of the tab or tabset. Subtabs can be referred to as TabSet.Tab
* or TabSet.Tab.Subtab.
* This function will create any missing tabs.
* or TabSet.Tab.Subtab. This function will create any missing tabs.
* @param array $fields An array of {@link FormField} objects.
* @param string $name Name of the field to insert before (optional)
*/
public function addFieldsToTab($tabName, $fields, $insertBefore = null) {
$this->flushFieldsCache();
@ -663,8 +663,8 @@ class FieldList extends ArrayList {
* Support function for backwards compatibility purposes.
* Caution: Volatile API, might be removed in 3.1 or later.
*
* @param String $tabname Path to a tab, e.g. "Root.Content.Main"
* @return String Rewritten path, based on {@link tabPathRewrites}
* @param string $name Path to a tab, e.g. "Root.Content.Main"
* @return string Rewritten path, based on {@link tabPathRewrites}
*/
protected function rewriteTabPath($name) {
$isRunningTest = (class_exists('SapphireTest', false) && SapphireTest::is_running_test());

View File

@ -148,7 +148,7 @@ class FileField extends FormField {
/**
* Get custom validator for this field
*
* @param Upload_Validator $validator
* @return Upload_Validator
*/
public function getValidator() {
return $this->upload->getValidator();
@ -158,7 +158,7 @@ class FileField extends FormField {
* Set custom validator for this field
*
* @param Upload_Validator $validator
* @return FileField Self reference
* @return $this
*/
public function setValidator($validator) {
$this->upload->setValidator($validator);
@ -169,7 +169,7 @@ class FileField extends FormField {
* Sets the upload folder name
*
* @param string $folderName
* @return FileField Self reference
* @return $this
*/
public function setFolderName($folderName) {
$this->folderName = $folderName;

View File

@ -651,7 +651,6 @@ class FormField extends RequestHandler {
* Set the field value.
*
* @param mixed $value
* @param null|array|DataObject $data {@see Form::loadDataFrom}
*
* @return $this
*/

View File

@ -49,7 +49,6 @@ class FormScaffolder extends Object {
/**
* @param DataObject $obj
* @param array $params
*/
public function __construct($obj) {
$this->obj = $obj;

View File

@ -160,7 +160,7 @@ class HtmlEditorConfig {
*
* @see http://wiki.moxiecode.com/index.php/TinyMCE:API/tinymce.PluginManager/load
*
* @param String [0..] a string, or several strings, or a single array of strings - The plugins to enable
* @param string [0..] a string, or several strings, or a single array of strings - The plugins to enable
* @return HtmlEditorConfig
*/
public function enablePlugins() {
@ -179,7 +179,7 @@ class HtmlEditorConfig {
/**
* Enable one or several plugins. Will properly handle being passed a plugin that is already disabled
* @param String [0..] a string, or several strings, or a single array of strings - The plugins to disable
* @param string [0..] a string, or several strings, or a single array of strings - The plugins to disable
* @return HtmlEditorConfig
*/
public function disablePlugins() {
@ -241,13 +241,13 @@ class HtmlEditorConfig {
/**
* Internal function for adding and removing buttons related to another button
* @param $name string - the name of the button to modify
* @param $offset integer - the offset relative to that button to perform an array_splice at - 0 for before $name,
* @param $name string The name of the button to modify
* @param $offset integer The offset relative to that button to perform an array_splice at - 0 for before $name,
* 1 for after
* @param $del integer - the number of buttons to remove at the position given by index(string) + offset
* @param $add mixed - an array or single item to insert at the position given by index(string) + offset,
* @param $del integer The number of buttons to remove at the position given by index(string) + offset
* @param $add mixed An array or single item to insert at the position given by index(string) + offset,
* or null for no insertion
* @return boolean - true if $name matched a button, false otherwise
* @return boolean True if $name matched a button, false otherwise
*/
protected function modifyButtons($name, $offset, $del=0, $add=null) {
foreach ($this->buttons as &$buttons) {
@ -262,8 +262,8 @@ class HtmlEditorConfig {
/**
* Insert buttons before the first occurance of another button
* @param string - the name of the button to insert other buttons before
* @param string a string, or several strings, or a single array of strings - the button names to insert before
* @param string The name of the button to insert other buttons before
* @param string A string, or several strings, or a single array of strings - the button names to insert before
* that button
* @return boolean - true if insertion occured, false if it did not (because the given button name was not found)
*/
@ -275,10 +275,10 @@ class HtmlEditorConfig {
/**
* Insert buttons after the first occurance of another button
* @param string - the name of the button to insert other buttons after
* @param string a string, or several strings, or a single array of strings - the button names to insert after
* @param string The name of the button to insert other buttons after
* @param string A string, or several strings, or a single array of strings - the button names to insert after
* that button
* @return boolean - true if insertion occured, false if it did not (because the given button name was not found)
* @return boolean True if insertion occured, false if it did not (because the given button name was not found)
*/
public function insertButtonsAfter() {
$inserts = func_get_args();

View File

@ -165,8 +165,9 @@ class HtmlEditorSanitiser {
/**
* Given an element tag, return the rule structure for that element
* @param string $tag - The element tag
* @return stdClass - The element rule
*
* @param string $tag The element tag
* @return stdClass The element rule
*/
protected function getRuleForElement($tag) {
if(isset($this->elements[$tag])) {
@ -179,8 +180,10 @@ class HtmlEditorSanitiser {
/**
* Given an attribute name, return the rule structure for that attribute
* @param string $name - The attribute name
* @return stdClass - The attribute rule
*
* @param object $elementRule
* @param string $name The attribute name
* @return stdClass The attribute rule
*/
protected function getRuleForAttribute($elementRule, $name) {
if(isset($elementRule->attributes[$name])) {
@ -193,9 +196,9 @@ class HtmlEditorSanitiser {
/**
* Given a DOMElement and an element rule, check if that element passes the rule
* @param DOMElement $element - the element to check
* @param stdClass $rule - the rule to check against
* @return bool - true if the element passes (and so can be kept), false if it fails (and so needs stripping)
* @param DOMElement $element The element to check
* @param stdClass $rule The rule to check against
* @return bool True if the element passes (and so can be kept), false if it fails (and so needs stripping)
*/
protected function elementMatchesRule($element, $rule = null) {
// If the rule doesn't exist at all, the element isn't allowed

View File

@ -123,19 +123,19 @@ class SelectionGroup extends CompositeField {
class SelectionGroup_Item extends CompositeField {
/**
* @var String
* @var string
*/
protected $value;
/**
* @var String
* @var string
*/
protected $title;
/**
* @param String $value Form field identifier
* @param FormField $field Contents of the option
* @param String $title Title to show for the radio button option
* @param string $value Form field identifier
* @param FormField[] $fields Contents of the option
* @param string $title Title to show for the radio button option
*/
function __construct($value, $fields = null, $title = null) {
$this->value = $value;
@ -145,19 +145,33 @@ class SelectionGroup_Item extends CompositeField {
parent::__construct($fields);
}
/**
* @return string
*/
function getTitle() {
return $this->title;
}
/**
* @param string $title
* @return $this
*/
function setTitle($title) {
$this->title = $title;
return $this;
}
/**
* @return string
*/
function getValue() {
return $this->value;
}
/**
* @param mixed $Value
* @return $this
*/
function setValue($Value) {
$this->value = $Value;
return $this;

View File

@ -392,8 +392,8 @@ class TreeDropdownField extends FormField {
* Marking public function for the tree, which combines different filters sensibly.
* If a filter function has been set, that will be called. And if search text is set,
* filter on that too. Return true if all applicable conditions are true, false otherwise.
* @param $node
* @return unknown_type
* @param DataObject $node
* @return boolean
*/
public function filterMarking($node) {
if ($this->filterCallback && !call_user_func($this->filterCallback, $node)) return false;
@ -414,7 +414,8 @@ class TreeDropdownField extends FormField {
}
/**
* @param String $field
* @param string $field
* @return $this
*/
public function setLabelField($field) {
$this->labelField = $field;
@ -422,14 +423,15 @@ class TreeDropdownField extends FormField {
}
/**
* @return String
* @return string
*/
public function getLabelField() {
return $this->labelField;
}
/**
* @param String $field
* @param string $field
* @return $this
*/
public function setKeyField($field) {
$this->keyField = $field;
@ -437,14 +439,15 @@ class TreeDropdownField extends FormField {
}
/**
* @return String
* @return string
*/
public function getKeyField() {
return $this->keyField;
}
/**
* @param String $field
* @param string $field
* @return $this
*/
public function setSourceObject($class) {
$this->sourceObject = $class;
@ -452,7 +455,7 @@ class TreeDropdownField extends FormField {
}
/**
* @return String
* @return string
*/
public function getSourceObject() {
return $this->sourceObject;

View File

@ -202,7 +202,6 @@ class UploadField extends FileField {
* @param string $title The field label.
* @param SS_List $items If no items are defined, the field will try to auto-detect an existing relation on
* @link $record}, with the same name as the field name.
* @param Form $form Reference to the container form
*/
public function __construct($name, $title = null, SS_List $items = null) {
@ -1335,8 +1334,8 @@ class UploadField_ItemHandler extends RequestHandler {
);
/**
* @param UploadFIeld $parent
* @param int $item
* @param UploadField $parent
* @param int $itemID
*/
public function __construct($parent, $itemID) {
$this->parent = $parent;

View File

@ -79,7 +79,7 @@ class GridFieldAddExistingAutocompleter
protected $resultsLimit = 20;
/**
*
* @param string $targetFragment
* @param array $searchFields Which fields on the object in the list should be searched
*/
public function __construct($targetFragment = 'before', $searchFields = null) {

View File

@ -55,8 +55,7 @@ interface GridField_ColumnProvider extends GridFieldComponent {
* @see {@link GridFieldDataColumns}.
*
* @param GridField $gridField
* @param arary $columns List of columns
* @param array - List reference of all column names.
* @param array $columns List of columns
*/
public function augmentColumns($gridField, &$columns);
@ -205,7 +204,7 @@ interface GridField_SaveHandler extends GridFieldComponent {
/**
* Called when a grid field is saved - i.e. the form is submitted.
*
* @param GridField $field
* @param GridField $grid
* @param DataObjectInterface $record
*/
public function handleSave(GridField $grid, DataObjectInterface $record);

View File

@ -174,8 +174,8 @@ class GridFieldDataColumns implements GridField_ColumnProvider {
* e.g. to set a title for a search column header.
*
* @param GridField $gridField
* @param string $columnName
* @return array - Map of arbitrary metadata identifiers to their values.
* @param string $column
* @return array Map of arbitrary metadata identifiers to their values.
*/
public function getColumnMetadata($gridField, $column) {
$columns = $this->getDisplayFields($gridField);

View File

@ -24,8 +24,8 @@ class GridFieldFooter implements GridField_HTMLProvider {
protected $showrecordcount;
/**
*
* @param string $message - a message to display in the footer
* @param string $message A message to display in the footer
* @param boolean $showrecordcount
*/
public function __construct($message = null, $showrecordcount = true) {
if($message) {

View File

@ -23,7 +23,7 @@ class GridFieldPageCount implements GridField_HTMLProvider {
protected $itemClass = 'GridFieldPageCount';
/**
* @param string $targetFrament The fragment indicating the placement of this page count
* @param string $targetFragment The fragment indicating the placement of this page count
*/
public function __construct($targetFragment = 'before') {
$this->targetFragment = $targetFragment;

View File

@ -61,7 +61,8 @@ class GridFieldSortableHeader implements GridField_HTMLProvider, GridField_DataM
* Specify sortings with fieldname as the key, and actual fieldname to sort as value.
* Example: array("MyCustomTitle"=>"Title", "MyCustomBooleanField" => "ActualBooleanField")
*
* @param array $casting
* @param array $sorting
* @return $this
*/
public function setFieldSorting($sorting) {
$this->fieldSorting = $sorting;
@ -77,6 +78,8 @@ class GridFieldSortableHeader implements GridField_HTMLProvider, GridField_DataM
/**
* Returns the header row providing titles with sort buttons
*
* @param GridField $gridField
*/
public function getHTMLFragments($gridField) {
if(!$this->checkDataType($gridField->getList())) return;

View File

@ -24,8 +24,8 @@ class GridState extends HiddenField {
/**
*
* @param GridField $name
* @param string $data - json encoded string
* @param GridField $grid
* @param string $value JSON encoded string
*/
public function __construct($grid, $value = null) {
$this->grid = $grid;

View File

@ -364,9 +364,10 @@ class ShortcodeParser extends Object {
* Replaces the shortcode tags extracted by extractTags with HTML element "markers", so that
* we can parse the resulting string as HTML and easily mutate the shortcodes in the DOM
*
* @param string $content - The HTML string with [tag] style shortcodes embedded
* @param array $tags - The tags extracted by extractTags
* @return string - The HTML string with [tag] style shortcodes replaced by markers
* @param string $content The HTML string with [tag] style shortcodes embedded
* @param array $tags The tags extracted by extractTags
* @param callable $generator Callback for performing the replacements
* @return string The HTML string with [tag] style shortcodes replaced by markers
*/
protected function replaceTagsWithText($content, $tags, $generator) {
// The string with tags replaced with markers
@ -398,7 +399,7 @@ class ShortcodeParser extends Object {
* We don't use markers with attributes because there's no point, it's easier to do all the matching
* in-DOM after the XML parse
*
* @param DOMDocument $doc
* @param DOMDocument $htmlvalue
*/
protected function replaceAttributeTagsWithContent($htmlvalue) {
$attributes = $htmlvalue->query('//@*[contains(.,"[")][contains(.,"]")]');
@ -485,7 +486,8 @@ class ShortcodeParser extends Object {
* generate only inline blocks)
*
* @param DOMElement $node
* @param int $location - ShortcodeParser::BEFORE, ShortcodeParser::SPLIT or ShortcodeParser::INLINE
* @param DOMElement $parent
* @param string $location ShortcodeParser::BEFORE, ShortcodeParser::SPLIT or ShortcodeParser::INLINE
*/
protected function moveMarkerToCompliantHome($node, $parent, $location) {
// Move before block parent

View File

@ -125,9 +125,10 @@ class BasicAuth {
* define('SS_USE_BASIC_AUTH', true);
*
* @param boolean $protect Set this to false to disable protection.
* @param String $code {@link Permission} code that is required from the user.
* @param string $code {@link Permission} code that is required from the user.
* Defaults to "ADMIN". Set to NULL to just require a valid login, regardless
* of the permission codes a user has.
* @param string $message
*/
public static function protect_entire_site($protect = true, $code = 'ADMIN', $message = null) {
Config::inst()->update('BasicAuth', 'entire_site_protected', $protect);

View File

@ -246,6 +246,9 @@ class Group extends DataObject {
* See {@link DirectMembers()} for retrieving members without any inheritance.
*
* @param string $filter
* @param string $sort
* @param string $join
* @param string $limit
* @return ManyManyList
*/
public function Members($filter = "", $sort = "", $join = "", $limit = "") {

View File

@ -47,7 +47,6 @@ class MemberLoginForm extends LoginForm {
* @param bool $checkCurrentUser If set to TRUE, it will be checked if a
* the user is currently logged in, and if
* so, only a logout button will be rendered
* @param string $authenticatorClassName Name of the authenticator class that this form uses.
*/
public function __construct($controller, $name, $fields = null, $actions = null,
$checkCurrentUser = true) {

View File

@ -108,6 +108,8 @@ class PasswordEncryptor_Blowfish extends PasswordEncryptor {
* The two digit cost parameter is the base-2 logarithm of the iteration
* count for the underlying Blowfish-based hashing algorithmeter and must
* be in range 04-31, values outside this range will cause crypt() to fail.
*
* @var int
*/
protected static $cost = 10;
@ -127,8 +129,7 @@ class PasswordEncryptor_Blowfish extends PasswordEncryptor {
/**
* Gets the cost that is set for the blowfish algorithm
*
* @param int $cost
* @return null
* @return int
*/
public static function get_cost() {
return self::$cost;