From 6460d09570dc3dafa3f33d9a5bda9a60bdcca46f Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Fri, 23 Apr 2010 00:11:41 +0000 Subject: [PATCH] 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 | 2 +- api/RestfulServer.php | 12 ++++++--- api/RestfulService.php | 5 ++++ cache/Cache.php | 3 ++- core/ManifestBuilder.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 +-- dev/YamlFixture.php | 9 +++++-- filesystem/Upload.php | 2 -- forms/ComplexTableField.php | 2 ++ forms/FieldSet.php | 3 +++ forms/FileField.php | 2 -- 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 +++ 40 files changed, 150 insertions(+), 74 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 @@ +?> \ No newline at end of file diff --git a/core/Requirements.php b/core/Requirements.php index f7da67848..00fd16a63 100644 --- a/core/Requirements.php +++ b/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. diff --git a/core/SSViewer.php b/core/SSViewer.php index a225d9f09..d673a82d3 100755 --- a/core/SSViewer.php +++ b/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 { diff --git a/core/model/Aggregate.php b/core/model/Aggregate.php index b85c6b56e..92092ef85 100644 --- a/core/model/Aggregate.php +++ b/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 { diff --git a/core/model/DataDifferencer.php b/core/model/DataDifferencer.php index 63b4a0fab..cf29d6a1b 100644 --- a/core/model/DataDifferencer.php +++ b/core/model/DataDifferencer.php @@ -1,5 +1,4 @@ * $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 f7c762a46..b68bce963 100755 --- a/core/model/DataObject.php +++ b/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'); diff --git a/core/model/DatabaseAdmin.php b/core/model/DatabaseAdmin.php index 5b12593d5..92a1cff93 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/dev/YamlFixture.php b/dev/YamlFixture.php
index 82a796eae..2c68b3a16 100644
--- a/dev/YamlFixture.php
+++ b/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
+ * 
+ * Parent: =>Page.about
+ * 
  * 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
+ * 
+ * MyRelation: =>Class.inst1,=>Class.inst2,=>Class.inst3
+ * 
+ * 
  * 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. 
diff --git a/filesystem/Upload.php b/filesystem/Upload.php
index ca9a4c2e9..c47029f8d 100644
--- a/filesystem/Upload.php
+++ b/filesystem/Upload.php
@@ -44,8 +44,6 @@ class Upload extends Controller {
 	 * 
 	 * 	array("jpg","GIF")
 	 * 
-	 * 
-	 * @var array
 	 */
 	public $allowedExtensions = array();
 	
diff --git a/forms/ComplexTableField.php b/forms/ComplexTableField.php
index 353ab2ad6..966fbe296 100755
--- a/forms/ComplexTableField.php
+++ b/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;
diff --git a/forms/FieldSet.php b/forms/FieldSet.php
index 8ea03bcee..fcaab45d8 100755
--- a/forms/FieldSet.php
+++ b/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() {
diff --git a/forms/FileField.php b/forms/FileField.php
index b8027d0ad..29f667f85 100755
--- a/forms/FileField.php
+++ b/forms/FileField.php
@@ -31,8 +31,6 @@ class FileField extends FormField {
 	 * 
 	 * 	array("jpg","GIF")
 	 * 
-	 * 
-	 * @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 ec0873c22..ebbb5efec 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 {
 
@@ -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() {
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 310658186..e4aac2234 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 d0c521a0a..6bab8a665 100755
--- a/forms/TreeDropdownField.php
+++ b/forms/TreeDropdownField.php
@@ -288,6 +288,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 9e7de9108..f70d8de50 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
  */
@@ -128,6 +129,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 8fafd91a7..b51122b31 100644
--- a/security/PermissionRole.php
+++ b/security/PermissionRole.php
@@ -1,10 +1,12 @@