MINOR Documentation (from r104795)

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

core/model/DataObject.php

@@ -2316,6 +2316,7 @@ public static function has_own_table($dataClass) {
 
 	/**
 	 * Returns true if the member is allowed to do the given action.
+	 * See {@link extendedCan()} for a more versatile tri-state permission control.
 	 *
 	 * @param string $perm The permission to be checked, such as 'View'.
 	 * @param Member $member The member whose permissions need checking.  Defaults to the currently logged
@@ -2383,17 +2384,23 @@ function can($perm, $member = null) {
 
 	/**
 	 * Process tri-state responses from permission-alterting decorators.  The decorators are
-	 * expected to return one of 3 values
+	 * expected to return one of three values:
 	 * 
 	 *  - false: Disallow this permission, regardless of what other decorators say
 	 *  - true: Allow this permission, as long as no other decorators return false
 	 *  - NULL: Don't affect the outcome
 	 * 
 	 * This method itself returns a tri-state value, and is designed to be used like this:
 	 *
+	 * <code>
 	 * $extended = $this->extendedCan('canDoSomething', $member);
 	 * if($extended !== null) return $extended;
 	 * else return $normalValue;
+	 * </code>
+	 * 
+	 * @param String $methodName Method on the same object, e.g. {@link canEdit()}
+	 * @param Member|int $member
+	 * @return boolean|null
 	 */
 	public function extendedCan($methodName, $member) {
 		$results = $this->extend($methodName, $member);
@@ -2406,8 +2413,12 @@ public function extendedCan($methodName, $member) {
 		}
 		return null;
 	}
+
 	/**
 	 * Helper functon for extendedCan
+	 * 
+	 * @param Mixed $value
+	 * @return boolean
 	 */
 	private function isNotNull($value) {
 		return !is_null($value);