Documentation consistency update. Part 2: toolkit/

symphony/lib/toolkit/class.administrationpage.php

@@ -710,13 +710,17 @@ public function __buildNavigation(){
 
 			}
 
-			####
-			# Delegate: ExtensionsAddToNavigation
-			# Description: After building the Navigation properties array. This is specifically
-			# 			for extensions to add their groups to the navigation or items to groups,
-			# 			already in the navigation. Note: THIS IS FOR ADDING ONLY! If you need
-			#			to edit existing navigation elements, use the 'NavigationPreRender' delegate.
-			# Global: Yes
+			/**
+             * After building the Navigation properties array. This is specifically
+			 * for extensions to add their groups to the navigation or items to groups,
+			 * already in the navigation. Note: THIS IS FOR ADDING ONLY! If you need
+             * to edit existing navigation elements, use the `NavigationPreRender` delegate.
+             * 
+             * @delegate ExtensionsAddToNavigation
+             * @param string $context
+             * '/backend/'
+             * @param array $navigation
+             */
 			Administration::instance()->ExtensionManager->notifyMembers(
 				'ExtensionsAddToNavigation', '/backend/', array('navigation' => &$nav)
 			);
@@ -870,7 +874,7 @@ public function __fetchAvailablePageTypes(){
 		 * @param XMLElement $element
 		 *	The element that should be wrapped with an error
 		 * @param string $message
-		 *	The text for this error. This will be appended after the $element,
+		 *	The text for this error. This will be appended after the `$element`,
 		 *  but inside the wrapping `<div>`
 		 */
 		public function wrapFormElementWithError($element, $message = null){

symphony/lib/toolkit/class.ajaxpage.php

@@ -50,14 +50,14 @@
 
 		/**
 		 * The HTTP status code of the page using the AJAXPage constants
-		 * STATUS_OK, STATUS_BAD, STATUS_ERROR or STATUS_UNAUTHORISED
+		 * `STATUS_OK`, `STATUS_BAD`, `STATUS_ERROR` or `STATUS_UNAUTHORISED`
 		 * @var integer
 		 */
 		protected $_status;
 
 		/**
-		 * The constructor for AJAXPage. This sets the page status to STATUS_OK,
-		 * the default content type to text/xml and initialises the $_Result var
+		 * The constructor for AJAXPage. This sets the page status to `STATUS_OK`,
+		 * the default content type to text/xml and initialises `$this->_Result`
 		 * with an XMLElement. The constructor also starts the Profiler for this
 		 * page template.
 		 *
@@ -82,7 +82,7 @@ public function __construct(&$parent){
 
 		/**
 		 * This function is called when a user is not authenticated to the Symphony
-		 * backend. It sets the status of this page to STATUS_UNAUTHORISED and
+		 * backend. It sets the status of this page to `STATUS_UNAUTHORISED` and
 		 * appends a message for generation
 		 */
 		public function handleFailedAuthorisation(){
@@ -105,9 +105,9 @@ public function build($context = null){
 
 		/**
 		 * The generate functions outputs the correct headers for
-		 * this AJAXPage, adds the $_status code to the root attribute
+		 * this AJAXPage, adds `$this->_status` code to the root attribute
 		 * before calling the parent generate function and generating
-		 * the $Result XMLElement
+		 * the `$this->_Result` XMLElement
 		 *
 		 * @return string
 		 */
@@ -140,10 +140,10 @@ public function generate(){
 		/**
 		 * All classes that extend the AJAXPage class must define a view method
 		 * which contains the logic for the content of this page. The resulting HTML
-		 * is append to $_Result where it is generated on build
+		 * is append to `$this->_Result` where it is generated on build
 		 *
 		 * @see build()
 		 */
 		abstract public function view();
 
-	}
+	}

symphony/lib/toolkit/class.alert.php

@@ -41,7 +41,7 @@
 
 		/**
 		 * The Alert constant to represent the style that this alert should
-		 * take on. Defaults to NOTICE.
+		 * take on. Defaults to `Alert::NOTICE`.
 		 * @var string
 		 */
 		private $_type;
@@ -54,7 +54,7 @@
 		 *  This text will be displayed to the user
 		 * @param string $type
 		 *  The type of alert this is. Defaults to NOTICE, available
-		 *  values are Alert::NOTICE, Alert::ERROR, Alert::SUCCESS
+		 *  values are `Alert::NOTICE`, `Alert::ERROR`, `Alert::SUCCESS`
 		 */
 		public function __construct($message, $type = self::NOTICE){
 			$this->message = $message;
@@ -118,4 +118,4 @@ public function asXML(){
 			return $p;
 		}
 
-	}
+	}

symphony/lib/toolkit/class.author.php

@@ -10,7 +10,7 @@
 
 		/**
 		 * An associative array of information relating to this author where
-		 * the keys map directly to the tbl_authors columns.
+		 * the keys map directly to the `tbl_authors` columns.
 		 * @var array
 		 */
 		private $_fields = array();
@@ -23,10 +23,10 @@
 		private $_accessSections = null;
 
 		/**
-		 * Stores a key=>value pair into the Author object's $_field array.
+		 * Stores a key=>value pair into the Author object's `$this->_fields` array.
 		 *
 		 * @param string $field
-		 *  Maps directly to a column in the tbl_authors table.
+		 *  Maps directly to a column in the `tbl_authors` table.
 		 * @param string $value
 		 *  The value for the given $field
 		 */
@@ -35,14 +35,14 @@ public function set($field, $value){
 		}
 
 		/**
-		 * Retrieves the value from the Author object by field from the $_fields
+		 * Retrieves the value from the Author object by field from `$this->_fields`
 		 * array. If field is omitted, all fields are returned.
 		 *
 		 * @param string $field
-		 *  Maps directly to a column in the tbl_authors table. Defaults to null
+		 *  Maps directly to a column in the `tbl_authors` table. Defaults to null
 		 * @return mixed
 		 *  If the field is not set or is empty, returns null.
-		 *  If the field is not provided, returns the $_fields array
+		 *  If the field is not provided, returns the `$this->_fields` array
 		 *  Otherwise returns a string.
 		 */
 		public function get($field = null){
@@ -91,12 +91,12 @@ public function getFullName(){
 		}
 
 		/**
-		 * Creates an author token using the General::hash function and the
+		 * Creates an author token using the `General::hash` function and the
 		 * current Author's username and password. The default hash function
 		 * is SHA1
 		 *
-		 * @see toolkit.General#hash
-		 * @see toolkit.General#substrmin
+		 * @see toolkit.General#hash()
+		 * @see toolkit.General#substrmin()
 		 *
 		 * @return string
 		 */
@@ -106,7 +106,7 @@ public function createAuthToken(){
 
 		/**
 		 * Prior to saving an Author object, the validate function ensures that
-		 * the values in the $_fields array are correct. The function returns
+		 * the values in `$this->_fields` array are correct. The function returns
 		 * boolean, but an errors array is provided by reference to the callee
 		 * function.
 		 *
@@ -153,12 +153,12 @@ public function validate(&$errors){
 
 		/**
 		 * This is the insert method for the Author. This takes the current
-		 * $_fields values and adds them to the database using either the
-		 * AuthorManager::edit or AuthorManager::add functions. An
+		 * `$this->_fields` values and adds them to the database using either the
+		 * `AuthorManager::edit` or `AuthorManager::add` functions. An
 		 * existing user is determined by if an ID is already set.
 		 *
-		 * @see toolkit.AuthorManager#add
-		 * @see toolkit.AuthorManager#edit
+		 * @see toolkit.AuthorManager#add()
+		 * @see toolkit.AuthorManager#edit()
 		 * @return mixed
 		 *  If an new Author was added, an integer of the Author ID will be
 		 *  returned, otherwise boolean to indicate whether the update was
@@ -226,9 +226,9 @@ public function loadAuthor($id){
 		 * This function will load an Author by Username into the current Author object
 		 *
 		 * @deprecated This function will be removed in the next major release. The
-		 *  AuthorManager::fetchByUsername is the preferred way to find Authors by
+		 *  `AuthorManager::fetchByUsername` is the preferred way to find Authors by
 		 *  Username.
-		* @see toolkit.AuthorManager#fetchByUsername
+		* @see toolkit.AuthorManager#fetchByUsername()
 		 * @param string $usernames
 		 *  The Author's username
 		 * @return boolean
@@ -243,4 +243,3 @@ public function loadAuthorFromUsername($username){
 		}
 
 	}
-

symphony/lib/toolkit/class.authormanager.php

@@ -21,8 +21,8 @@
 		 *
 		 * @param array $fields
 		 *  Associative array of field names => values for the Author object
-		 * @return int|boolean
-		 *  Returns an author_id of the created Author on success, false otherwise.
+		 * @return integer|boolean
+		 *  Returns an Author ID of the created Author on success, false otherwise.
 		 */
 		public static function add(Array $fields){
 			if(!Symphony::Database()->insert($fields, 'tbl_authors')) return false;
@@ -33,7 +33,7 @@ public static function add(Array $fields){
 
 		/**
 		 * Given an Author ID and associative array of fields, update an existing Author
-		 * row in the Database's authors table. Returns boolean for success/failure
+		 * row in the `tbl_authors` database table. Returns boolean for success/failure
 		 *
 		 * @param integer $id
 		 *  The ID of the Author that should be updated
@@ -71,7 +71,7 @@ public static function delete($id){
 		 *  The number of rows to return
 		 * @param integer $start
 		 *  The offset start point for limiting, maps to the LIMIT {x}, {y} MySQL functionality
-		 * @return array(Author)
+		 * @return array
 		 *  An array of Author objects.  If no Authors are found, null is returned.
 		 */
 		public static function fetch($sortby = 'id', $sortdirection = 'ASC', $limit = null, $start = null){
@@ -105,10 +105,10 @@ public static function fetch($sortby = 'id', $sortdirection = 'ASC', $limit = nu
 		}
 
 		/**
-		 * The fetchById method returns Author that match the provided ID's with
+		 * The fetchById function returns Author's that match the provided ID's with
 		 * the option to sort or limit the output.
 		 *
-		 * @param int|array $id
+		 * @param integer|array $id
 		 *  A single ID or an array of ID's
 		 * @param string $sortby
 		 *  The field to sort the authors by, defaults to 'id'
@@ -120,8 +120,8 @@ public static function fetch($sortby = 'id', $sortdirection = 'ASC', $limit = nu
 		 * @param integer $start
 		 *  The offset start point for limiting, maps to the LIMIT {x}, {y} MySQL functionality
 		 * @return mixed
-		 *  If $id was an integer, the result will be an Author object, otherwise an array of
-		 *  Author objects will be returned. If no Authors are found, or no $id is given null is returned.
+		 *  If `$id` was an integer, the result will be an Author object, otherwise an array of
+		 *  Author objects will be returned. If no Authors are found, or no `$id` is given null is returned.
 		 */
 		public static function fetchByID($id, $sortby = 'id', $sortdirection = 'ASC', $limit = null, $start = null){
 

symphony/lib/toolkit/class.datasource.php

@@ -15,7 +15,7 @@
 	 * the Dynamic XML datasource allows XML pages to be retrieved. This is especially
 	 * helpful for working with Restful XML API's. Datasources are saved through the
 	 * Symphony backend, which uses a Datasource template defined in
-	 * /symphony/template/datasource.tpl.
+	 * `TEMPLATE . /datasource.tpl`.
 	 */
 	Class DataSource{
 
@@ -63,17 +63,18 @@
 		protected $_force_empty_result = false;
 
 		/**
-		 * Constructor for the datasource sets the parent, and if process_params is set,
-		 * the $env variable as well.
+		 * Constructor for the datasource sets the parent, and if `$process_params` is set,
+		 * the `$env` variable will be run through `Datasource::processParameters`.
 		 *
+         * @see toolkit.Datasource#processParameters()
 		 * @param Administration $parent
 		 *  The Administration object that this page has been created from
 		 *  passed by reference
 		 * @param array $env
 		 *  The environment variables from the Frontend class which includes
 		 *  any params set by Symphony or Events or by other Datasources
 		 * @param boolean $process_params
-		 *  If set to true, the processParameters function will be called. By default
+		 *  If set to true, `Datasource::processParameters` will be called. By default
 		 *  this is true
 		 */
 		public function __construct(&$parent, Array $env = null, $process_params=true){
@@ -150,12 +151,12 @@ public function __determineFilterType($value){
 		}
 
 		/**
-		 * If there is no results to return this function calls __noRecordsFound
+		 * If there is no results to return this function calls `Datasource::__noRecordsFound`
 		 * which appends an XMLElement to the current root element.
 		 *
 		 * @param XMLElement $xml
 		 *  The root element XMLElement for this datasource. By default, this will
-		 *  the handle of the datasource, as defined by dsParamROOTELEMENT
+		 *  the handle of the datasource, as defined by `$this->dsParamROOTELEMENT`
 		 * @return XMLElement
 		 */
 		public function emptyXMLSet(XMLElement $xml = null){
@@ -166,7 +167,7 @@ public function emptyXMLSet(XMLElement $xml = null){
 		}
 
 		/**
-		 * Returns an error XMLElement with a No Records Found text
+		 * Returns an error XMLElement with a 'No records found' text
 		 *
 		 * @return XMLElement
 		 */
@@ -176,8 +177,8 @@ public function __noRecordsFound(){
 
 		/**
 		 * Given a wrapper and an associative array of fields, this function
-		 * will append all the Included Elements to a wrapper. This function
-		 * is a basic version of Field's appendFormattedElements. It is currently
+		 * will append all `$this->dsParamINCLUDEDELEMENTS` to a wrapper. This function
+		 * is a basic version of `Field::appendFormattedElements`. It is currently
 		 * only used by the Author Datasource type.
 		 *
 		 * @param XMLElement $wrapper

symphony/lib/toolkit/class.datasourcemanager.php

@@ -5,7 +5,7 @@
 	/**
 	 * The DatasourceManager class is responsible for managing all Datasource objects
 	 * in Symphony. Datasources's are stored on the file system either in the
-	 * /workspace/data-sources folder or provided by an extension in a /data-sources folder.
+	 * `WORKSPACE . /data-sources` folder or provided by an extension in `EXTENSIONS . /./data-sources` folder.
 	 * Datasources are run from the Frontend to commonly output Entries and parameters,
 	 * however there any different types of Datasource that query external sources for data.
 	 * Typically, a Datasource returns XML.
@@ -18,7 +18,7 @@
 
 		/**
 		 * Given the filename of a Datasource return it's handle. This will remove
-		 * the Symphony convention of data.*.php
+		 * the Symphony convention of `data.*.php`
 		 *
 		 * @param string $filename
 		 *  The filename of the Datasource
@@ -48,7 +48,7 @@ public function __getClassName($handle){
 		 *
 		 * @param string $handle
 		 *  The handle of the Datasource free from any Symphony conventions
-		 *  such as data.*.php
+		 *  such as `data.*.php`
 		 * @return mixed
 		 *  If the datasource is found, the function returns the path it's folder, otherwise false.
 		 */
@@ -71,10 +71,10 @@ public function __getClassPath($handle){
 		/**
 		 * Given a name, return the path to the Datasource class
 		 *
-		 * @see __getClassPath
+		 * @see DatasourceManager::__getClassPath()
 		 * @param string $handle
 		 *  The handle of the Datasource free from any Symphony conventions
-		 *  such as data.*.php
+		 *  such as `data.*.php`
 		 * @return string
 		 */
 		public function __getDriverPath($handle){
@@ -86,10 +86,10 @@ public function __getDriverPath($handle){
 		 * the workspace and in all installed extension folders. Returns an
 		 * associative array of data-sources.
 		 *
-		 * @see toolkit.Manager#about
+		 * @see toolkit.Manager#about()
 		 * @return array
 		 *  Associative array of Datasources with the key being the handle of the
-		 *  Datasource and the value being the Datasource's about() information.
+		 *  Datasource and the value being the Datasource's `about()` information.
 		 */
 		public function listAll(){
 
@@ -183,4 +183,3 @@ public function &create($handle, Array $env = null, $process_params=true){
 		}
 
     }
-