Merge branch '3.1'

code/controllers/AssetAdmin.php

@@ -625,6 +625,7 @@ JS
 	}
 
 	/**
+	 * @param bool $unlinked
 	 * @return ArrayList
 	 */
 	public function Breadcrumbs($unlinked = false) {

code/controllers/CMSFileAddController.php

@@ -48,6 +48,8 @@ class CMSFileAddController extends LeftAndMain {
 	}
 
 	/**
+	 * @param null $id Not used.
+	 * @param null $fields Not used.
 	 * @return Form
 	 * @todo what template is used here? AssetAdmin_UploadContent.ss doesn't seem to be used anymore
 	 */
@@ -106,6 +108,7 @@ class CMSFileAddController extends LeftAndMain {
 	}
 
 	/**
+	 * @param bool $unlinked
 	 * @return ArrayList
 	 */
 	public function Breadcrumbs($unlinked = false) {

code/controllers/CMSMain.php

@@ -134,6 +134,7 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
 	/**
 	 * Override {@link LeftAndMain} Link to allow blank URL segment for CMSMain.
 	 *
+	 * @param string|null $action Action to link to.
 	 * @return string
 	 */
 	public function Link($action = null) {
@@ -352,6 +353,7 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
 	}
 
 	/**
+	 * @param bool $unlinked
 	 * @return ArrayList
 	 */
 	public function Breadcrumbs($unlinked = false) {
@@ -510,6 +512,7 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
 	 *
 	 * @param int $id Record ID
 	 * @param int $versionID optional Version id of the given record
+	 * @return DataObject
 	 */
  	public function getRecord($id, $versionID = null) {
 		$treeClass = $this->stat('tree_class');
@@ -671,12 +674,17 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
 	}
 
 	/**
+	 * @param SS_HTTPRequest $request
 	 * @return String HTML
 	 */
 	public function treeview($request) {
 		return $this->renderWith($this->getTemplatesWithSuffix('_TreeView'));
 	}
 
+	/**
+	 * @param SS_HTTPRequest $request
+	 * @return String HTML
+	 */
 	public function listview($request) {
 		return $this->renderWith($this->getTemplatesWithSuffix('_ListView'));
 	}
@@ -686,9 +694,10 @@ class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionPr
 	 * defaulting to no filter and show all pages in first level.
 	 * Doubles as search results, if any search parameters are set through {@link SearchForm()}.
 	 * 
-	 * @param Array Search filter criteria
-	 * @param Int Optional parent node to filter on (can't be combined with other search criteria)
+	 * @param Array $params Search filter criteria
+	 * @param Int $parentID Optional parent node to filter on (can't be combined with other search criteria)
 	 * @return SS_List
+	 * @throws Exception if invalid filter class is passed.
 	 */
 	public function getList($params, $parentID = 0) {
 		$list = new DataList($this->stat('tree_class'));

code/controllers/CMSPageHistoryController.php

@@ -39,6 +39,7 @@ class CMSPageHistoryController extends CMSMain {
 	}
 	
 	/**
+	 * @param SS_HTTPRequest $request
 	 * @return array
 	 */
 	public function show($request) {
@@ -57,6 +58,7 @@ class CMSPageHistoryController extends CMSMain {
 	}
 	
 	/**
+	 * @param SS_HTTPRequest $request
 	 * @return array
 	 */
 	public function compare($request) {
@@ -96,7 +98,7 @@ class CMSPageHistoryController extends CMSMain {
 	 * @param int $id ID of the record to show
 	 * @param array $fields optional
 	 * @param int $versionID
-	 * @param int $compare Compare mode
+	 * @param int $compareID Compare mode
 	 *
 	 * @return Form
 	 */
@@ -341,6 +343,7 @@ class CMSPageHistoryController extends CMSMain {
 	}
 
 	/**
+	 * @param int|null $versionID
 	 * @return Form
 	 */
 	public function ShowVersionForm($versionID = null) {
@@ -353,6 +356,8 @@ class CMSPageHistoryController extends CMSMain {
 	}
 	
 	/**
+	 * @param int $versionID
+	 * @param int $otherVersionID
 	 * @return Form
 	 */
 	public function CompareVersionsForm($versionID, $otherVersionID) {

code/controllers/CMSSettingsController.php

@@ -24,6 +24,8 @@ class CMSSettingsController extends LeftAndMain {
 	}
 
 	/**
+	 * @param null $id Not used.
+	 * @param null $fields Not used.
 	 * @return Form
 	 */
 	public function getEditForm($id = null, $fields = null) {

code/controllers/ContentController.php

@@ -51,6 +51,7 @@ class ContentController extends Controller {
 	 * Return the link to this controller, but force the expanded link to be returned so that form methods and
 	 * similar will function properly.
 	 *
+	 * @param string|null $action Action to link to.
 	 * @return string
 	 */
 	public function Link($action = null) {
@@ -77,7 +78,8 @@ class ContentController extends Controller {
 	}
 	
 	/**
-	 * @return SS_List
+	 * @param string $link
+	 * @return SiteTree
 	 */
 	public function Page($link) {
 		return SiteTree::get_by_link($link);
@@ -151,7 +153,10 @@ class ContentController extends Controller {
 	 * This acts the same as {@link Controller::handleRequest()}, but if an action cannot be found this will attempt to
 	 * fall over to a child controller in order to provide functionality for nested URLs.
 	 *
+	 * @param SS_HTTPRequest $request
+	 * @param DataModel $model
 	 * @return SS_HTTPResponse
+	 * @throws SS_HTTPResponse_Exception
 	 */
 	public function handleRequest(SS_HTTPRequest $request, DataModel $model = null) {
 		$child  = null;
@@ -232,7 +237,8 @@ class ContentController extends Controller {
 
 	/**
 	 * Returns a fixed navigation menu of the given level.
-	 * @return SS_List
+	 * @param int $level Menu level to return.
+	 * @return ArrayList
 	 */
 	public function getMenu($level = 1) {
 		if($level == 1) {

code/controllers/ModelAsController.php

@@ -42,6 +42,8 @@ class ModelAsController extends Controller implements NestedController {
 	
 	/**
 	 * @uses ModelAsController::getNestedController()
+	 * @param SS_HTTPRequest $request
+	 * @param DataModel $model
 	 * @return SS_HTTPResponse
 	 */
 	public function handleRequest(SS_HTTPRequest $request, DataModel $model) {
@@ -88,6 +90,7 @@ class ModelAsController extends Controller implements NestedController {
 	
 	/**
 	 * @return ContentController
+	 * @throws Exception If URLSegment not passed in as a request parameter.
 	 */
 	public function getNestedController() {
 		$request = $this->request;
@@ -127,7 +130,8 @@ class ModelAsController extends Controller implements NestedController {
 	 * @deprecated 3.2 Use OldPageRedirector::find_old_page instead
 	 *
 	 * @param string $URLSegment A subset of the url. i.e in /home/contact/ home and contact are URLSegment.
-	 * @param int $parentID The ID of the parent of the page the URLSegment belongs to.
+	 * @param int $parent The ID of the parent of the page the URLSegment belongs to.
+	 * @param bool $ignoreNestedURLs
 	 * @return SiteTree
 	 */
 	static public function find_old_page($URLSegment, $parent = null, $ignoreNestedURLs = false) {

code/controllers/OldPageRedirector.php

@@ -7,6 +7,7 @@ class OldPageRedirector extends Extension {
 	 * find an old URL that it should be redirecting to.
 	 *
 	 * @param SS_HTTPResponse $request The request object
+	 * @throws SS_HTTPResponse_Exception
 	 */
 	public function onBeforeHTTPError404($request) {
 		// Build up the request parameters

code/controllers/RootURLController.php

@@ -107,6 +107,7 @@ class RootURLController extends Controller {
 	
 	/**
 	 * @param SS_HTTPRequest $request
+	 * @param DataModel|null $model
 	 * @return SS_HTTPResponse
 	 */
 	public function handleRequest(SS_HTTPRequest $request, DataModel $model = null) {

code/controllers/SilverStripeNavigator.php

@@ -20,7 +20,8 @@ class SilverStripeNavigator extends ViewableData {
 	protected $record;
 	
 	/**
-	 * @param DataObject
+	 * @param DataObject $record
+	 * @throws InvalidArgumentException if record doesn't implement CMSPreviewable
 	 */
 	public function __construct($record) {
 		if(!in_array('CMSPreviewable', class_implements($record))) {

code/forms/SiteTreeURLSegmentField.php

@@ -71,7 +71,7 @@ class SiteTreeURLSegmentField extends TextField {
 	}
 	
 	/**
-	 * @param string the secondary text to show
+	 * @param string $string The secondary text to show
 	 */
 	public function setHelpText($string){
 		$this->helpText = $string; 

code/model/ErrorPage.php

@@ -220,9 +220,7 @@ class ErrorPage extends Page {
 	 * content, so the page can be shown even when SilverStripe is not
 	 * functioning correctly before publishing this page normally.
 	 *
-	 * @param string|int $fromStage Place to copy from. Can be either a stage name or a version number.
-	 * @param string $toStage Place to copy to. Must be a stage name.
-	 * @param boolean $createNewVersion Set this to true to create a new version number.  By default, the existing version number will be copied over.
+	 * @return void
 	 */
 	public function doPublish() {
 		parent::doPublish();
@@ -330,8 +328,9 @@ class ErrorPage_Controller extends Page_Controller {
 	 * pages such as 401 and 403 pages won't be rendered due to
 	  * {@link SS_HTTPResponse::isFinished() ignoring the response body.
 	 *
-	 * @param SS_HTTPRequest
-	 * @param DataModel
+	 * @param SS_HTTPRequest $request
+	 * @param DataModel $model
+	 * @return SS_HTTPResponse
 	 */
 	public function handleRequest(SS_HTTPRequest $request, DataModel $model = NULL) {
 		$body = parent::handleRequest($request, $model);

code/model/SiteConfig.php

@@ -3,6 +3,17 @@
 /**
  * Sitewide configuration.
  *
+ * @property string Title Title of the website.
+ * @property string Tagline Tagline of the website.
+ * @property string Theme Current theme.
+ * @property string CanViewType Type of restriction used for view permissions.
+ * @property string CanEditType Type of restriction used for edit permissions.
+ * @property string CanCreateTopLevelType Type of restriction used for creation of root-level pages.
+ *
+ * @method ManyManyList ViewerGroups() List of groups that can view SiteConfig.
+ * @method ManyManyList EditorGroups() List of groups that can edit SiteConfig.
+ * @method ManyManyList CreateTopLevelGroups() List of groups that can create root-level pages.
+ *
  * @author Tom Rix
  * @package cms
  */
@@ -206,7 +217,6 @@ class SiteConfig extends DataObject implements PermissionProvider {
 	/**
 	 * Create SiteConfig with defaults from language file.
 	 * 
-	 * @param string $locale
 	 * @return SiteConfig
 	 */
 	static public function make_site_config() {

code/model/SiteTree.php

@@ -11,6 +11,28 @@
  * The full path is constructed via {@link Link()}, {@link RelativeLink()} and {@link AbsoluteLink()}.
  * You can allow these segments to contain multibyte characters through {@link URLSegmentFilter::$default_allow_multibyte}.
  *
+ * @property integer ID ID of the SiteTree object.
+ * @property string URLSegment
+ * @property string Title
+ * @property string MenuTitle
+ * @property string Content HTML content of the page.
+ * @property string MetaDescription
+ * @property string ExtraMeta
+ * @property string ShowInMenus
+ * @property string ShowInSearch
+ * @property string Sort Integer value denoting the sort order.
+ * @property string HasBrokenFile
+ * @property string HasBrokenLink
+ * @property string ReportClass
+ * @property string CanViewType Type of restriction for viewing this object.
+ * @property string CanEditType Type of restriction for editing this object.
+ *
+ * @method ManyManyList LinkTracking() List of site pages linked on this page.
+ * @method ManyManyList ImageTracking() List of Images linked on this page.
+ * @method ManyManyList ViewerGroups() List of groups that can view this object.
+ * @method ManyManyList EditorGroups() List of groups that can edit this object.
+ * @method ManyManyList BackLinkTracking() List of site pages that link to this page.
+ *
  * @package cms
  */
 class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvider,CMSPreviewable {
@@ -407,7 +429,10 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	/**
 	 * Replace a "[sitetree_link id=n]" shortcode with a link to the page with the corresponding ID.
 	 *
-	 * @return string
+	 * @param array $arguments
+	 * @param mixed $content
+	 * @param object|null $parser
+	 * @return string|void
 	 */
 	static public function link_shortcode_handler($arguments, $content = null, $parser = null) {
 		if(!isset($arguments['id']) || !is_numeric($arguments['id'])) return;
@@ -615,6 +640,7 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	 * Create a duplicate of this node. Doesn't affect joined data - create a
 	 * custom overloading of this if you need such behaviour.
 	 *
+	 * @param bool $doWrite
 	 * @return SiteTree The duplicated object.
 	 */
 	 public function duplicate($doWrite = true) {
@@ -677,9 +703,9 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	 *
 	 * @param int $maxDepth The maximum depth to traverse.
 	 * @param boolean $unlinked Do not make page names links
-	 * @param string $stopAtPageType ClassName of a page to stop the upwards traversal.
+	 * @param boolean|string $stopAtPageType ClassName of a page to stop the upwards traversal.
 	 * @param boolean $showHidden Include pages marked with the attribute ShowInMenus = 0
-	 * @return string The breadcrumb trail.
+	 * @return HTMLText The breadcrumb trail.
 	 */
 	public function Breadcrumbs($maxDepth = 20, $unlinked = false, $stopAtPageType = false, $showHidden = false) {
 		$page = $this;
@@ -737,7 +763,7 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	 * "grandparent - parent - page".
 	 *
 	 * @param int $level The maximum amount of levels to traverse.
-	 * @param string $seperator Seperating string
+	 * @param string $separator Seperating string
 	 * @return string The resulting string
 	 */
 	public function NestedTitle($level = 2, $separator = " - ") {
@@ -800,6 +826,7 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	 * @uses canEdit()
 	 * @uses $allowed_children
 	 *
+	 * @param Member|int|null $member
 	 * @return boolean True if the current user can add children.
 	 */
 	public function canAddChildren($member = null) {
@@ -831,6 +858,7 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	 * @uses DataExtension->canView()
 	 * @uses ViewerGroups()
 	 *
+	 * @param Member|int|null $member
 	 * @return boolean True if the current user can view this page.
 	 */
 	public function canView($member = null) {
@@ -1073,9 +1101,9 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	 * Pre-populate the cache of canEdit, canView, canDelete, canPublish permissions.
 	 * This method will use the static can_(perm)_multiple method for efficiency.
 	 * 
-	 * @param $permission String The permission: edit, view, publish, approve, etc.
-	 * @param $ids array An array of page IDs
-	 * @param $batchCallBack The function/static method to call to calculate permissions.  Defaults
+	 * @param string $permission The permission: edit, view, publish, approve, etc.
+	 * @param array $ids An array of page IDs
+	 * @param callback|null $batchCallback The function/static method to call to calculate permissions.  Defaults
 	 * to 'SiteTree::can_(permission)_multiple'
 	 */
 	static public function prepopulate_permission_cache($permission = 'CanEditType', $ids, $batchCallback = null) {
@@ -1220,9 +1248,10 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	/**
 	 * Get the 'can edit' information for a number of SiteTree pages.
 	 * 
-	 * @param An array of IDs of the SiteTree pages to look up.
-	 * @param useCached Return values from the permission cache if they exist.
-	 * @return A map where the IDs are keys and the values are booleans stating whether the given
+	 * @param array $ids An array of IDs of the SiteTree pages to look up.
+	 * @param int $memberID ID of member.
+	 * @param bool $useCached Return values from the permission cache if they exist.
+	 * @return array A map where the IDs are keys and the values are booleans stating whether the given
 	 * page can be edited.
 	 */
 	static public function can_edit_multiple($ids, $memberID, $useCached = true) {
@@ -1231,8 +1260,10 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 
 	/**
 	 * Get the 'can edit' information for a number of SiteTree pages.
-	 * @param An array of IDs of the SiteTree pages to look up.
-	 * @param useCached Return values from the permission cache if they exist.
+	 * @param array $ids An array of IDs of the SiteTree pages to look up.
+	 * @param int $memberID ID of member.
+	 * @param bool $useCached Return values from the permission cache if they exist.
+	 * @return array
 	 */
 	static public function can_delete_multiple($ids, $memberID, $useCached = true) {
 		$deletable = array();
@@ -1304,6 +1335,7 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	 *                          will be called $item
 	 * @param array $collator An array, passed by reference, to collect all
 	 *                        of the matching descendants.
+	 * @return true|void
 	 */
 	public function collateDescendants($condition, &$collator) {
 		if($children = $this->Children()) {
@@ -1322,8 +1354,6 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	 * @todo Move <title> tag in separate getter for easier customization and more obvious usage
 	 * 
 	 * @param boolean|string $includeTitle Show default <title>-tag, set to false for custom templating
-	 * @param boolean $includeTitle Show default <title>-tag, set to false for
-	 *                              custom templating
 	 * @return string The XHTML metatags
 	 */
 	public function MetaTags($includeTitle = true) {
@@ -1705,7 +1735,8 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	 * Returns the pages that depend on this page.
 	 * This includes virtual pages, pages that link to it, etc.
 	 * 
-	 * @param $includeVirtuals Set to false to exlcude virtual pages.
+	 * @param bool $includeVirtuals Set to false to exlcude virtual pages.
+	 * @return ArrayList
 	 */
 	public function DependentPages($includeVirtuals = true) {
 		if(class_exists('Subsite')) {
@@ -1760,7 +1791,8 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	 * 
 	 * @deprecated 3.1 Use DependentPages()->Count() instead.
 	 *
-	 * @param $includeVirtuals Set to false to exlcude virtual pages.
+	 * @param bool $includeVirtuals Set to false to exlcude virtual pages.
+	 * @return ArrayList
 	 */
 	public function DependentPagesCount($includeVirtuals = true) {
 		Deprecation::notice('3.1', 'Use SiteTree->DependentPages()->Count() instead.');
@@ -2090,7 +2122,7 @@ class SiteTree extends DataObject implements PermissionProvider,i18nEntityProvid
 	/**
 	 *
 	 * @param boolean $includerelations a boolean value to indicate if the labels returned include relation fields
-	 * 
+	 * @return array|string
 	 */
 	public function fieldLabels($includerelations = true) {
 		$cacheKey = $this->class . '_' . $includerelations;

code/model/SiteTreeFileExtension.php

@@ -20,7 +20,11 @@ class SiteTreeFileExtension extends DataExtension {
 	/**
 	 * Extend through {@link updateBackLinkTracking()} in your own {@link Extension}.
 	 *
-	 * @return ComponentSet
+	 * @param string|array $filter
+	 * @param string $sort
+	 * @param string $join
+	 * @param string $limit
+	 * @return ManyManyList
 	 */
 	public function BackLinkTracking($filter = "", $sort = "", $join = "", $limit = "") {
 		if(class_exists("Subsite")){

code/model/VirtualPage.php

@@ -413,6 +413,7 @@ class VirtualPage extends Page {
 	 *
 	 * @param string $method 
 	 * @param string $args
+	 * @return mixed
 	 */
 	public function __call($method, $args) {
 		if(parent::hasMethod($method)) {
@@ -422,6 +423,10 @@ class VirtualPage extends Page {
 		}
 	}
 
+	/**
+	 * @param string $field
+	 * @return bool
+	 */
 	public function hasField($field) {
 		return (
 			array_key_exists($field, $this->record) 
@@ -519,6 +524,9 @@ class VirtualPage_Controller extends Page_Controller {
 	 *
 	 * @param string $method 
 	 * @param string $args
+	 * @return mixed
+	 *
+	 * @throws Exception Any error other than a 'no method' error.
 	 */
 	public function __call($method, $args) {
 		try {