Improved API documentation

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

api/Spyc.php

@@ -23,7 +23,7 @@ class YAMLNode {
    */
   public $parent;
   public $id;
-  /**#@+*/
+  /**#@-*/
   /**
    * @access public
    * @var mixed
@@ -349,7 +349,7 @@ class Spyc {
   private $_isInline;
   private $_dumpIndent;
   private $_dumpWordWrap;
-  /**#@+*/
+  /**#@-*/
 
   /**** Public Properties ****/
 
@@ -358,7 +358,7 @@ class Spyc {
    * @var mixed
    */
   public $_nodeId;
-  /**#@+*/
+  /**#@-*/
 
   /**** Private Methods ****/
 

cli-script.php

@@ -16,6 +16,9 @@ $_SERVER['HTTP_HOST'] = $_SERVER['argv'][2];
 $_SERVER['SCRIPT_FILENAME'] = __FILE__;
 chdir(dirname($_SERVER['SCRIPT_FILENAME']));
 
+/**
+ * Include Sapphire's core code
+ */
 require_once("core/Core.php");
 
 header("Content-type: text/html; charset=\"utf-8\"");

core/Email.php

@@ -368,6 +368,11 @@ class Email extends ViewableData {
     }
 }
 
+/**
+ * Implements an email template that can be populated.
+ * @package sapphire
+ * @subpackage email
+ */
 class Email_Template extends Email {
 	public function __construct() {
 	}

core/ManifestBuilder.php

@@ -205,7 +205,7 @@ class ManifestBuilder {
 	 * application
 	 *
 	 * @param string $folder The folder to traverse (recursively)
-	 * @pram array $classMap The already built class map
+	 * @param array $classMap The already built class map
 	 */
 	private static function getClassManifest($folder, &$classMap) {
 		$items = scandir($folder);

core/control/Director.php

@@ -86,8 +86,8 @@ class Director {
 	 *  - output the response to the browser, using {@link HTTPResponse::output()}.
 	 * 
 	 * @param $url String, the URL the user is visiting, without the querystring.
-	 * @uses getControllerForURL() The rule-lookup logic is handled by this.
+	 * @uses getControllerForURL() rule-lookup logic is handled by this.
-	 * @uses Controller::run() The actual page logic is handled by this.
+	 * @uses Controller::run() Controller::run() handles the page logic for a Director::direct() call.
 	 */
 	function direct($url) {
 		if(isset($_GET['debug_profile'])) Profiler::mark("Director","direct");
@@ -125,7 +125,7 @@ class Director {
 	 * calls of Director::test(), you can simulate a peristed session.
 	 * 
 	 * @uses getControllerForURL() The rule-lookup logic is handled by this.
-	 * @uses Controller::run() The actual page logic is handled by this.
+	 * @uses Controller::run() Controller::run() handles the page logic for a Director::direct() call.
 	 */
 	function test($url, $post = null, $session = null) {
         $getVars = array();

core/model/Database.php

@@ -445,6 +445,8 @@ abstract class Database extends Object {
  * Primarily, the Query class takes care of the iterator plumbing, letting the subclasses focusing
  * on providing the specific data-access methods that are required: {@link nextRecord()}, {@link numRecords()}
  * and {@link seek()}
+ * @package sapphire
+ * @subpackage model
  */
 abstract class Query extends Object implements Iterator {
 	/**

core/model/ErrorPage.php

@@ -104,6 +104,7 @@ class ErrorPage extends Page {
 
 /**
  * Controller for ErrorPages.
+ * @package cms
  */
 class ErrorPage_Controller extends Page_Controller {
 	public function init() {

core/model/GhostPage.php

@@ -96,6 +96,7 @@ class GhostPage extends SiteTree implements HiddenClass {
 
 /**
  * Controller for GhostPages
+ * @package cms
  */
 class GhostPage_Controller extends Page_Controller {
 	function getViewer($action) {
@@ -105,6 +106,7 @@ class GhostPage_Controller extends Page_Controller {
 
 /**
  * Special type of ComponentSet just for GhostPages
+ * @package cms
  */
 class GhostPage_ComponentSet extends ComponentSet {
 	function setOwner($ownerObj) {

core/model/Image.php

@@ -264,9 +264,9 @@ class Image extends File {
 	 * Generate an image on the specified format. It will save the image
 	 * at the location specified by cacheFilename(). The image will be generated
 	 * using the specific 'generate' method for the specified format.
-	 * @var string $format Name of the format to generate.
+	 * @param string $format Name of the format to generate.
-	 * @var string $arg1 Argument to pass to the generate method.
+	 * @param string $arg1 Argument to pass to the generate method.
-	 * @var string $arg2 A second argument to pass to the generate method.
+	 * @param string $arg2 A second argument to pass to the generate method.
 	 */
 	function generateFormattedImage($format, $arg1 = null, $arg2 = null) {
 		$cacheFile = $this->cacheFilename($format, $arg1, $arg2);
@@ -367,7 +367,11 @@ class Image extends File {
 }
 
 /**
- * Image not stored in the database, that is just a cached resampled image
+ * A resized / processed {@link Image} object.
+ * When Image object are processed or resized, a suitable Image_Cached object is returned, pointing to the
+ * cached copy of the processed image.
+ * @package sapphire
+ * @subpackage filesystem
  */
 class Image_Cached extends Image {
 	/**
@@ -395,6 +399,12 @@ class Image_Cached extends Image {
 	}
 }
 
+/**
+ * A db field type designed to help save images.
+ * @deprecated Use a has_one relationship pointing to the file table instead.
+ * @package sapphire
+ * @subpackage filesystem
+ */
 class Image_Saver extends DBField {
 	function saveInto($record) {
 		$image = $record->getComponent($this->name);
@@ -414,8 +424,9 @@ class Image_Saver extends DBField {
 }
 
 /**
- * Uploader support for the uploading anything which is a File or subclass of 
+ * Uploader support for the uploading anything which is a File or subclass of File, eg Image.
- * File, eg Image.
+ * @package sapphire
+ * @subpackage filesystem
  */
 class Image_Uploader extends Controller {
 	/**

core/model/MySQLDatabase.php

@@ -32,10 +32,10 @@ class MySQLDatabase extends Database {
 	/**
 	 * Connect to a MySQL database.
 	 * @param array $parameters An map of parameters, which should include:
-	 * <ul><li>server: The server, eg, localhost</li>
+	 *  - server: The server, eg, localhost
-	 * <li>username: The username to log on with</li>
+	 *  - username: The username to log on with
-	 * <li>password: The password to log on with</li>
+	 *  - password: The password to log on with
-	 * <li>database: The database to connect to</li>
+	 *  - database: The database to connect to
 	 */
 	public function __construct($parameters) {
 		$this->dbConn = mysql_connect($parameters['server'], $parameters['username'], $parameters['password']);
@@ -392,6 +392,8 @@ class MySQLDatabase extends Database {
 
 /**
  * A result-set from a MySQL database.
+ * @package sapphire
+ * @subpackage model
  */
 class MySQLQuery extends Query {
 	/**

core/model/PDODatabase.php

@@ -313,11 +313,11 @@ class PDODatabase extends Database {
 
 	/**
 	 * Alter fields and indexes in existing table.
-	 * @var string $tableName The name of the table.
+	 * @param string $tableName The name of the table.
-	 * @var string $newFields Fields to add.
+	 * @param string $newFields Fields to add.
-	 * @var string $newIndexes Indexes to add.
+	 * @param string $newIndexes Indexes to add.
-	 * @var string $alteredFields Fields to change.
+	 * @param string $alteredFields Fields to change.
-	 * @var string $alteredIndexes Indexes to change.
+	 * @param string $alteredIndexes Indexes to change.
 	 * @return void.
 	 */
 	public function alterTable($table, $newFields = null, $newIndexes = null, $alteredFields = null, $alteredIndexes = null) {
@@ -353,8 +353,8 @@ class PDODatabase extends Database {
 
 	/**
 	 * Rename an existing table, the TO is necessary for PostgreSQL and MS SQL.
-	 * @var string $oldTableName The name of the existing table.
+	 * @param string $oldTableName The name of the existing table.
-	 * @var string $newTableName How the table should be named from now on.
+	 * @param string $newTableName How the table should be named from now on.
 	 * @return void.
 	 */
 	public function renameTable($oldTableName, $newTableName) {
@@ -656,6 +656,8 @@ class PDODatabase extends Database {
 
 /**
  * A result-set from a database query (array).
+ * @package sapphire
+ * @subpackage model
  */
 class PDOQuery extends Query {
 	private $database;

core/model/RedirectorPage.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
+ * @subpackage content
  */
 
 /**
  * A redirector page redirects when the page is visited.
  * @package cms
+ * @subpackage content
  */
 class RedirectorPage extends Page {
 	static $add_action = "Redirector to another page";
@@ -94,6 +96,11 @@ class RedirectorPage extends Page {
 	}
 }
 
+/**
+ * Controller for the {@link RedirectorPage}.
+ * @package cms
+ * @subpackage content
+ */
 class RedirectorPage_Controller extends Page_Controller {
 	function init() {
 		if($this->RedirectionType == 'External') {

forms/CheckboxField.php

@@ -84,6 +84,11 @@ HTML;
 	}
 }
 
+/**
+ * Readonly version of a checkbox field - "Yes" or "No".
+ * @package forms
+ * @subpackage fields-basic
+ */
 class CheckboxField_Readonly extends ReadonlyField {
 	function performReadonlyTransformation() {
 		return $this;

forms/ComplexTableField.php

@@ -645,6 +645,11 @@ JS;
 
 }
 
+/**
+ * Single row of a {@link ComplexTableField}.
+ * @package forms
+ * @subpackage fields-relational
+ */
 class ComplexTableField_Item extends TableListField_Item {
 	/**
 	 * Needed to transfer pagination-status from overview.
@@ -680,6 +685,8 @@ class ComplexTableField_Item extends TableListField_Item {
  * detailed view of the source class your presenting.
  * You can customise the fields and requirements as well as any
  * permissions you might need.
+ * @package forms
+ * @subpackage fields-relational
  */
 class ComplexTableField_Popup extends Form {
 	protected $sourceClass;

forms/CompositeDateField.php

@@ -143,6 +143,8 @@ JS;
 /**
  * Allows dates to be represented in a form, by
  * showing in a user friendly format, eg, dd/mm/yyyy.
+ * @package forms
+ * @subpackage fields-datetime
  */
 class CompositeDateField_Disabled extends DateField {
 	function setValue($val) {

forms/CurrencyField.php

@@ -79,7 +79,9 @@ JS;
 }
 
 /**
- * Creates the appropriate readonly field for this class.
+ * Readonly version of a {@link CurrencyField}.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class CurrencyField_Readonly extends ReadonlyField{
 	

forms/CustomRequiredFields.php

@@ -15,8 +15,7 @@ class CustomRequiredFields extends RequiredFields{
 		
 	/**
 	 * Pass each field to be validated as a seperate argument
-	 * __construct()'s arguments needs to be an array
+	 * @param $required array The list of required fields
-	 * @mpeel Unfortunately the line 'function __construct(array $required)' breaks older versions of PHP 5, so remove the forcing of array
 	 */
 	function __construct($required) {
 		$this->required = $required;

forms/DataReport.php

@@ -201,8 +201,8 @@ HTML
 	
 	/**
 		*Todo: Returns the HTML for the body of the reported table, excluding table header
-		*@Param rowCallBack: the function name for how the rows are formated
+		* @param rowCallBack: the function name for how the rows are formated
-		*@Param cellCallBack: the function name for how the cells are formated
+		* @param cellCallBack: the function name for how the cells are formated
 		*/
 	protected function datacells($rowCallBack = 'htmlTableRow', $cellCallBack = 'htmlTableDataCell' ) {
 		$records = $this->getRecords();
@@ -555,6 +555,9 @@ HTML
 
 /**
  * A controller class work for exporting reported table to CSV format.
+ * @package forms
+ * @subpackage fields-reports
+ * @deprecated This should be considered alpha code; reporting needs a clean-up.
  */
 class DataReport_Controller extends Controller{
 

forms/DateField.php

@@ -89,8 +89,10 @@ JS;
 }
 
 /**
- * Allows dates to be represented in a form, by
+ * Disabled version of {@link DateField}.
- * showing in a user friendly format, eg, dd/mm/yyyy.
+ * Allows dates to be represented in a form, by showing in a user friendly format, eg, dd/mm/yyyy.
+ * @package forms
+ * @subpackage fields-datetime
  */
 class DateField_Disabled extends DateField {
 	

forms/DropdownField.php

@@ -85,9 +85,12 @@ class DropdownField extends FormField {
 }
 
 /**
-  * The class is originally designed to be used by RelatedDataEditor
+ * Dropdown field with an add button to the right.
-  * However, it can potentially be used as a normal dropdown field with add links in a normal form
+ * The class is originally designed to be used by RelatedDataEditor
-  */
+ * However, it can potentially be used as a normal dropdown field with add links in a normal form
+ * @package forms
+ * @subpackage fields-basic
+ */
 class DropdownField_WithAdd extends DropdownField {
 		
 	protected $addText, $useExistingText, $addLink, $useExistingLink;

forms/EditableButton.php

@@ -8,6 +8,8 @@
 /**
  * EditableButton
  * Allows a user to modify the text on the button
+ * @package forms
+ * @subpackage fieldeditor
  */
 class EditableButton extends FormField {
 	

forms/Form.php

@@ -18,7 +18,6 @@
  * recreate the form object upon form submission, without the use of a session, which would be too
  * resource-intensive.
  *
- * @example forms/Form.php See how you can create a form on your controller.
  * @package forms
  * @subpackage core
  */

forms/FormAction.php

@@ -58,6 +58,10 @@ class FormAction extends FormField {
 	}
 }
 
+/**
+ * @package forms
+ * @subpackage actions
+ */
 class FormAction_WithoutLabel extends FormAction {
 	function Title(){
 		return null;

forms/HasManyComplexTableField.php

@@ -134,6 +134,11 @@ HTML;
 	}
 }
 
+/**
+ * Single record of a {@link HasManyComplexTableField} field.
+ * @package forms
+ * @subpackage fields-relational
+ */
 class HasManyComplexTableField_Item extends ComplexTableField_Item {
 	
 	function MarkingCheckbox() {

forms/HasOneComplexTableField.php

@@ -16,8 +16,8 @@ class HasOneComplexTableField extends HasManyComplexTableField {
 	
 	public $isOneToOne = false;
 	
-	function getParentIdName($parentClass, $childClass) {
+	function getParentIdName($parentClass, $childClass) {
-		return $this->getParentIdNameRelation($parentClass, $childClass, 'has_one');
+		return $this->getParentIdNameRelation($parentClass, $childClass, 'has_one');
 	}
 			
 	function getControllerJoinID() {
@@ -54,6 +54,11 @@ HTML;
 	}
 }
 
+/**
+ * Single record of a {@link HasOneComplexTableField} field.
+ * @package forms
+ * @subpackage fields-relational
+ */
 class HasOneComplexTableField_Item extends ComplexTableField_Item {
 	
 	function MarkingCheckbox() {

forms/HtmlEditorField.php

@@ -183,6 +183,11 @@ class HtmlEditorField extends TextareaField {
 	}
 }
 
+/**
+ * Readonly version of an {@link HTMLEditorField}.
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class HtmlEditorField_readonly extends ReadonlyField {
 	function Field() {
 		$valforInput = $this->value ? Convert::raw2att($this->value) : "";
@@ -231,7 +236,12 @@ function HtmlEditorField_dataValue_processImage($parts) {
 	return $result;
 }
 
-
+/**
+ * External toolbar for the HtmlEditorField.
+ * This is used by the CMS
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class HtmlEditorField_Toolbar extends ViewableData {
 	protected $controller, $name;
 	
@@ -414,7 +424,10 @@ class HtmlEditorField_Toolbar extends ViewableData {
 
 
 /**
- * These controls are used when manually constructing a toolbar, as we do in the CMS
+ * Base class for HTML editor toolbar buttons.
+ * These controls are used when manually constructing a toolbar, as we do in the CMS.
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class HtmlEditorField_control extends ViewableData {
 	protected $command;
@@ -423,6 +436,11 @@ class HtmlEditorField_control extends ViewableData {
 	function Command() { return $this->command; }
 }
 
+/**
+ * Button on the HTML edityor toolbar.
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class HtmlEditorField_button extends HtmlEditorField_control {
 	function __construct($command, $icon, $title = null) {
 		$this->title = $title ? $title : $command;
@@ -452,8 +470,20 @@ class HtmlEditorField_button extends HtmlEditorField_control {
 		return $this->icon;
 	}
 }
+
+/**
+ * Separator on the HTML edityor toolbar.
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class HtmlEditorField_separator extends HtmlEditorField_control {
 }
+
+/**
+ * Dropdown field on the HTML editor toolbar.
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class HtmlEditorField_dropdown extends HtmlEditorField_control {
 	protected $options, $idSegment;
 	
@@ -477,6 +507,12 @@ class HtmlEditorField_dropdown extends HtmlEditorField_control {
 		return $this->idSegment;
 	}
 }
+
+/**
+ * Line break on the HTML editor toolbar.
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class HtmlEditorField_break extends HtmlEditorField_control {
 }
 

forms/InlineFormAction.php

@@ -53,6 +53,11 @@ class InlineFormAction extends FormField {
 	}
 }
 
+/**
+ * Readonly version of {@link InlineFormAction}.
+ * @package forms
+ * @subpackage actions
+ */
 class InlineFormAction_ReadOnly extends FormField {
 	function Field() {
 		return "<input type=\"submit\" name=\"action_{$this->name}\" value=\"{$this->title}\" id=\"{$this->id()}\" disabled=\"disabled\" class=\"action$extraClass\" />";

forms/LookupField.php

@@ -5,7 +5,6 @@
  * @subpackage fields-basic
  */
 
-
 /**
  * Read-only complement of {@link DropdownField}.
  * Shows the "human value" of the dropdown field for the currently selected value.

forms/SimpleImageField.php

@@ -54,6 +54,11 @@ class SimpleImageField extends FileField {
 	} 
 }
 
+/**
+ * Disabled version of {@link SimpleImageField}.
+ * @package forms
+ * @subpackage fields-files
+ */
 class SimpleImageField_Disabled extends FormField {
 		
 	function Field() {

forms/SubmittedFileField.php

@@ -6,6 +6,7 @@
 
 /**
  * A file uploaded on a UserDefinedForm field
+ * @package cms
  */
 class SubmittedFileField extends SubmittedFormField {
 	

forms/SubmittedForm.php

@@ -5,8 +5,8 @@
  */
 
 /**
- * SubmittedForm
  * Contents of an UserDefinedForm submission
+ * @package cms
  */
 class SubmittedForm extends DataObject {
 	static $has_one = array(

forms/SubmittedFormField.php

@@ -5,10 +5,9 @@
  */
 
 /**
- * SubmittedFormField
  * Data received from a UserDefinedForm submission
+ * @package cms
  */
- 
 class SubmittedFormField extends DataObject {
 	
 	static $db = array(

forms/SubmittedFormReportField.php

@@ -5,10 +5,9 @@
  */
 
 /**
- * SubmittedFormReportField
  * Displays a summary of instances of a form submitted to the website
+ * @package cms
  */
-	
 class SubmittedFormReportField extends FormField {
 	
 	/**

forms/TimeField.php

@@ -6,7 +6,7 @@
  */
 
 /**
- * Date field.
+ * Time field.
  * Default Value represented in the format passed as constructor.
  * 
  * @package forms
@@ -62,7 +62,9 @@ class TimeField extends TextField {
 }
 
 /**
- * The readonly class for our TimeField
+ * The readonly class for our {@link TimeField}.
+ * @package forms
+ * @subpackage fields-datetime
  */
 class TimeField_Readonly extends TimeField {
 	

forms/Validator.php

@@ -13,7 +13,6 @@
  * TODO Automatically mark fields after serverside validation and replace the form through
  * FormResponse if the request was made by ajax.
  * 
- * @example forms/Form.php See how you can create a form on your controller.
  * @package forms
  * @subpackage validators
  */ 

misc/Browscap.php

@@ -666,6 +666,8 @@ class Browscap
  * @copyright  Copyright (c) 2006 Jonathan Stoppani
  * @license    http://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License
  * @link       http://garetjax.info/projects/browscap/
+ * @package sapphire
+ * @subpackage misc
  */
 class Browscap_Exception extends Exception
 {}

parsers/HTML/BBCodeParser/Filter.php

@@ -4,11 +4,15 @@
  * @subpackage misc
  */
 
+/**
+ */
 require_once 'HTML/HTMLBBCodeParser.php';
 
 /**
-*   Dummy class that filters need to extend from.
+ * Dummy class that filters need to extend from.
-*/
+ * @package  sapphire
+ * @subpackage misc
+ */
 class SSHTMLBBCodeParser_Filter extends SSHTMLBBCodeParser
 {
 }

parsers/HTML/BBCodeParser/Filter/Basic.php

@@ -26,11 +26,15 @@
  */
 
 
+/**
+ */
 require_once 'HTML/BBCodeParser/Filter.php';
 
 
-
+/**
-
+ * @package  sapphire
+ * @subpackage misc
+ */
 class SSHTMLBBCodeParser_Filter_Basic extends SSHTMLBBCodeParser_Filter
 {
 

parsers/HTML/BBCodeParser/Filter/EmailLinks.php

@@ -26,11 +26,17 @@
  */
 
 
+/**
+ */
 require_once 'HTML/BBCodeParser/Filter.php';
 
 
 
 
+/**
+ * @package  sapphire
+ * @subpackage misc
+ */
 class SSHTMLBBCodeParser_Filter_EmailLinks extends SSHTMLBBCodeParser_Filter
 {
 

parsers/HTML/BBCodeParser/Filter/Extended.php

@@ -25,12 +25,16 @@
  * @author   Stijn de Reede  <sjr@gmx.co.uk>
  */
 
-
+/**
+ */
 require_once 'HTML/BBCodeParser/Filter.php';
 
 
 
-
+/**
+ * @package  sapphire
+ * @subpackage misc
+ */
 class SSHTMLBBCodeParser_Filter_Extended extends SSHTMLBBCodeParser_Filter
 {
 

parsers/HTML/BBCodeParser/Filter/Images.php

@@ -24,8 +24,15 @@
  * @subpackage misc
  * @author   Stijn de Reede  <sjr@gmx.co.uk>
  */
+
+/**
+ */
 require_once 'HTML/BBCodeParser/Filter.php';
 
+/**
+ * @package  sapphire
+ * @subpackage misc
+ */
 class SSHTMLBBCodeParser_Filter_Images extends SSHTMLBBCodeParser_Filter
 {
 

parsers/HTML/BBCodeParser/Filter/Links.php

@@ -24,10 +24,14 @@
  * @subpackage misc
  * @author   Stijn de Reede  <sjr@gmx.co.uk>
  */
+
+/**
+ */
 require_once 'HTML/BBCodeParser/Filter.php';
 
 /**
- *
+ * @package  sapphire
+ * @subpackage misc
  */
 class SSHTMLBBCodeParser_Filter_Links extends SSHTMLBBCodeParser_Filter
 {

parsers/HTML/BBCodeParser/Filter/Lists.php

@@ -26,10 +26,13 @@
  * @author   Stijn de Reede  <sjr@gmx.co.uk>
  */
 
+/**
+ */
 require_once 'HTML/BBCodeParser/Filter.php';
 
 /**
- * 
+ * @package  sapphire
+ * @subpackage misc
  */
 class SSHTMLBBCodeParser_Filter_Lists extends SSHTMLBBCodeParser_Filter
 {

parsers/HTML/HTMLBBCodeParser.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package  sapphire
+ * @subpackage misc
+ */
+
 /* vim: set expandtab tabstop=4 shiftwidth=4: */
 // +----------------------------------------------------------------------+
 // | PHP Version 4                                                        |
@@ -21,41 +27,38 @@
 // Modified by SilverStripe www.silverstripe.com
 
 /**
-* @package  sapphire
+ * @package  sapphire
-* @subpackage misc
+ * @subpackage misc
-* @author   Stijn de Reede  <sjr@gmx.co.uk> , SilverStripe
+ * @author   Stijn de Reede  <sjr@gmx.co.uk> , SilverStripe
-*
+ *
-*
+ *
-* This is a parser to replace UBB style tags with their html equivalents. It
+ * This is a parser to replace UBB style tags with their html equivalents. It
-* does not simply do some regex calls, but is complete stack based
+ * does not simply do some regex calls, but is complete stack based
-* parse engine. This ensures that all tags are properly nested, if not,
+ * parse engine. This ensures that all tags are properly nested, if not,
-* extra tags are added to maintain the nesting. This parser should only produce
+ * extra tags are added to maintain the nesting. This parser should only produce
-* xhtml 1.0 compliant code. All tags are validated and so are all their attributes.
+ * xhtml 1.0 compliant code. All tags are validated and so are all their attributes.
-* It should be easy to extend this parser with your own tags, see the _definedTags
+ * It should be easy to extend this parser with your own tags, see the _definedTags
-* format description below.
+ * format description below.
-*
+ *
-*
+ *
-* Usage:
+ * Usage:
-* $parser = new SSHTMLBBCodeParser();
+ * $parser = new SSHTMLBBCodeParser();
-* $parser->setText('normal [b]bold[/b] and normal again');
+ * $parser->setText('normal [b]bold[/b] and normal again');
-* $parser->parse();
+ * $parser->parse();
-* echo $parser->getParsed();
+ * echo $parser->getParsed();
-* or:
+ * or:
-* $parser = new SSHTMLBBCodeParser();
+ * $parser = new SSHTMLBBCodeParser();
-* echo $parser->qparse('normal [b]bold[/b] and normal again');
+ * echo $parser->qparse('normal [b]bold[/b] and normal again');
-* or:
+ * or:
-* echo SSHTMLBBCodeParser::staticQparse('normal [b]bold[/b] and normal again');
+ * echo SSHTMLBBCodeParser::staticQparse('normal [b]bold[/b] and normal again');
-*
+ *
-*
+ *
-* Setting the options from the ini file:
+ * Setting the options from the ini file:
-* $config = parse_ini_file('BBCodeParser.ini', true);
+ * $config = parse_ini_file('BBCodeParser.ini', true);
-* $options = &PEAR::getStaticProperty('SSHTMLBBCodeParser', '_options');
+ *  $options = &PEAR::getStaticProperty('SSHTMLBBCodeParser', '_options');
-* $options = $config['SSHTMLBBCodeParser'];
+ * $options = $config['SSHTMLBBCodeParser'];
-* unset($options);
+ * unset($options);
-*
+ */
-*
-*/
-
 class SSHTMLBBCodeParser
 {
     /**

security/Group.php

@@ -178,6 +178,12 @@ class Group extends DataObject {
 		}
 	}
 }
+
+/**
+ * A group representing everyone, including users not logged in.
+ * @package sapphire
+ * @subpackage security
+ */
 class Group_Unsecure extends Group {
 }
 ?>

security/Member.php

@@ -815,6 +815,8 @@ class Member extends DataObject {
 /**
  * Special kind of {@link ComponentSet} that has special methods for
  * manipulating a user's membership
+ * @package sapphire
+ * @subpackage security
  */
 class Member_GroupSet extends ComponentSet {
 	/**
@@ -1019,6 +1021,11 @@ class Member_GroupSet extends ComponentSet {
 
 
 
+/**
+ * Form for editing a member profile.
+ * @package sapphire
+ * @subpackage security
+ */
 class Member_ProfileForm extends Form {
 	
 	function __construct($controller, $name, $member) {
@@ -1073,6 +1080,8 @@ class Member_ProfileForm extends Form {
 
 /**
  * Class used as template to send an email to new members
+ * @package sapphire
+ * @subpackage security
  */
 class Member_SignupEmail extends Email_Template {
 	protected $from = '';  // setting a blank from address uses the site's default administrator email
@@ -1129,6 +1138,8 @@ class Member_SignupEmail extends Email_Template {
 /**
  * Class used as template to send an email saying that the password has been
  * changed
+ * @package sapphire
+ * @subpackage security
  */
 class Member_ChangePasswordEmail extends Email_Template {
     protected $from = '';   // setting a blank from address uses the site's default administrator email
@@ -1145,6 +1156,8 @@ class Member_ChangePasswordEmail extends Email_Template {
 
 /**
  * Class used as template to send the forgot password email
+ * @package sapphire
+ * @subpackage security
  */
 class Member_ForgotPasswordEmail extends Email_Template {
     protected $from = '';  // setting a blank from address uses the site's default administrator email
@@ -1160,9 +1173,9 @@ class Member_ForgotPasswordEmail extends Email_Template {
 
 
 /**
- * Record to keep track of which records a member has unsubscribed from and
+ * Record to keep track of which records a member has unsubscribed from and when.
- * when
+ * @package sapphire
- *
+ * @subpackage security
  * @todo Check if that email stuff ($from, $to, $subject, $body) is needed
  *       here! (Markus)
  */
@@ -1219,6 +1232,8 @@ class Member_UnsubscribeRecord extends DataObject {
 
 /**
  * Member Validator
+ * @package sapphire
+ * @subpackage security
  */
 class Member_Validator extends RequiredFields {
 

security/Permission.php

@@ -542,6 +542,8 @@ class Permission extends DataObject {
  *
  * This class is used to group permissions together for showing on an
  * interface.
+ * @package sapphire
+ * @subpackage security
  */
 class Permission_Group {
 

tools/importer.php

@@ -6,10 +6,10 @@
  */
 
 /**
- ** Contains heaps of tools that you can use when importing database information
+ * Contains heaps of tools that you can use when importing database information
- **/
+ * @package sapphire
-
+ * @subpackage misc
-
+ */
 class importer_Controller extends Page_Controller {
 
 	// Generates the URLsegment for every page that doesn't have one.