Added return type hinting to comments

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@40596 467b73ca-7a2a-4603-9d3b-597d59a354a9

core/control/Controller.php

@@ -38,6 +38,9 @@ class Controller extends ViewableData {
 		$this->urlParams = $urlParams;
 	}
 	
+	/**
+	 * @return
+	 */
 	function getURLParams() {
 		return $this->urlParams;
 	}
@@ -46,8 +49,10 @@ class Controller extends ViewableData {
 	 * 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
 	 */
 	protected $baseInitCalled = false;
 	function run($requestParams) {
@@ -214,6 +219,7 @@ class Controller extends ViewableData {
 	
 	/**
 	 * Return an SSViewer object to process the data
+	 * @return SSViewer The viewer identified being the default handler for this Controller/Action combination
 	 */
 	function getViewer($action) {
 		// Hard-coded templates
@@ -270,12 +276,17 @@ class Controller extends ViewableData {
 		$this->baseInitCalled = true;
 	}
 
+	/**
+	 * Deprecated - use Controller::curr() instead
+	 * @returns Controller
+	 */
 	public static function currentController() {
 		return self::curr();
 	}
 	
 	/**
 	 * Returns the current controller
+	 * @returns Controller
 	 */
 	public static function curr() {
 		if(Controller::$controller_stack) {
@@ -287,6 +298,7 @@ class Controller extends ViewableData {
 	
 	/**
 	 * Tests whether we have a currently active controller or not
+	 * @return boolean True if there is at least 1 controller in the stack.
 	 */
 	public static function has_curr() {
 		return Controller::$controller_stack ? true : false;
@@ -297,6 +309,7 @@ class Controller extends ViewableData {
 	 * @param perm The permission to be checked, such as 'View'.
 	 * @param member The member whose permissions need checking.  Defaults to the currently logged
 	 * in user.
+	 * @return boolean
 	 */
 	function can($perm, $member = null) {
 		if(!$member) $member = Member::currentUser();
@@ -312,6 +325,7 @@ class Controller extends ViewableData {
 	/**
 	 * returns a date object for use within a template
 	 * Usage: $Now.Year - Returns 2006
+	 * @return Date The current date
 	 */
 	function Now() {
 		$d = new Date(null);
@@ -339,6 +353,7 @@ class Controller extends ViewableData {
 	
 	/**
 	 * Returns true if the visitor has been here before
+	 * @return boolean
 	 */
 	function PastVisitor() {
 		return Cookie::get("PastVisitor") ? true : false;
@@ -346,6 +361,7 @@ class Controller extends ViewableData {
 	 
 	/**
 	 * Return true if the visitor has signed up for a login account before
+	 * @return boolean
 	 */
 	function PastMember() {
 		return Cookie::get("PastMember") ? true : false;
@@ -390,6 +406,7 @@ class Controller extends ViewableData {
 	
 	/**
 	 * Get the Session object representing this Controller's session
+	 * @return Session
 	 */
 	function getSession() {
 		return $this->session;
@@ -404,6 +421,7 @@ class Controller extends ViewableData {
 	
 	/**
 	 * Returns true if this controller is processing an ajax request
+	 * @return boolean True if this controller is processing an ajax request
 	 */
 	function isAjax() {
 		return (

forms/Form.php

@@ -129,10 +129,17 @@ class Form extends ViewableData {
 			$this->validator->removeValidation();
 	}
 	
+	/**
+	 * Get the {@link Validator} attached to this form.
+	 * @return Validator
+	 */
 	function getValidator() {
 		return $this->validator;
 	}
 
+	/**
+	 * Set the {@link Validator} on this form.
+	 */
 	function setValidator( Validator $validator ) {
 		if($validator) {
 			$this->validator = $validator;
@@ -140,6 +147,9 @@ class Form extends ViewableData {
 		}
 	}
 
+	/**
+	 * Remove the {@link Validator} from this from.
+	 */
 	function unsetValidator(){
 		$this->validator = null;
 	}
@@ -161,10 +171,18 @@ class Form extends ViewableData {
 	
 	/**
 	 * Return the form's fields - used by the templates
+	 * @return FieldSet The form fields
 	 */
 	function Fields() {
 	  return $this->fields;
 	}
+	
+	/**
+	 * Get a named field from this form's fields.
+	 * It will traverse into composite fields for you, to find the field you want.
+	 * It will only return a data field.
+	 * @return FormField
+	 */
 	function dataFieldByName($name) {
 		return $this->fields->dataFieldByName($name);
 	}
@@ -172,6 +190,7 @@ class Form extends ViewableData {
 	
 	/**
 	 * Return the form's action buttons - used by the templates
+	 * @return FieldSet The action list
 	 */
 	function Actions() {
 		return $this->actions;
@@ -220,6 +239,7 @@ class Form extends ViewableData {
 	
 	/**
 	 * Return the attributes of the form tag - used by the templates
+	 * @return string The attribute string
 	 */
 	function FormAttributes() {
 		// Forms shouldn't be cached, cos their error messages won't be shown
@@ -242,6 +262,11 @@ class Form extends ViewableData {
     $this->target = $target;
   }
 
+	/**
+	 * Returns the encoding type of the form.
+	 * This will be either multipart/form-data - if there are field fields - or application/x-www-form-urlencoded
+	 * @return string The encoding mime type
+	 */
 	function FormEncType() {
 		if(is_array($this->fields->dataFields())){
 			foreach($this->fields->dataFields() as $field) {
@@ -251,14 +276,27 @@ class Form extends ViewableData {
 		return "application/x-www-form-urlencoded";
 	}
 	
+	/**
+	 * Returns the form method.
+	 * @return string 'get' or 'post'
+	 */
 	function FormMethod() {
 		return $this->formMethod;
 	}
+	
+	/**
+	 * Set the form method - get or post
+	 */
 	function setFormMethod($method) {
 		$this->formMethod = strtolower($method);
 		if($this->formMethod == 'get') $this->fields->push(new HiddenField('executeForm', '', $this->name));
 	}
 	
+	/**
+	 * Return the form's action attribute.
+	 * This is build by adding an executeForm get variable to the parent controller's Link() value
+	 * @return string The
+	 */
 	function FormAction() {
 		// "get" form needs ?executeForm added as a hidden field
 		if($this->formMethod == 'post') {
@@ -282,6 +320,7 @@ class Form extends ViewableData {
 	/**
 	 * Returns the field referenced by $_GET[fieldName].
 	 * Used for embedding entire extra helper forms inside complex field types (such as ComplexTableField)
+	 * @return FormField The field referenced by $_GET[fieldName]
 	 */
 	function ReferencedField() {
 		return $this->dataFieldByName($_GET['fieldName']);
@@ -350,6 +389,11 @@ class Form extends ViewableData {
 	}
 	
 	protected $record;
+	
+	/**
+	 * Returns the DataObject that has given this form its data.
+	 * @return DataObject
+	 */
 	function getRecord() {
 		return $this->record;
 	}
@@ -642,6 +686,10 @@ class Form extends ViewableData {
 	// TESTING HELPERS
 	//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 	
+	/**
+	 * Test a submission of this form.
+	 * @return HTTPResponse the response object that the handling controller produces.  You can interrogate this in your unit test.
+	 */
 	function testSubmission($action, $data) {
 		$data['action_' . $action] = true;
 		$data['executeForm'] = $this->name;
@@ -652,6 +700,10 @@ class Form extends ViewableData {
 		//return $response;
 	}
 	
+	/**
+	 * Test an ajax submission of this form.
+	 * @return HTTPResponse the response object that the handling controller produces.  You can interrogate this in your unit test.
+	 */
 	function testAjaxSubmission($action, $data) {
 		$data['ajax'] = 1;
 		return $this->testSubmission($action, $data);