Improving API documentation

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

api/RSSFeed.php

@@ -9,6 +9,7 @@
  * RSSFeed class
  *
  * This class is used to create an RSS feed.
+ * @todo Improve documentation
  * @package sapphire
  * @subpackage integration
  */

api/SapphireSoapServer.php

@@ -7,6 +7,7 @@
 
 /**
  * Soap server class
+ * @todo Improve documentation
  * @package sapphire
  * @subpackage integration
  */

cli/DailyTask.php

@@ -7,6 +7,7 @@
 
 /**
  * Classes that must be run daily extend this class
+ * @todo Improve documentation
  * @package sapphire
  * @subpackage cron
  */

cli/ScheduledTask.php

@@ -7,6 +7,7 @@
 
 /**
  * Abstract task representing scheudled tasks
+ * @todo Improve documentation
  * @package sapphire
  * @subpackage cron
  */

core/ArrayLib.php

@@ -35,6 +35,9 @@ static function valuekey($arr) {
 		return $newArr;
 	}
 
+	/**
+	 * @todo Improve documentation
+	 */
 	static function array_values_recursive($arr) {
 	   $lst = array();
 	   foreach(array_keys($arr) as $k){

core/ClassInfo.php

@@ -21,14 +21,26 @@ static function ready() {
 		global $_ALL_CLASSES;
 		return $_ALL_CLASSES && $_ALL_CLASSES['hastable'];
 	}
+
+	/**
+	 * @todo Improve documentation
+	 */
 	static function allClasses() {
 		global $_ALL_CLASSES;
 		return $_ALL_CLASSES['exists'];
 	}
+
+	/**
+	 * @todo Improve documentation
+	 */
 	static function exists($class) {
 		global $_ALL_CLASSES;
 		return isset($_ALL_CLASSES['exists'][$class]) ? $_ALL_CLASSES['exists'][$class] : null;
 	}
+
+	/**
+	 * @todo Improve documentation
+	 */
 	static function hasTable($class) {
 		global $_ALL_CLASSES;
 		return isset($_ALL_CLASSES['hastable'][$class]) ? $_ALL_CLASSES['hastable'][$class] : null;
@@ -90,6 +102,9 @@ static function baseDataClass($class) {
 		return $baseDataClass ? $baseDataClass : $class;
 	}
 
+	/**
+	 * @todo Improve documentation
+	 */
 	static function subclassesFor($class){
 		global $_ALL_CLASSES;
 		$subclasses = isset($_ALL_CLASSES['children'][$class]) ? $_ALL_CLASSES['children'][$class] : null;
@@ -98,6 +113,9 @@ static function subclassesFor($class){
 		return $subclasses;
 	}
 
+	/**
+	 * @todo Improve documentation
+	 */
 	static function ancestry($class, $onlyWithTables = false) {
 		global $_ALL_CLASSES;
 

core/control/ContentController.php

@@ -6,7 +6,7 @@
  */
 
 /**
- * The most common kind if controller; effectively a controller linked to a {@link DataObject}.
+ * The most common kind of controller; effectively a controller linked to a {@link DataObject}.
  *
  * ContentControllers are most useful in the content-focused areas of a site.  This is generally
  * the bulk of a site; however, they may be less appropriate in, for example, the user management
@@ -18,6 +18,8 @@
  *
  * Subclasses of ContentController are generally instantiated by ModelAsController; this will create
  * a controller based on the URLSegment action variable, by looking in the SiteTree table.
+ * 
+ * @todo Can this be used for anything other than SiteTree controllers?
  *
  * @package sapphire
  * @subpackage control

core/control/ContentNegotiator.php

@@ -7,6 +7,8 @@
 /**
  * The content negotiator performs text/html or application/xhtml+xml switching.
  * It does this through the static function ContentNegotiator::process()
+ * 
+ * @todo Improve documentation
  * @package sapphire
  * @subpackage control
  */

core/control/Controller.php

@@ -75,6 +75,8 @@ function getResponse() {
 		return $this->response;
 	}
 
+	protected $baseInitCalled = false;
+
 	/**
 	 * Executes this controller, and return an {@link HTTPResponse} object with the result.
 	 * 
@@ -96,16 +98,13 @@ function getResponse() {
 	 * 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 $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) {
 		if(isset($_GET['debug_profile'])) Profiler::mark("Controller", "run");		
 		$this->pushCurrent();
@@ -292,10 +291,17 @@ function run($requestParams) {
 		return $this->response;
 	}
 
+	/**
+	 * This is the default action handler used if a method doesn't exist.
+	 * It will process the controller object with the template returned by {@link getViewer()}
+	 */
 	function defaultAction($action) {
 		return $this->getViewer($action)->process($this);
 	}
 
+	/**
+	 * Returns the action that is being executed on this controller.
+	 */
 	function getAction() {
 		return $this->action;
 	}
@@ -330,8 +336,9 @@ function getViewer($action) {
 	}
 
 	/**
-	 * Call this to disable basic authentication on test sites
+	 * Call this to disable basic authentication on test sites.
 	 * must be called in the init() method
+	 * @deprecated Use BasicAuth::disable() instead?  This is used in CliController - it should be updated.
 	 */
 	function disableBasicAuth() {
 		$this->basicAuthEnabled = false;
@@ -394,6 +401,7 @@ public static function has_curr() {
 	 * @param member The member whose permissions need checking.  Defaults to the currently logged
 	 * in user.
 	 * @return boolean
+	 * @deprecated I don't believe that the system has widespread use/support of this.
 	 */
 	function can($perm, $member = null) {
 		if(!$member) $member = Member::currentUser();
@@ -419,11 +427,15 @@ function Now() {
 
 	/**
 	 * Returns a link to any other page
+	 * @deprecated It's unclear what value this has; construct a link manually or use your own custom link-gen functions.
 	 */
 	function LinkTo($a, $b) {
 		return Director::baseURL() . $a . '/' . $b;
 	}
 
+	/**
+	 * Returns an absolute link to this controller
+	 */
 	function AbsoluteLink() {
 		return Director::absoluteURL($this->Link());
 	}
@@ -480,7 +492,8 @@ function popCurrent() {
 	}
 
 	/**
-	 * Handle redirection
+	 * Redirct to the given URL.
+	 * It is generally recommended to call Director::redirect() rather than calling this function directly.
 	 */
 	function redirect($url) {
 		if($this->response->getHeader('Location')) {
@@ -530,7 +543,8 @@ function isAjax() {
 	}
 
 	/**
-	 * Check thAT
+	 * Check that the given action is allowed to be called on this controller.
+	 * This method is called by run() and makes use of {@link self::$allowed_actions}.
 	 */
 	function checkAccessAction($action) {
 		// Collate self::$allowed_actions from this class and all parent classes
@@ -547,7 +561,7 @@ function checkAccessAction($action) {
 			$className = get_parent_class($className);
 		}
 
-		if($access === null || $accessParts[0] === $accessParts[1]) {
+		if($access === null || (sizeof($accessParts) > 1 && $accessParts[0] === $accessParts[1])) {
 			// user_error("Deprecated: please define static \$allowed_actions on your Controllers for security purposes", E_USER_NOTICE);
 			return true;
 		}