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 @@ class ArrayLib extends Object {
 		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 @@ class ClassInfo {
 		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 @@ class ClassInfo {
 		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 @@ class ClassInfo {
 		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
@@ -19,6 +19,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 @@ class Controller extends ViewableData {
 		return $this->response;
 	}
 
+	protected $baseInitCalled = false;
+
 	/**
 	 * Executes this controller, and return an {@link HTTPResponse} object with the result.
 	 * 
@@ -96,8 +98,6 @@ class Controller extends ViewableData {
 	 * 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.
@@ -105,7 +105,6 @@ class Controller extends ViewableData {
 	 * @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 @@ class Controller extends ViewableData {
 		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 @@ class Controller extends ViewableData {
 	}
   
 	/**
-	 * 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 @@ class Controller extends ViewableData {
 	 * @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 @@ class Controller extends ViewableData {
 
 	/**
 	 * 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 @@ class Controller extends ViewableData {
 	}
 	
 	/**
-	 * 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 @@ class Controller extends ViewableData {
 	}
 	
 	/**
-	 * 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 @@ class Controller extends ViewableData {
 			$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;
 		}

core/control/Director.php

@@ -149,6 +149,10 @@ class Director {
 	}
 		
 		
+	/**
+	 * Returns the controller that should be used to handle the given URL.
+	 * @todo More information about director rules.
+	 */
 	static function getControllerForURL($url) {
 		if(isset($_GET['debug_profile'])) Profiler::mark("Director","getControllerForURL");
 		$url = preg_replace( array( '/\/+/','/^\//', '/\/$/'),array('/','',''),$url);
@@ -214,15 +218,24 @@ class Director {
 		}
 	}
 
-
+	/**
+	 * Returns the urlParam with the given name
+	 */
 	static function urlParam($name) {
 		return Director::$urlParams[$name];
 	}
 	
+	/**
+	 * Returns an array of urlParams
+	 */
 	static function urlParams() {
 		return Director::$urlParams;
 	}
 
+	/**
+	 * Returns the dataobject of the current page.
+	 * This will only return a value if you are looking at a SiteTree page
+	 */
 	static function currentPage() {
 		if(isset(Director::$urlParams['URLSegment'])) {
 			$SQL_urlSegment = Convert::raw2sql(Director::$urlParams['URLSegment']);
@@ -236,7 +249,10 @@ class Director {
 		}
 	}
 
-
+	/**
+	 * Turns the given URL into an absolute URL.
+	 * @todo Document how relativeToSiteBase works
+	 */
 	static function absoluteURL($url, $relativeToSiteBase = false) {
 		if(strpos($url,'/') === false && !$relativeToSiteBase) $url = dirname($_SERVER['REQUEST_URI'] . 'x') . '/' . $url;
 
@@ -248,6 +264,9 @@ class Director {
 		return $url;
 	}
 
+	/**
+	 * Returns the part of the URL, 'http://www.mysite.com'.
+	 */
 	static function protocolAndHost() {
 		if(self::$alternateBaseURL) {
 			if(preg_match('/^(http[^:]*:\/\/[^/]+)\//1', self::$alternateBaseURL, $matches)) {
@@ -314,12 +333,16 @@ class Director {
 		Director::redirect($url);
 	}
 
+	/**
+	 * @deprecated This seems like a bit of a hack; is it used anywhere?
+	 */
 	static function currentURLSegment() {
 		return Director::$urlSegment;
 	}
 
 	/**
 	 * Returns a URL to composed of the given segments - usually controller, action, parameter
+	 * @deprecated This function has little value.  Just craft links yourself.
 	 */
 	static function link() {
 		$parts = func_get_args();
@@ -327,7 +350,8 @@ class Director {
 	}
 
 	/**
-	 * Returns a URL for the given controller
+	 * Returns the root URL for the site.
+	 * It will be automatically calculated unless it is overridden with {@link setBaseURL()}.
 	 */
 	static function baseURL() {
 		if(self::$alternateBaseURL) return self::$alternateBaseURL;
@@ -338,18 +362,35 @@ class Director {
 		}
 	}
 	
+	/**
+	 * Sets the root URL for the website.
+	 * If the site isn't accessible from the URL you provide, weird things will happen.
+	 */
 	static function setBaseURL($baseURL) {
 		self::$alternateBaseURL = $baseURL;
 	}
 
+	/**
+	 * Returns the root filesystem folder for the site.
+	 * It will be automatically calculated unless it is overridden with {@link setBaseFolder()}.
+	 */
 	static function baseFolder() {
 		if(self::$alternateBaseFolder) return self::$alternateBaseFolder;
 		else return dirname(dirname($_SERVER['SCRIPT_FILENAME']));
 	}
+
+	/**
+	 * Sets the root folder for the website.
+	 * If the site isn't accessible from the folder you provide, weird things will happen.
+	 */
 	static function setBaseFolder($baseFolder) {
 		self::$alternateBaseFolder = $baseFolder;
 	}
 
+	/**
+	 * Turns an absolute URL or folder into one that's relative to the root of the site.
+	 * This is useful when turning a URL into a filesystem reference, or vice versa.
+	 */
 	static function makeRelative($url) {
 		$base1 = self::absoluteBaseURL();
 		$base2 = self::baseFolder();
@@ -362,26 +403,39 @@ class Director {
 		return $url;
 	}
 
+	/**
+	 * @deprecated This method's behaviour isn't very useful or consistent.
+	 */
 	static function getAbsURL($url) {
 		return Director::baseURL() . $url;
 	}
 
+	/**
+	 * Given a filesystem reference relative to the site root, return the full filesystem path
+	 */
 	static function getAbsFile($file) {
 		if($file[0] == '/') return $file;
 		return Director::baseFolder() . '/' . $file;
 	}
 	
+	/**
+	 * Returns true if the given file exists.
+	 * @param $file Filename specified relative to the site root
+	 */
 	static function fileExists($file) {
 		return file_exists(Director::getAbsFile($file));
 	}
 
 	/**
-	 * Returns the Absolute URL for the given controller
+	 * Returns the Absolute URL of the site root.
 	 */
 	 static function absoluteBaseURL() {
 	 	return Director::absoluteURL(Director::baseURL());
 	 }
 	 
+	/**
+	 * Returns the Absolute URL of the site root, embedding the current basic-auth credentials into the URL.
+	 */
 	 static function absoluteBaseURLWithAuth() {
 	 	if($_SERVER['PHP_AUTH_USER'])
 			$login = "$_SERVER[PHP_AUTH_USER]:$_SERVER[PHP_AUTH_PW]@";
@@ -391,7 +445,12 @@ class Director {
 	 }
 
 	/**
-	 * Force the site to run on SSL.  To use, call from _config.php
+	 * Force the site to run on SSL.  To use, call from _config.php.
+	 * 
+	 * For example:
+	 * <code>
+	 * if(Director::isLive()) Director::forceSSL();
+	 * </code>
 	 */
 	static function forceSSL() {
 		if(!isset($_SERVER['HTTPS']) && !Director::isDev()){
@@ -403,7 +462,7 @@ class Director {
 	}
 
 	/**
-	 * Force a redirect to www.domain
+	 * Force a redirect to a domain starting with "www."
 	 */
 	static function forceWWW() {
 		if(!Director::isDev() && !Director::isTest() && strpos( $_SERVER['SERVER_NAME'], 'www') !== 0 ){
@@ -449,8 +508,7 @@ class Director {
 	////////////////////////////////////////////////////////////////////////////////////////////
 
 	/**
-	 * Sets the site mode (if it is the public site or the cms),
+	 * Sets the site mode (if it is the public site or the cms), and runs registered modules.
-	 * and runs registered modules.
 	 * 
 	 * @param string $mode 'site' or 'cms' 
 	 */