From 6f0df9eb19cbc059d55f0ef946b876e9b8bb6228 Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Fri, 23 Apr 2010 00:25:47 +0000 Subject: [PATCH] MINOR Fixed phpdoc documentation (from r103385) git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/branches/2.4@103388 467b73ca-7a2a-4603-9d3b-597d59a354a9 --- api/DataFormatter.php | 2 +- api/RestfulServer.php | 12 ++++++--- api/RestfulService.php | 5 ++++ cache/Cache.php | 3 ++- core/Requirements.php | 5 ++++ core/SSViewer.php | 3 +++ core/model/Aggregate.php | 4 +++ core/model/DataDifferencer.php | 4 ++- core/model/DataObject.php | 3 +-- core/model/DatabaseAdmin.php | 1 + core/model/SQLMap.php | 5 ++++ core/model/fieldtypes/StringField.php | 2 -- dev/BulkLoader.php | 5 +++- dev/CodeViewer.php | 4 +-- dev/Log.php | 5 ++-- dev/LogEmailWriter.php | 5 ++-- dev/LogErrorEmailFormatter.php | 6 ++--- dev/LogErrorFileFormatter.php | 5 ++-- dev/LogFileWriter.php | 5 ++-- dev/ModelViewer.php | 15 +++++++++++ dev/SapphireTestReporter.php | 33 ++++++++++++------------ dev/TestViewer.php | 4 +-- forms/ComplexTableField.php | 2 ++ forms/FieldSet.php | 3 +++ forms/FileField.php | 3 --- forms/Form.php | 4 +++ forms/FormField.php | 5 ++-- forms/HtmlEditorConfig.php | 25 ++++++++++-------- forms/NullableField.php | 4 +-- forms/TableListField.php | 6 ++++- forms/TreeDropdownField.php | 4 +++ forms/TreeMultiselectField.php | 5 ++++ parsers/HTML/HTMLBBCodeParser.php | 2 +- search/SearchContext.php | 2 +- search/filters/ExactMatchMultiFilter.php | 2 ++ security/PermissionRole.php | 4 ++- widgets/Widget.php | 4 +++ 37 files changed, 142 insertions(+), 69 deletions(-) diff --git a/api/DataFormatter.php b/api/DataFormatter.php index a2cccab93..c8b6ed0b5 100644 --- a/api/DataFormatter.php +++ b/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) { diff --git a/api/RestfulServer.php b/api/RestfulServer.php index fed90822a..ad9fb66ad 100644 --- a/api/RestfulServer.php +++ b/api/RestfulServer.php @@ -1,8 +1,5 @@ * $diff->ignoreFields('AuthorID', 'Status'); * + * + * @package sapphire + * @subpackage misc */ class DataDifferencer extends ViewableData { protected $fromRecord; diff --git a/core/model/DataObject.php b/core/model/DataObject.php index 92e6fb3ba..e1991cd45 100755 --- a/core/model/DataObject.php +++ b/core/model/DataObject.php @@ -3089,8 +3089,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'); diff --git a/core/model/DatabaseAdmin.php b/core/model/DatabaseAdmin.php index 025852dd4..91299d497 100644 --- a/core/model/DatabaseAdmin.php +++ b/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 */ diff --git a/core/model/SQLMap.php b/core/model/SQLMap.php index 809a74ca8..b2568f47f 100755 --- a/core/model/SQLMap.php +++ b/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; diff --git a/core/model/fieldtypes/StringField.php b/core/model/fieldtypes/StringField.php index 690bfcdaf..71bc96580 100644 --- a/core/model/fieldtypes/StringField.php +++ b/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; diff --git a/dev/BulkLoader.php b/dev/BulkLoader.php index 082447c05..f7912653d 100644 --- a/dev/BulkLoader.php +++ b/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: + * + * array(array('ID'=>1, 'ClassName'=>'Member', 'Message'=>'Updated existing record based on ParentID relation')) + * */ protected $created = array(); diff --git a/dev/CodeViewer.php b/dev/CodeViewer.php index 03740b663..614fb56d3 100644 --- a/dev/CodeViewer.php +++ b/dev/CodeViewer.php @@ -233,8 +233,8 @@ class CodeViewer extends Controller { } /** - * Finish the 
 block in method content.
-	 * Will remove whitespace and 
 blocks
+	 * Finish the "pre" block in method content.
+	 * Will remove whitespace and empty "pre" blocks
 	 */
 	function closeOffMethodContentPre() {
 		$this->currentMethod['content'] = trim($this->currentMethod['content']);
diff --git a/dev/Log.php b/dev/Log.php
index d820f1203..f1cce7599 100644
--- a/dev/Log.php
+++ b/dev/Log.php
@@ -1,4 +1,6 @@
  at  line :  
  * @package sapphire
  * @subpackage dev
  */
-
-require_once 'Zend/Log/Formatter/Interface.php';
-
 class SS_LogErrorFileFormatter implements Zend_Log_Formatter_Interface {
 
 	public function format($event) {
diff --git a/dev/LogFileWriter.php b/dev/LogFileWriter.php
index e1171ee18..a47a2b90b 100644
--- a/dev/LogFileWriter.php
+++ b/dev/LogFileWriter.php
@@ -1,4 +1,6 @@
  '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;
 	
diff --git a/dev/SapphireTestReporter.php b/dev/SapphireTestReporter.php
index 91df9b2fb..e0911d007 100644
--- a/dev/SapphireTestReporter.php
+++ b/dev/SapphireTestReporter.php
@@ -1,21 +1,4 @@
  block in method content.
-	 * Will remove whitespace and 
 blocks
+	 * Finish the "pre" block in method content.
+	 * Will remove whitespace and empty "pre" blocks
 	 */
 	function closeOffMethodContentPre() {
 		$this->currentMethod['content'] = trim($this->currentMethod['content']);
diff --git a/forms/ComplexTableField.php b/forms/ComplexTableField.php
index 40c94e897..e6b27435e 100755
--- a/forms/ComplexTableField.php
+++ b/forms/ComplexTableField.php
@@ -687,6 +687,8 @@ JS;
 
 /**
  * @todo Tie this into ComplexTableField_Item better.
+ * @package forms
+ * @subpackage fields-relational
  */
 class ComplexTableField_ItemRequest extends TableListField_ItemRequest {
 	protected $ctf;
diff --git a/forms/FieldSet.php b/forms/FieldSet.php
index be53dc0bb..f37d91e58 100755
--- a/forms/FieldSet.php
+++ b/forms/FieldSet.php
@@ -540,6 +540,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() {
diff --git a/forms/FileField.php b/forms/FileField.php
index 6b62a3cef..b310c76be 100755
--- a/forms/FileField.php
+++ b/forms/FileField.php
@@ -32,9 +32,6 @@ class FileField extends FormField {
 	 * 
 	 * 	array("jpg","GIF")
 	 * 
-	 *
-	 * @deprecated 2.5
-	 * @var array
 	 */
 	public $allowedExtensions = array();
 	
diff --git a/forms/Form.php b/forms/Form.php
index 48659b58d..5d1a151e1 100755
--- a/forms/Form.php
+++ b/forms/Form.php
@@ -1280,6 +1280,10 @@ class Form extends RequestHandler {
 	}
 }
 
+/**
+ * @package forms
+ * @subpackage core
+ */
 class Form_FieldMap extends ViewableData {
 	protected $form;
 	
diff --git a/forms/FormField.php b/forms/FormField.php
index 038c5d612..6e5b5218e 100755
--- a/forms/FormField.php
+++ b/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
diff --git a/forms/HtmlEditorConfig.php b/forms/HtmlEditorConfig.php
index bc0e71b58..2d30d1170 100644
--- a/forms/HtmlEditorConfig.php
+++ b/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" 
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class HtmlEditorConfig {
 
@@ -141,7 +143,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() {
@@ -159,7 +161,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() {
@@ -182,8 +184,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() {
@@ -199,8 +202,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() {
@@ -234,8 +237,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() {
@@ -246,8 +249,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() {
@@ -258,7 +261,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() {
diff --git a/forms/NullableField.php b/forms/NullableField.php
index 65bfa3f06..debe517cb 100644
--- a/forms/NullableField.php
+++ b/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;
diff --git a/forms/TableListField.php b/forms/TableListField.php
index d8802ccef..8d7d28492 100755
--- a/forms/TableListField.php
+++ b/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;
diff --git a/forms/TreeDropdownField.php b/forms/TreeDropdownField.php
index e5fe157fb..695bd0559 100755
--- a/forms/TreeDropdownField.php
+++ b/forms/TreeDropdownField.php
@@ -286,6 +286,10 @@ class TreeDropdownField extends FormField {
 	}
 }
 
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
 class TreeDropdownField_Readonly extends TreeDropdownField {
 	protected $readonly = true;
 	
diff --git a/forms/TreeMultiselectField.php b/forms/TreeMultiselectField.php
index bb0696008..abec4f109 100755
--- a/forms/TreeMultiselectField.php
+++ b/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
  */
@@ -129,6 +130,10 @@ HTML;
 	}
 }
 
+/**
+ * @package forms
+ * @subpackage fields-relational
+ */
 class TreeMultiselectField_Readonly extends TreeMultiselectField {
 	
 	protected $readonly = true;
diff --git a/parsers/HTML/HTMLBBCodeParser.php b/parsers/HTML/HTMLBBCodeParser.php
index 025ff371f..28610492d 100644
--- a/parsers/HTML/HTMLBBCodeParser.php
+++ b/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
diff --git a/search/SearchContext.php b/search/SearchContext.php
index d84d1e450..54a4e8a73 100644
--- a/search/SearchContext.php
+++ b/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() {
diff --git a/search/filters/ExactMatchMultiFilter.php b/search/filters/ExactMatchMultiFilter.php
index 782b701f3..e85d410ea 100644
--- a/search/filters/ExactMatchMultiFilter.php
+++ b/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 {
 	
diff --git a/security/PermissionRole.php b/security/PermissionRole.php
index 636e283f4..bccaea8fc 100644
--- a/security/PermissionRole.php
+++ b/security/PermissionRole.php
@@ -1,10 +1,12 @@