MINOR Fixed phpdoc documentation

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

api/DataFormatter.php

@@ -85,7 +85,7 @@ abstract class DataFormatter extends Object {
 	/**
 	 * Get a DataFormatter object suitable for handling the given file extension.
 	 * 
-	 * @string $extension
+	 * @param string $extension
 	 * @return DataFormatter
 	 */
 	static function for_extension($extension) {

api/RestfulServer.php

@@ -1,8 +1,5 @@
 <?php
 /**
- * @package sapphire
- * @subpackage api
- *
  * Sapphire's generic RESTful server.
  * 
  * This class gives your application a RESTful API for free.  All you have to do is define static $api_access = true on
@@ -86,6 +83,9 @@
  * @todo i18n integration (e.g. Page/1.xml?lang=de_DE)
  * @todo Access to decoratable methods/relations like SiteTree/1/Versions or SiteTree/1/Version/22
  * @todo Respect $api_access array notation in search contexts
+ * 
+ * @package sapphire
+ * @subpackage api
  */
 class RestfulServer extends Controller {
 	static $url_handlers = array(
@@ -585,6 +585,9 @@ class RestfulServer extends Controller {
 
 /**
  * Restful server handler for a DataObjectSet
+ * 
+ * @package sapphire
+ * @subpackage api
  */
 class RestfulServer_List {
 	static $url_handlers = array(
@@ -602,6 +605,9 @@ class RestfulServer_List {
 
 /**
  * Restful server handler for a single DataObject
+ * 
+ * @package sapphire
+ * @subpackage api
  */
 class RestfulServer_Item {
 	static $url_handlers = array(

api/RestfulService.php

@@ -3,6 +3,7 @@
  * RestfulService class allows you to consume various RESTful APIs.
  * Through this you could connect and aggregate data of various web services.
  * For more info visit wiki documentation - http://doc.silverstripe.org/doku.php?id=restfulservice  
+ * 
  * @package sapphire
  * @subpackage integration
  */
@@ -354,6 +355,10 @@ class RestfulService extends ViewableData {
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
 class RestfulService_Response extends SS_HTTPResponse {
 	protected $simpleXML;
 	

cache/Cache.php

@@ -1,5 +1,4 @@
 <?php 
-
 /**
  * SS_Cache provides a bunch of static functions wrapping the Zend_Cache system in something a little more
  * easy to use with the SilverStripe config system.
@@ -58,6 +57,8 @@
  * SS_Cache::pick_backend('two-level', 'any', 10); // No need for special backend for aggregate - TwoLevels with a File slow backend supports tags
  * 
  * @author hfried
+ * @package sapphire
+ * @subpackage core
  */
 class SS_Cache {
 	

core/ManifestBuilder.php

@@ -595,5 +595,4 @@ class ManifestBuilder {
 			return $results;;
 	}
 }
-
-?>
+?>

core/Requirements.php

@@ -3,6 +3,7 @@
 /**
  * Requirements tracker, for javascript and css.
  * @todo Document the requirements tracker, and discuss it with the others.
+ * 
  * @package sapphire
  * @subpackage view
  */
@@ -304,6 +305,10 @@ class Requirements {
 
 }
 
+/**
+ * @package sapphire
+ * @subpackage view
+ */
 class Requirements_Backend {
 		/**
 	 * Paths to all required .js files relative to the webroot.

core/SSViewer.php

@@ -668,6 +668,9 @@ class SSViewer_FromString extends SSViewer {
  * This shouldn't be used as an example of how to add functionality to SSViewer - the eventual plan is to re-write
  * SSViewer using a proper parser (probably http://github.com/hafriedlander/php-peg), so that extra functionality
  * can be added without relying on ad-hoc parsers like this.
+ * 
+ * @package sapphire
+ * @subpackage view
  */
 class SSViewer_PartialParser {
  	

core/model/Aggregate.php

@@ -26,6 +26,8 @@
  * backend (and the two-level backend with the File backend as the slow store) meets this requirement
  * 
  * @author hfried
+ * @package sapphire
+ * @subpackage core
  */
 class Aggregate extends ViewableData {
 
@@ -119,6 +121,8 @@ class Aggregate extends ViewableData {
  * A subclass of Aggregate that calculates aggregates for the result of a has_many query.
  * 
  * @author hfried
+ * @package sapphire
+ * @subpackage core
  */
 class Aggregate_Relationship extends Aggregate {
 

core/model/DataDifferencer.php

@@ -1,5 +1,4 @@
 <?php
-
 /**
  * Utility class to render views of the differences between two data objects (or two versions of the
  * same data object).
@@ -30,6 +29,9 @@
  * <code>
  * $diff->ignoreFields('AuthorID', 'Status');
  * </code>
+ * 
+ * @package sapphire
+ * @subpackage misc
  */
 class DataDifferencer extends ViewableData {
 	protected $fromRecord;

core/model/DataObject.php

@@ -3071,8 +3071,7 @@ class DataObject extends ViewableData implements DataObjectInterface, i18nEntity
 	 *
 	 * @param boolean $includerelations a boolean value to indicate if the labels returned include relation fields
 	 * 
-	 * @return array of all element labels if no argument given
-	 * @return string of label if field
+	 * @return array|string Array of all element labels if no argument given, otherwise the label of the field
 	 */
 	public function fieldLabels($includerelations = true) {
 		$customLabels = $this->stat('field_labels');

core/model/DatabaseAdmin.php

@@ -7,6 +7,7 @@ require_once("core/model/DB.php");
  *
  * Utility functions for administrating the database. These can be accessed
  * via URL, e.g. http://www.yourdomain.com/db/build.
+ * 
  * @package sapphire
  * @subpackage model
  */

core/model/SQLMap.php

@@ -2,6 +2,7 @@
 /**
  * This is a class used to represent key->value pairs generated from database queries.
  * The query isn't actually executed until you need it.
+ * 
  * @package sapphire
  * @subpackage model
  */
@@ -83,6 +84,10 @@ class SQLMap extends Object implements IteratorAggregate {
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
 class SQLMap_Iterator extends Object implements Iterator {
 	protected $items;
 	protected $keyField, $titleField;

core/model/fieldtypes/StringField.php

@@ -13,7 +13,6 @@ abstract class StringField extends DBField {
 	 * Construct a string type field with a set of optional parameters
 	 * @param $name string The name of the field
 	 * @param $options array An array of options e.g. array('nullifyEmpty'=>false).  See {@link StringField::setOptions()} for information on the available options
-	 * @return unknown_type
 	 */
 	function __construct($name = null, $options = array()) {
 		// Workaround: The singleton pattern calls this constructor with true/1 as the second parameter, so we must ignore it
@@ -43,7 +42,6 @@ abstract class StringField extends DBField {
 	/**
 	 * Set whether this field stores empty strings rather than converting them to null
 	 * @param $value boolean True if empty strings are to be converted to null
-	 * @return 
 	 */
 	function setNullifyEmpty($value) {
 		$this->nullifyEmpty == $value ? true : false;

dev/BulkLoader.php

@@ -275,7 +275,10 @@ class BulkLoader_Result extends Object {
 	 * the import of this object. This information is stored
 	 * in a custom object property "_BulkLoaderMessage".
 	 *
-	 * @example array(array('ID'=>1, 'ClassName'=>'Member', 'Message'=>'Updated existing record based on ParentID relation'))
+	 * Example:
+	 * <code>
+	 * array(array('ID'=>1, 'ClassName'=>'Member', 'Message'=>'Updated existing record based on ParentID relation'))
+	 * </code>
 	 */   
 	protected $created = array();
    

dev/CodeViewer.php

@@ -233,8 +233,8 @@ class CodeViewer extends Controller {
 	}
 	
 	/**
-	 * Finish the <pre> block in method content.
-	 * Will remove whitespace and <pre></pre> blocks
+	 * Finish the "pre" block in method content.
+	 * Will remove whitespace and empty "pre" blocks
 	 */
 	function closeOffMethodContentPre() {
 		$this->currentMethod['content'] = trim($this->currentMethod['content']);

dev/Log.php

@@ -1,4 +1,6 @@
 <?php
+require_once 'Zend/Log.php';
+
 /**
  * Wrapper class for a logging handler like {@link Zend_Log}
  * which takes a message (or a map of context variables) and
@@ -42,9 +44,6 @@
  * @package sapphire
  * @subpackage dev
  */
-
-require_once 'Zend/Log.php';
-
 class SS_Log {
 
 	const ERR = Zend_Log::ERR;

dev/LogEmailWriter.php

@@ -1,4 +1,6 @@
 <?php
+require_once 'Zend/Log/Writer/Abstract.php';
+
 /**
  * Sends an error message to an email whenever an error occurs
  * in sapphire.
@@ -8,9 +10,6 @@
  * @package sapphire
  * @subpackage dev
  */
-
-require_once 'Zend/Log/Writer/Abstract.php';
-
 class SS_LogEmailWriter extends Zend_Log_Writer_Abstract {
 
 	protected $emailAddress;

dev/LogErrorEmailFormatter.php

@@ -1,12 +1,12 @@
 <?php
+require_once 'Zend/Log/Formatter/Interface.php';
+
 /**
  * Formats SS error emails with a basic layout.
+ * 
  * @package sapphire
  * @subpackage dev
  */
-
-require_once 'Zend/Log/Formatter/Interface.php';
-
 class SS_LogErrorEmailFormatter implements Zend_Log_Formatter_Interface {
 
 	public function format($event) {

dev/LogErrorFileFormatter.php

@@ -1,13 +1,12 @@
 <?php
+require_once 'Zend/Log/Formatter/Interface.php';
+
 /**
  * Formats SS error entries in an error file log.
  * Format: [d-M-Y h:i:s] <type> at <file> line <line>: <errormessage> <url>
  * @package sapphire
  * @subpackage dev
  */
-
-require_once 'Zend/Log/Formatter/Interface.php';
-
 class SS_LogErrorFileFormatter implements Zend_Log_Formatter_Interface {
 
 	public function format($event) {

dev/LogFileWriter.php

@@ -1,4 +1,6 @@
 <?php
+require_once 'Zend/Log/Writer/Abstract.php';
+
 /**
  * Sends an error message to an email whenever an
  * error occurs in sapphire.
@@ -13,9 +15,6 @@
  * @package sapphire
  * @subpackage dev
  */
-
-require_once 'Zend/Log/Writer/Abstract.php';
-
 class SS_LogFileWriter extends Zend_Log_Writer_Abstract {
 
 	/**

dev/ModelViewer.php

@@ -83,6 +83,10 @@ class ModelViewer extends Controller {
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage tools
+ */
 class ModelViewer_Module extends ModelViewer {
 	static $url_handlers = array(
 		'graph' => 'graph',
@@ -111,6 +115,9 @@ class ModelViewer_Module extends ModelViewer {
 
 /**
  * Represents a single model in the model viewer 
+ * 
+ * @package sapphire
+ * @subpackage tools
  */
 class ModelViewer_Model extends ViewableData {
 	protected $className;
@@ -169,6 +176,10 @@ class ModelViewer_Model extends ViewableData {
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage tools
+ */
 class ModelViewer_Field extends ViewableData {
 	public $Model, $Name, $Type;
 	
@@ -181,6 +192,10 @@ class ModelViewer_Field extends ViewableData {
 	}
 }
 
+/**
+ * @package sapphire
+ * @subpackage tools
+ */
 class ModelViewer_Relation extends ViewableData {
 	public $Model, $Name, $RelationType, $RelatedClass;
 	

dev/SapphireTestReporter.php

@@ -1,21 +1,4 @@
 <?php
-
-/**
- * Gathers details about PHPUnit2 test suites as they 
- * are been executed. This does not actually format any output
- * but simply gathers extended information about the overall 
- * results of all suites & their tests for use elsewhere.
- *
- * Changelog:
- *  0.6 First created [David Spurr]
- *  0.7 Added fix to getTestException provided [Glen Ogilvie]
- * 
- * @package sapphire
- * @subpackage testing
- *
- * @version 0.7 2006-03-12
- * @author David Spurr
- */
 require_once 'PHPUnit/Framework/TestResult.php';
 require_once 'PHPUnit/Framework/TestListener.php';
 
@@ -40,6 +23,22 @@ define('TEST_SUCCESS', 1);
 define('TEST_INCOMPLETE', 2);
 /**#@-*/
 
+/**
+ * Gathers details about PHPUnit2 test suites as they 
+ * are been executed. This does not actually format any output
+ * but simply gathers extended information about the overall 
+ * results of all suites & their tests for use elsewhere.
+ *
+ * Changelog:
+ *  0.6 First created [David Spurr]
+ *  0.7 Added fix to getTestException provided [Glen Ogilvie]
+ * 
+ * @package sapphire
+ * @subpackage testing
+ *
+ * @version 0.7 2006-03-12
+ * @author David Spurr
+ */
 class SapphireTestReporter implements PHPUnit_Framework_TestListener {
 	/**
 	 * Holds array of suites and total number of tests run

dev/TestViewer.php

@@ -132,8 +132,8 @@ class TestViewer extends Controller {
 	}
 	
 	/**
-	 * Finish the <pre> block in method content.
-	 * Will remove whitespace and <pre></pre> blocks
+	 * Finish the "pre" block in method content.
+	 * Will remove whitespace and empty "pre" blocks
 	 */
 	function closeOffMethodContentPre() {
 		$this->currentMethod['content'] = trim($this->currentMethod['content']);

dev/YamlFixture.php

@@ -17,13 +17,18 @@ require_once 'thirdparty/spyc/spyc.php';
  *   However, if you want to define a relationship, you can do so using "=>"
  * 
  * There are a couple of lines like this:
- * @example Parent: =>Page.about
+ * <code>
+ * Parent: =>Page.about
+ * </code>
  * This will tell the system to set the ParentID database field to the ID of the Page object with the identifier ÒaboutÓ. 
  * This can be used on any has-one or many-many relationship. 
  * Note that we use the name of the relationship (Parent), and not the name of the database field (ParentID)
  *
  * On many-many relationships, you should specify a comma separated list of values.
- * @example MyRelation: =>Class.inst1,=>Class.inst2,=>Class.inst3
+ * <code>
+ * MyRelation: =>Class.inst1,=>Class.inst2,=>Class.inst3
+ * </code>
+ * 
  * An crucial thing to note is that the YAML file specifies DataObjects, not database records. 
  * The database is populated by instantiating DataObject objects, setting the fields listed, and calling write(). 
  * This means that any onBeforeWrite() or default value logic will be executed as part of the test. 

filesystem/Upload.php

@@ -44,8 +44,6 @@ class Upload extends Controller {
 	 * <code>
 	 * 	array("jpg","GIF")
 	 * </code>
-	 * 
-	 * @var array
 	 */
 	public $allowedExtensions = array();
 	

forms/ComplexTableField.php

@@ -679,6 +679,8 @@ JS;
 
 /**
  * @todo Tie this into ComplexTableField_Item better.
+ * @package forms
+ * @subpackage fields-relational
  */
 class ComplexTableField_ItemRequest extends RequestHandler {
 	protected $ctf;

forms/FieldSet.php

@@ -537,6 +537,9 @@ class FieldSet extends DataObjectSet {
 /**
  * A fieldset designed to store a list of hidden fields.  When inserted into a template, only the
  * input tags will be included
+ * 
+ * @package forms
+ * @subpackage fields-structural
  */
 class HiddenFieldSet extends FieldSet {
 	function forTemplate() {

forms/FileField.php

@@ -31,8 +31,6 @@ class FileField extends FormField {
 	 * <code>
 	 * 	array("jpg","GIF")
 	 * </code>
-	 * 
-	 * @var array
 	 */
 	public $allowedExtensions = array();
 	

forms/Form.php

@@ -1280,6 +1280,10 @@ class Form extends RequestHandler {
 	}
 }
 
+/**
+ * @package forms
+ * @subpackage core
+ */
 class Form_FieldMap extends ViewableData {
 	protected $form;
 	

forms/FormField.php

@@ -593,8 +593,9 @@ HTML;
 	 * words. Also resolves combined fieldnames with dot syntax
 	 * to spaced words.
 	 * 
-	 * @example 'TotalAmount' will return 'Total Amount'
-	 * @example 'Organisation.ZipCode' will return 'Organisation Zip Code'
+	 * Examples:
+	 * - 'TotalAmount' will return 'Total Amount'
+	 * - 'Organisation.ZipCode' will return 'Organisation Zip Code'
 	 *
 	 * @param string $fieldName
 	 * @return string

forms/HtmlEditorConfig.php

@@ -7,6 +7,8 @@
  * the currently active config using set_active. Whichever config is active when HtmlEditorField#Field is called wins.
  *  
  * @author "Hamish Friedlander" <hamish@silverstripe.com>
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class HtmlEditorConfig {
 
@@ -142,7 +144,7 @@ class HtmlEditorConfig {
 	 * 
 	 * @see http://wiki.moxiecode.com/index.php/TinyMCE:API/tinymce.PluginManager/load
 	 * 
-	 * @param[0..] a string, or several strings, or a single array of strings - The plugins to enable
+	 * @param String [0..] a string, or several strings, or a single array of strings - The plugins to enable
 	 * @return null
 	 */
 	function enablePlugins() {
@@ -160,7 +162,7 @@ class HtmlEditorConfig {
 
 	/**
 	 * Enable one or several plugins. Will properly handle being passed a plugin that is already disabled
-	 * @param[0..] a string, or several strings, or a single array of strings - The plugins to disable
+	 * @param String [0..] a string, or several strings, or a single array of strings - The plugins to disable
 	 * @return null
 	 */
 	function disablePlugins() {
@@ -183,8 +185,9 @@ class HtmlEditorConfig {
 	
 	/**
 	 * Totally re-set the buttons on a given line
-	 * @param[0] integer from 1..3 - The line number to redefine
-	 * @param[1..] a string or several strings, or a single array of strings - The button names to make this line contain 
+	 * 
+	 * @param integer from 1..3 - The line number to redefine
+	 * @param string  a string or several strings, or a single array of strings - The button names to make this line contain 
 	 * @return null
 	 */
 	function setButtonsForLine() {
@@ -200,8 +203,8 @@ class HtmlEditorConfig {
 	
 	/**
 	 * Add buttons to the end of a line
-	 * @param[0] integer from 1..3
-	 * @param[1..] a string, or several strings, or a single array of strings - The button names to add to the end of this line 
+	 * @param integer from 1..3
+	 * @param string a string, or several strings, or a single array of strings - The button names to add to the end of this line 
 	 * @return null
 	 */
 	function addButtonsToLine() {
@@ -235,8 +238,8 @@ class HtmlEditorConfig {
 	
 	/**
 	 * Insert buttons before the first occurance of another button
-	 * @param[0] string - the name of the button to insert other buttons before
-	 * @param[1..] a string, or several strings, or a single array of strings - the button names to insert before that button 
+	 * @param string - the name of the button to insert other buttons before
+	 * @param string a string, or several strings, or a single array of strings - the button names to insert before that button 
 	 * @return boolean - true if insertion occured, false if it did not (because the given button name was not found)
 	 */
 	function insertButtonsBefore() {
@@ -247,8 +250,8 @@ class HtmlEditorConfig {
 	
 	/**
 	 * Insert buttons after the first occurance of another button
-	 * @param[0] string - the name of the button to insert other buttons after
-	 * @param[1..] a string, or several strings, or a single array of strings - the button names to insert after that button 
+	 * @param string - the name of the button to insert other buttons after
+	 * @param string a string, or several strings, or a single array of strings - the button names to insert after that button 
 	 * @return boolean - true if insertion occured, false if it did not (because the given button name was not found)
 	 */
 	function insertButtonsAfter() {
@@ -259,7 +262,7 @@ class HtmlEditorConfig {
 	
 	/**
 	 * Remove the first occurance of buttons
-	 * @param[0..] string - the name of the buttons to remove
+	 * @param string one or more strings - the name of the buttons to remove
 	 * @return null
 	 */
 	function removeButtons() {

forms/NullableField.php

@@ -15,7 +15,8 @@
  * $field->setIsNullLabel(_T(SOME_MODULE_ISNULL_LABEL, "Is Null");
  * 
  * @author Pete Bacon Darwin
- *
+ * @package forms
+ * @subpackage fields-basic
  */
 class NullableField extends FormField {
 	/**
@@ -57,7 +58,6 @@ class NullableField extends FormField {
 	/**
 	 * Set the label used for the Is Null checkbox.
 	 * @param $isNulLabel string
-	 * @return 
 	 */
 	function setIsNullLabel(string $isNulLabel){
 		$this->isNullLabel = $isNulLabel;

forms/TableListField.php

@@ -149,7 +149,7 @@ class TableListField extends FormField {
 	 * @var $customSourceItems DataObjectSet Use the manual setting of a result-set only as a last-resort
 	 * for sets which can't be resolved in a single query.
 	 *
-	 * @todo: Add pagination support for customSourceItems.
+	 * @todo Add pagination support for customSourceItems.
 	 */
 	protected $customSourceItems;
 	
@@ -1407,6 +1407,10 @@ class TableListField_Item extends ViewableData {
 	}
 }
 
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
 class TableListField_ItemRequest extends RequestHandler {
 	protected $ctf;
 	protected $itemID;

forms/TreeDropdownField.php

@@ -288,6 +288,10 @@ class TreeDropdownField extends FormField {
 	}
 }
 
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
 class TreeDropdownField_Readonly extends TreeDropdownField {
 	protected $readonly = true;
 	

forms/TreeMultiselectField.php

@@ -2,6 +2,7 @@
 /**
  * This formfield represents many-many joins using a tree selector shown in a dropdown styled element
  * which can be added to any form usually in the CMS. 
+ * 
  * @package forms
  * @subpackage fields-relational
  */
@@ -128,6 +129,10 @@ HTML;
 	}
 }
 
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
 class TreeMultiselectField_Readonly extends TreeMultiselectField {
 	
 	protected $readonly = true;

parsers/HTML/HTMLBBCodeParser.php

@@ -324,7 +324,7 @@ class SSHTMLBBCodeParser
      * $_preparsed variable. The method uses _buildTag() to check if a tag is
      * valid and to build the actual tag to be added to the tag array.
      *
-     * @todo: - rewrite whole method, as this one is old and probably slow
+     * @todo - rewrite whole method, as this one is old and probably slow
      *       - see if a recursive method would be better than an iterative one
      *
      * @return   none

search/SearchContext.php

@@ -88,7 +88,7 @@ class SearchContext extends Object {
 	}
 	
 	/**
-	 * @refactor move to SQLQuery
+	 * @todo move to SQLQuery
 	 * @todo fix hack
 	 */
 	protected function applyBaseTableFields() {

search/filters/ExactMatchMultiFilter.php

@@ -9,6 +9,8 @@
  * SQL syntax used: Column IN ('val1','val2')
  * 
  * @todo Add negation (NOT IN)6
+ * @package sapphire
+ * @subpackage search
  */
 class ExactMatchMultiFilter extends SearchFilter {
 	

security/PermissionRole.php

@@ -1,10 +1,12 @@
 <?php
-
 /**
  * A PermissionRole represents a collection of permission codes that can be applied to groups.
  * 
  * Because permission codes are very granular, this lets website administrators create more
  * business-oriented units of access control - Roles - and assign those to groups.
+ * 
+ * @package sapphire
+ * @subpackage security
  */
 class PermissionRole extends DataObject {
 	static $db = array(

widgets/Widget.php

@@ -215,6 +215,10 @@ class Widget_Controller extends Controller {
 	}	
 }
 
+/**
+ * @package sapphire
+ * @subpackage widgets
+ */
 class Widget_TreeDropdownField extends TreeDropdownField {
 	function FieldHolder() {}
 	function Field() {}