Updated API documentation package tags

Fixed some whitespace

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

api/RSSFeed.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
+
 /**
  * RSSFeed class
  *

api/RestfulService.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
+
 /**
  * RestfulService class allows you to consume various RESTful APIs.
  * Through this you could connect and aggregate data of various web services.

api/SapphireSoapServer.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
+
+/**
+ * Soap server class
+ */
 class SapphireSoapServer extends Controller {
 	static $methods = array();
 	static $xsd_types = array(

api/SimplePie.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage integration
+ */
+
 /****************************************************
 SIMPLEPIE
 A PHP-Based RSS and Atom Feed Framework

api/Spyc.php

@@ -1,5 +1,5 @@
 <?php
-  /**
+/**
  * Spyc -- A Simple PHP YAML Class
  * @version 0.2.(5) -- 2006-12-31
  * @author Chris Wanstrath <chris@ozmm.org>
@@ -7,14 +7,14 @@
  * @link http://spyc.sourceforge.net/
  * @copyright Copyright 2005-2006 Chris Wanstrath
  * @license http://www.opensource.org/licenses/mit-license.php MIT License
-   * @package Spyc
+ * @package sapphire
+ * @subpackage misc
  */
 
-  /**
+/**
  * A node, used by Spyc for parsing YAML.
-   * @package Spyc
  */
-  class YAMLNode {
+class YAMLNode {
   /**#@+
    * @access public
    * @var string
@@ -46,9 +46,9 @@
    public function YAMLNode($nodeId) {
     $this->id = $nodeId;
   }
-  }
+}
 
-  /**
+/**
  * The Simple PHP YAML Class.
  *
  * This class can be used to read a YAML file and convert its contents
@@ -60,9 +60,8 @@
  *   $parser = new Spyc;
  *   $array  = $parser->load($file);
  * </code>
-   * @package Spyc
  */
-  class Spyc {
+class Spyc {
 
   /**
    * Load YAML into a PHP array statically
@@ -863,5 +862,5 @@
     }
     return $ret;
   }
-  }
+}
 ?>

cli/CliController.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage cron
+ */
+
 /**
 * Base class invoked from CLI rather than the webserver (Cron jobs, handling email bounces)
 */

cli/DailyTask.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage cron
+ */
+
 /**
  * Classes that must be run daily extend this class
  */

cli/MonthlyTask.php

@@ -1,6 +1,12 @@
 <?php
+
 /**
- * Executed a task monthly
+ * @package sapphire
+ * @subpackage cron
+ */
+
+/**
+ * Classes that must be run monthly extend this class
  */
 class MonthlyTask extends ScheduledTask {
 

cli/ScheduledTask.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage cron
+ */
+
+/**
+ * Abstract task representing scheudled tasks
+ */
 abstract class ScheduledTask extends CliController {
     // this class exists as a logical extension
 }  

cli/WeeklyTask.php

@@ -1,4 +1,13 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage cron
+ */
+
+/**
+ * Classes that must be run weekly extend this class
+ */
 class WeeklyTask extends ScheduledTask {
 
 }

core/ArrayData.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage view
+ */
+
 /**
  * Lets you wrap a bunch of array data into a ViewableData object.
  * This is useful when you want to pass data to a template in the "SilverStripe 1" way of giving a 

core/ArrayLib.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
+/**
+ * Library of static methods for manipulating arrays.
+ */
 class ArrayLib extends Object {
 	static function invert($arr) {
 		if (! $arr) return false;

core/ClassInfo.php

@@ -3,6 +3,9 @@
  * Provides introspection information about the class tree.
  * It's a cached wrapper around the built-in class functions.  Sapphire uses class introspection heavily
  * and without the caching it creates an unfortunate performance hit.
+ *
+ * @package sapphire
+ * @subpackage core
  */
 class ClassInfo {
 	/**

core/Convert.php

@@ -14,6 +14,9 @@
  *
  *  html: HTML source suitable for use in a page or email
  *  text: Plain-text content, suitable for display to a user as-is, or insertion in a plaintext email.
+ *
+ * @package sapphire
+ * @subpackage misc
  */
 class Convert extends Object {
 	// Convert raw to other formats

core/Cookie.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
+/**
+ * A set of static methods for manipulating cookies.
+ */
 class Cookie extends Object {
 	/**
 	 * Set a cookie variable

core/Core.php

@@ -1,4 +1,11 @@
 <?php
+/**
+ * This file contains several methods that control the core behaviour of Sapphire.
+ *
+ * @package sapphire
+ * @subpackage core
+ */
+
 /**
  * Returns the temporary folder that sapphire/silverstripe should use for its cache files
  * This is loaded into the TEMP_FOLDER define on start up

core/Debug.php

@@ -1,6 +1,9 @@
 <?php
 /**
  * Class of static methods to support debugging.
+ *
+ * @package sapphire
+ * @subpackage core
  */
 class Debug {
 	

core/Email.php

@@ -1,8 +1,16 @@
 <?php
 
-define('X_MAILER', 'SilverStripe Mailer - version 2006.06.21 (Sent from "'.$_SERVER['SERVER_NAME'].'")');
+/**
+ * @package sapphire
+ * @subpackage email
+ */
 
+/**
+ * X-Mailer header value on emails sent
+ */
+define('X_MAILER', 'SilverStripe Mailer - version 2006.06.21 (Sent from "'.$_SERVER['SERVER_NAME'].'")');
 // Note: The constant 'BOUNCE_EMAIL' should be defined as a valid email address for where bounces should be returned to.
+
 /**
  * Class to support sending emails.
  */

core/Extension.php

@@ -3,6 +3,9 @@
 /**
  * Add extension that can be added to an object with Object::add_extension().
  * For DataObject extensions, use DataObjectDecorator
+ *
+ * @package sapphire
+ * @subpackage core
  */
 
 abstract class Extension extends Object {

core/HTTP.php

@@ -3,6 +3,9 @@
 /**
  * A class with HTTP-related helpers.
  * Like Debug, this is more a bundle of methods than a class ;-)
+ * 
+ * @package sapphire
+ * @subpackage misc
  */
 class HTTP {
 

core/ManifestBuilder.php

@@ -1,7 +1,12 @@
 <?php
 
 /**
- * ManifestBuilder
+ * Name of the manifest file
+ */
+define("MANIFEST_FILE", TEMP_FOLDER . "/manifest" . str_replace(array("/",":", "\\"),"_", $_SERVER['SCRIPT_FILENAME']));
+
+/**
+ * The ManifestBuilder class generates the manifest file and keeps it fresh.
  * 
  * The manifest file is a PHP include that contains global variables that
  * represent the collected contents of the application:
@@ -12,21 +17,9 @@
  * Traversing the filesystem to collect this information on everypage.
  * This information is cached so that it need not be regenerated on every
  * pageview.
- */
-
-
-
-/**
- * Define a constant for the name of the manifest file
- */
-define("MANIFEST_FILE", TEMP_FOLDER . "/manifest" . str_replace(array("/",":", "\\"),"_", $_SERVER['SCRIPT_FILENAME']));
-
-
-
-/**
- * ManifestBuilder
  *
- * The ManifestBuilder class generates the manifest file and keeps it fresh.
+ * @package sapphire
+ * @subpackage core
  */
 class ManifestBuilder {
 

core/Object.php

@@ -1,9 +1,14 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage core
+ */
+
 /**
  * Base object that all others should inherit from.
  * This object provides a number of helper methods that patch over PHP's deficiencies.
  */
-
 class Object {
 	/**
 	 * This DataObjects extensions, eg Versioned.

core/Requirements.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage view
+ */
+
 /**
  * Requirements tracker, for javascript and css.
  * @todo Document the requirements tracker, and discuss it with the others.

core/SSViewer.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage view
+ */
+
 /**
  * The SSViewer executes a .ss template file.
  * The SSViewer class handles rendering of .ss templates.  In addition to a full template in

core/Session.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage control
+ */
+
 /**
  * Handles all manipulation of the session.
  * 
@@ -12,14 +17,6 @@
  * 
  * The instance object is basically just a way of manipulating a set of nested maps, and isn't specific to session data.
  * This class is currently really basic and could do with a more well-thought-out implementation
- *
- * $session->myVar = 'XYZ' would be fine, as would Session::data->myVar.  What about the equivalent
- * of Session::get('member.abc')?  Are the explicit accessor methods acceptable?  Do we need a
- * broader spectrum of functions, such as Session::inc("cart.$productID", 2)?  And what should 
- * Session::get("cart") then return?  An array?
- *
- * @todo Decide whether this class is really necessary, and if so, overhaul it.  Perhaps use
- * __set() and __get() on an instance, rather than static functions?
  */
 class Session {
 	public static function set($name, $val) {

core/ViewableData.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage view
  */
 
 /**

core/control/ContentController.php

@@ -12,6 +12,9 @@
  *
  * Subclasses of ContentController are generally instantiated by ModelAsController; this will create
  * a controller based on the URLSegment action variable, by looking in the SiteTree table.
+ *
+ * @package sapphire
+ * @subpackage control
  */
 class ContentController extends Controller {
 	protected $dataRecord;

core/control/ContentNegotiator.php

@@ -1,4 +1,8 @@
 <?php
+/**
+ * @package sapphire
+ * @subpackage control
+ */
 
 /**
  * The content negotiator performs text/html or application/xhtml+xml switching.

core/control/Controller.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage control
+ */
+
 /**
  * Base controller class.
  * Controllers are the cornerstone of all site functionality in Sapphire.  The {@link Director}

core/control/Director.php

@@ -6,6 +6,9 @@
  * one of a number of patterns, and determines the controller, action and any argument to be
  * used.  It then runs the controller, which will finally run the viewer and/or perform processing
  * steps.
+ *
+ * @package sapphire
+ * @subpackage control
  */
 class Director {
 	

core/control/FormResponse.php

@@ -21,6 +21,9 @@
  * 
  * TODO Force a specific execution order ($forceTop, $forceBottom)
  * TODO Extension to return different formats, e.g. JSON or XML
+ *
+ * @package sapphire
+ * @subpackage forms
  */
 class FormResponse {
 	

core/control/HTTPResponse.php

@@ -2,6 +2,9 @@
 
 /**
  * Represenets an HTTPResponse returned by a controller.
+ *
+ * @package sapphire
+ * @subpackage control
  */
 class HTTPResponse extends Object {
 	protected static $status_codes = array(

core/control/ModelAsController.php

@@ -4,6 +4,9 @@
  * ModelAsController will hand over all control to the appopriate model object
  * It uses URLSegment to determine the right object.  Also, if (ModelClass)_Controller exists,
  * that controller will be used instead.  It should be a subclass of ContentController.
+ *
+ * @package sapphire
+ * @subpackage control
  */
 class ModelAsController extends Controller implements NestedController {
 	

core/control/NestedController.php

@@ -1,5 +1,16 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage control
+ */
+
+/**
+ * Interface that is implemented by controllers that are designed to hand control over to another controller.  
+ * ModelAsController, which selects up a SiteTree object and passes control over to a suitable subclass of ContentController, is a good
+ * example of this.
+ */
+ 
 interface NestedController {
 	public function getNestedController();
 

core/control/RootURLController.php

@@ -1,7 +1,10 @@
 <?php
 
 /**
- * This controller handles what happens when you visit the root URL
+ * This controller handles what happens when you visit the root URL.
+ *
+ * @package sapphire
+ * @subpackage control
  */
 class RootURLController extends Controller {
 	protected static $is_at_root = false;

core/i18n.php

@@ -21,6 +21,8 @@
  * Please see the {Translatable} DataObjectDecorator for managing translations of database-content.
  *
  * @author Bernat Foj Capell <bernat@silverstripe.com>
+ * @package sapphire
+ * @subpackage misc
  */
 
 class i18n extends Controller {

core/model/ComponentSet.php

@@ -1,8 +1,7 @@
 <?php
-
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 /**

core/model/CurrentPageIdentifier.php

@@ -1,8 +1,7 @@
 <?php
 
 /**
- * @package sapphire
+ * @package cms
- * @subpackage core
  */
 
 /**

core/model/DB.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 /**

core/model/DataObject.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 /**

core/model/DataObjectDecorator.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 

core/model/DataObjectInterface.php

@@ -1,4 +1,8 @@
 <?php
+/**
+ * @package sapphire
+ * @subpackage model
+ */
 
 /** 
  * DataObjectInterface is an interface that other data systems in your application can implement in order to behave in a manner

core/model/DataObjectLog.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 /**

core/model/DataObjectSet.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 /**

core/model/Database.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 /**

core/model/DatabaseAdmin.php

@@ -4,7 +4,7 @@
  * Database Administration
  *
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 

core/model/ErrorPage.php

@@ -1,8 +1,7 @@
 <?php
 
 /**
- * @package sapphire
+ * @package cms
- * @subpackage core
  */
 
 /**

core/model/GhostPage.php

@@ -1,8 +1,7 @@
 <?php
 
 /**
- * @package sapphire
+ * @package cms
- * @subpackage core
  */
 
 /**

core/model/HiddenClass.php

@@ -1,8 +1,7 @@
 <?php
 
 /**
- * @package sapphire
+ * @package cms
- * @subpackage core
  */
 
 /**

core/model/Hierarchy.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 /**

core/model/Image.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage filesystem
  */
 
 /**

core/model/MySQLDatabase.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 /**

core/model/PDODatabase.php

@@ -2,7 +2,7 @@
 
 /**
  * @package sapphire
- * @subpackage core
+ * @subpackage model
  */
 
 /**

core/model/PageView.php

@@ -1,7 +1,6 @@
 <?php
 /**
- * @package sapphire
+ * @package cms
- * @subpackage core
  */
 
 /**

core/model/RedirectorPage.php

@@ -1,5 +1,9 @@
 <?php
 
+/**
+ * @package cms
+ */
+
 /**
  * A redirector page redirects when the page is visited.
  */

core/model/SQLMap.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
 /**
  * This is a class used to represent key->value pairs generated from database queries.
  * The query isn't actually executed until you need it.

core/model/SQLQuery.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
 /**
  * Object representing a SQL query.
  * The various parts of the SQL query can be manipulated individually.

core/model/SiteTree.php

@@ -1,7 +1,7 @@
 <?php
+
 /**
- * @package sapphire
+ * @package cms
- * @subpackage core
  */
 
 /**

core/model/Translatable.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /**
  * The {Translatable} decorator allows your DataObjects to have versions in different languages,
  * defining which fields are can be translated.

core/model/Versioned.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
 /**
  * The Versioned decorator allows your DataObjects to have several versions, allowing
  * you to rollback changes and view history. An example of this is the pages used in the CMS.

core/model/VirtualPage.php

@@ -1,5 +1,9 @@
 <?php
 
+/**
+ * @package cms
+ */
+
 /**
 * Virtual Page creates an instance of a  page, with the same fields that the original page had, but readonly.
 * This allows you can have a page in mulitple places in the site structure, with different children without duplicating the content

core/model/fieldtypes/Boolean.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
 /**
  * Represents a boolean field.
  * 

core/model/fieldtypes/Currency.php

@@ -1,6 +1,12 @@
 <?php
+
 /**
- * Currency value.
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents a decimal field containing a currency amount.
  * Currency the currency class only supports single currencies.
  */
 class Currency extends Decimal {

core/model/fieldtypes/DBField.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
 /**
  * Single field in the database.
  * Every field from the database is represented as a sub-class of DBField.  In addition to supporting

core/model/fieldtypes/Date.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents a date field.
+ */
 class Date extends DBField {
 	
 	function setValue($value) {

core/model/fieldtypes/Datetime.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
 if(!class_exists('Datetime')) {
 	class Datetime extends Date {
 		function __construct($name) {

core/model/fieldtypes/Decimal.php

@@ -1,6 +1,12 @@
 <?php
+
 /**
- * Decimal value.
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents a Decimal field.
  */
 class Decimal extends DBField {
 	protected $wholeSize, $decimalSize;

core/model/fieldtypes/Enum.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents an enumeration field.
+ */
 class Enum extends DBField {
 	
 	protected $enum, $default;

core/model/fieldtypes/Float.php

@@ -1,6 +1,12 @@
 <?php
+
 /**
- * 
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents a floating point field.
  */
 class Float extends DBField {
 	

core/model/fieldtypes/HTMLText.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents a large text field that contains HTML content.
+ * 
+ * This behaves similarly to Text, but the template processor won't escape any HTML content within it.
+ */
 class HTMLText extends Text {
 
 	/**

core/model/fieldtypes/HTMLVarchar.php

@@ -1,8 +1,14 @@
 <?php
 
 /**
- * This behaves exactly the same as Varchar but is intended to store HTML content in it.
+ * @package sapphire
- * The template processor won't escape any HTML content within it
+ * @subpackage model
+ */
+
+/**
+ * Represents a short text field that is intended to contain HTML content.
+ *
+ * This behaves similarly to Varchar, but the template processor won't escape any HTML content within it.
  */
 class HTMLVarchar extends Varchar {
 

core/model/fieldtypes/Int.php

@@ -1,5 +1,13 @@
 <?php
+
 /**
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents an integer field.
+ *
  * @param $defaultVal int
  */
 class Int extends DBField {

core/model/fieldtypes/Percentage.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents a decimal field from 0-1 containing a percentage value.
+ */
 class Percentage extends Decimal {
 	
 	/**

core/model/fieldtypes/SSDatetime.php

@@ -1,4 +1,13 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents a date-time field.
+ */
 class SSDatetime extends Date {
 	function setValue($value) {
 		if($value) $this->value = date('Y-m-d H:i:s', strtotime($value));

core/model/fieldtypes/Text.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents a long text field.
+ */
 class Text extends DBField {
 	static $casting = array(
 		"AbsoluteLinks" => "HTMLText",

core/model/fieldtypes/Time.php

@@ -1,8 +1,13 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
 /**
  * Represents a column in the database with the type 'Time'
  */
- 
 class Time extends DBField {
 
 	function setVal($value) {

core/model/fieldtypes/Varchar.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage model
+ */
+
+/**
+ * Represents a short text field.
+ */
 class Varchar extends DBField {
 	protected $size;
 	

email/Notifications.php

@@ -1,5 +1,9 @@
 <?php
 
+/**
+ * @package cms
+ */
+
 /**
  * The Notifications class allows you to create email notifications for various events.
  * It lets your scripts generate a number of notifications, and delay sending of the emails until

email/QueuedEmail.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage email
+ */
+
 /**
  * Stores a queued email to be sent at the given time
  */

email/QueuedEmailDispatchTask.php

@@ -1,4 +1,13 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage email
+ */
+
+/**
+ * Daily task to send queued email.
+ */
 class QueuedEmailDispatchTask extends DailyTask {
 	
 	public function process() {

filesystem/Archive.php

@@ -1,6 +1,18 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage filesystem
+ */
+
+/**
+ * Class for handling archives.
+ * To implement a specific archive system, create a subclass of this abstract class, and amend the implementation of Archive::open().
+ */
 abstract class Archive extends Object {
+	/**
+	 * Return an Archive object for the given file.
+	 */
 	static function open($filename) {
 		if(substr($filename, strlen($filename) - strlen('.tar.gz')) == '.tar.gz' ||
 			substr($filename, strlen($filename) - strlen('.tar.bz2')) == '.tar.bz2' ||

filesystem/File.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage filesystem
+ */
+
 /**
  * This class handles the representation of a File within Sapphire
  * Note: The files are stored in the "/assets/" directory, but sapphire

filesystem/Filesystem.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage filesystem
+ */
+
+/**
+ * A collection of static methods for manipulating the filesystem.
+ */
 class Filesystem extends Object {
 	
 	public static $file_create_mask = 02775;

filesystem/Folder.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage filesystem
+ */
+
+/**
+ * Represents a folder in the assets directory.
+ */
 class Folder extends File {
 	
 	static $many_many = array(

filesystem/GD.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage filesystem
+ */
+
 /**
  * A wrapper class for GD-based images, with lots of manipulation functions.
  */

filesystem/PostBackup.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * Writes the POST array to a file as a last-ditch effort to preserve entered data.
  */

filesystem/TarballArchive.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage filesystem
+ */
+
+/**
+ * Implementation of .tar, .tar.gz, and .tar.bz2 archive handler.
+ */
 class TarballArchive extends Archive {
 	private $filename = '';
 	private $compressionModifiers = '';

forms/ComplexTableField.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * Provides a tabuar list in your form with view, edit and add links to edit records
  * with a "has-one"-relationship. Detail-views are shown in a greybox-iframe.

forms/EditableButton.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 	/**
 	 * EditableButton
 	 * Allows a user to modify the text on the button

forms/EditableCheckbox.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 	/**
 	 * EditableCheckbox
 	 * A user modifiable checkbox on a UserDefinedForm

forms/EditableCheckboxGroupField.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 	/**
  * EditableDropdown
  * Represents a set of selectable radio buttons

forms/EditableCheckboxOption.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 	/**
 	 * EditableDropdownOption
 	 * Represents a single entry in an EditableRadioField

forms/EditableDateField.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * EditableDateField
  * Allows a user to add a date field to the Field Editor

forms/EditableDropdown.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 	/**
 	 * EditableDropdown
 	 * Represents a modifiable dropdown box on a form

forms/EditableDropdownOption.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 	/**
 	 * EditableDropdownOption
 	 * Represents a single entry in an EditableDropdown

forms/EditableEmailField.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 	/**
 	 * EditableEmailField
 	 * Allow users to define a validating editable email field for a UserDefinedForm

forms/EditableFileField.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * EditableFileField
  * Allows a user to add a field that can be used to upload a file

forms/EditableFormField.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * Represents an editable form field
  */

forms/EditableFormHeading.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * Allows an editor to insert a generic heading into a field
  */

forms/EditableMemberListField.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * Creates an editable field that displays members in a given group
  */

forms/EditableRadioField.php

@@ -1,5 +1,11 @@
 <?php
-	/**
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
+/**
  * EditableDropdown
  * Represents a set of selectable radio buttons
  */

forms/EditableRadioOption.php

@@ -1,5 +1,11 @@
 <?php
-	/**
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
+/**
  * EditableDropdownOption
  * Represents a single entry in an EditableRadioField
  */

forms/EditableTextField.php

@@ -1,5 +1,11 @@
 <?php
-	/**
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
+/**
  * EditableTextField
  * This control represents a user-defined field in a user defined form
  */

forms/Form.php

@@ -1,7 +1,8 @@
 <?php
 
 /**
- * Bulk of the form system
+ * @package sapphire
+ * @subpackage forms
  */
 
 /**

forms/FormField.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * Represents a field in a form.  
  * A FieldSet contains a number of FormField objects which make up the whole of a form.

forms/FormTransformation.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * This class represents "transformations" of a form - such as making it printable or making it readonly.
  * The idea is that sometimes you will want to make your own such transformations, and you shouldn't have

forms/HasManyComplexTableField.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 class HasManyComplexTableField extends ComplexTableField {
 		
 	public $joinField;

forms/HasOneComplexTableField.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 class HasOneComplexTableField extends HasManyComplexTableField {
 	
 	protected $itemClass = 'HasOneComplexTableField_Item';

forms/HtmlEditorField.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * A WYSIWYG editor field, powered by tinymce.
  * tinymce editor fields are created from <textarea> tags which are then converted with javascript.

forms/ManyManyComplexTableField.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 class ManyManyComplexTableField extends HasManyComplexTableField {
 	
 	private $manyManyParentClass;

forms/ReportField.php

@@ -1,5 +1,9 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
 
 /**
  * Displays complex reports based on the list of tables and fields provided to

forms/SubmittedFileField.php

@@ -1,4 +1,12 @@
 <?php
+
+/**
+ * @package cms
+ */
+
+/**
+ * A file uploaded on a UserDefinedForm field
+ */
 class SubmittedFileField extends SubmittedFormField {
 	
 	static $has_one = array(

forms/SubmittedForm.php

@@ -1,4 +1,9 @@
 <?php
+
+/**
+ * @package cms
+ */
+
 /**
  * SubmittedForm
  * Contents of an UserDefinedForm submission

forms/SubmittedFormField.php

@@ -1,10 +1,15 @@
 <?php
-	/**
+
+/**
+ * @package cms
+ */
+
+/**
  * SubmittedFormField
  * Data received from a UserDefinedForm submission
  */
  
-	class SubmittedFormField extends DataObject {
+class SubmittedFormField extends DataObject {
 	
 	static $db = array(
 		"Name" => "Varchar",
@@ -15,5 +20,5 @@
 	static $has_one = array(
 		"Parent" => "SubmittedForm"
 	);
-	}
+}
 ?>

forms/SubmittedFormReportField.php

@@ -1,5 +1,10 @@
 <?php
-	/**
+
+/**
+ * @package cms
+ */
+
+/**
  * SubmittedFormReportField
  * Displays a summary of instances of a form submitted to the website
  */

forms/TableField.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * TableField behaves in the same manner as TableListField, however allows the addition of 
  * fields and editing of attributes specified, and filtering results.

forms/TableListField.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * Form field that embeds a list into a form, such as a member list or a file list.
  * 

forms/Validator.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage forms
+ */
+
 /**
  * This validation class handles all form and custom form validation through
  * the use of Required fields.

integration/XML.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /**
  * Base class for XML parsers
  */

misc/Browscap.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /**
  * Browscap.ini parsing class with caching and update capabilities
  *
@@ -19,7 +24,6 @@
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  *
- * @package    Browscap
  * @author     Jonathan Stoppani <st.jonathan@gmail.com>
  * @copyright  Copyright (c) 2006 Jonathan Stoppani
  * @version    0.7
@@ -656,7 +660,6 @@ class Browscap
 /**
  * Browscap.ini parsing class exception
  *
- * @package    Browscap
  * @author     Jonathan Stoppani <st.jonathan@gmail.com>
  * @copyright  Copyright (c) 2006 Jonathan Stoppani
  * @license    http://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License

misc/GoogleSitemap.php

@@ -1,10 +1,15 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /**
  * Initial implementation of Sitemap support.
  * GoogleSitemap should handle requests to 'sitemap.xml'
  * the other two classes are used to render the sitemap
  */
-
 class GoogleSitemap extends Controller {
 	protected $Pages;
 	

misc/IPS.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /**
  * Ioncube Performance Suite management
  */

misc/Statistics.php

@@ -1,5 +1,9 @@
 <?php
 
+/**
+ * @package cms
+ */
+
 /**
  * Statistics class for gathering and formatting of statistical data for tables and charts in
  * both public and administrative contexts.

parsers/BBCodeParser.php

@@ -1,5 +1,9 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
 
 require_once('HTML/HTMLBBCodeParser.php');
 /*Seting up the PEAR bbcode parser*/  
@@ -10,6 +14,10 @@ $options = $config['SSHTMLBBCodeParser'];
 unset($options);
 
 
+/**
+ * BBCode parser object.
+ * Use on a text field in a template with $Content.Parse(BBCodeParser).
+ */
 class BBCodeParser extends TextParser {
 
 	protected static $autolinkUrls = true;

parsers/HTML/BBCodeParser/Filter.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * @package  sapphire
+ * @subpackage misc
+ */
+
 require_once 'HTML/HTMLBBCodeParser.php';
 
 /**

parsers/HTML/BBCodeParser/Filter/Basic.php

@@ -20,9 +20,10 @@
 //
 
 /**
-* @package  SSHTMLBBCodeParser
+ * @package  sapphire
-* @author   Stijn de Reede  <sjr@gmx.co.uk>
+ * @subpackage misc
-*/
+ * @author   Stijn de Reede  <sjr@gmx.co.uk>
+ */
 
 
 require_once 'HTML/BBCodeParser/Filter.php';

parsers/HTML/BBCodeParser/Filter/EmailLinks.php

@@ -20,9 +20,10 @@
 //
 
 /**
-* @package  SSHTMLBBCodeParser
+ * @package  sapphire
-* @author   Stijn de Reede  <sjr@gmx.co.uk>
+ * @subpackage misc
-*/
+ * @author   Stijn de Reede  <sjr@gmx.co.uk>
+ */
 
 
 require_once 'HTML/BBCodeParser/Filter.php';

parsers/HTML/BBCodeParser/Filter/Extended.php

@@ -20,9 +20,10 @@
 //
 
 /**
-* @package  SSHTMLBBCodeParser
+ * @package  sapphire
-* @author   Stijn de Reede  <sjr@gmx.co.uk>
+ * @subpackage misc
-*/
+ * @author   Stijn de Reede  <sjr@gmx.co.uk>
+ */
 
 
 require_once 'HTML/BBCodeParser/Filter.php';

parsers/HTML/BBCodeParser/Filter/Images.php

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

parsers/HTML/BBCodeParser/Filter/Links.php

@@ -20,9 +20,10 @@
 //
 
 /**
-* @package  SSHTMLBBCodeParser
+ * @package  sapphire
-* @author   Stijn de Reede  <sjr@gmx.co.uk>
+ * @subpackage misc
-*/
+ * @author   Stijn de Reede  <sjr@gmx.co.uk>
+ */
 require_once 'HTML/BBCodeParser/Filter.php';
 
 /**

parsers/HTML/BBCodeParser/Filter/Lists.php

@@ -21,9 +21,10 @@
 
 
 /**
-* @package  SSHTMLBBCodeParser
+ * @package  sapphire
-* @author   Stijn de Reede  <sjr@gmx.co.uk>
+ * @subpackage misc
-*/
+ * @author   Stijn de Reede  <sjr@gmx.co.uk>
+ */
 
 require_once 'HTML/BBCodeParser/Filter.php';
 

parsers/HTML/HTMLBBCodeParser.php

@@ -21,7 +21,8 @@
 // Modified by SilverStripe www.silverstripe.com
 
 /**
-* @package  SSHTMLBBCodeParser
+* @package  sapphire
+* @subpackage misc
 * @author   Stijn de Reede  <sjr@gmx.co.uk> , SilverStripe
 *
 *

parsers/TextParser.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /**
  * Parses text in a variety of ways.
  * 

profiler/Profiler.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /********************************************************************************\
  * Copyright (C) Carl Taylor (cjtaylor@adepteo.com)                             *
  * Copyright (C) Torben Nehmer (torben@nehmer.net) for Code Cleanup             *
@@ -6,6 +12,10 @@
 \********************************************************************************/
 
 /// Enable multiple timers to aid profiling of performance over sections of code
+
+/**
+ * Execution time profiler.
+ */
 class Profiler {
     var $description;
     var $startTime;

search/AdvancedSearchForm.php

@@ -1,6 +1,12 @@
 <?php
+
 /**
- * Standard basical search form
+ * @package sapphire
+ * @subpackage search
+ */
+
+/**
+ * More advanced search form
  */
 class AdvancedSearchForm extends SearchForm {
 	

search/SearchForm.php

@@ -1,8 +1,13 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage search
+ */
+
 /**
  * Standard basic search form
  */
-
 class SearchForm extends Form {
 	
 	protected $showInSearchTurnOn;

security/Authenticator.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage security
+ */
+
 /**
  * Abstract base class for an authentication method
  *

security/BasicAuth.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage security
+ */
+
 /**
  * Provides an interface to HTTP basic authentication.
  */

security/ChangePasswordForm.php

@@ -1,10 +1,10 @@
 <?php
 
 /**
- * Change password form
+ * @package sapphire
+ * @subpackage security
  */
 
-
 /**
  * Standard Change Password Form
  */

security/Geoip.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /* Geoip.php 
 
  Known to work with the following versions of GeoIP:

security/Group.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage security
+ */
+
+/**
+ * A security group.
+ */
 class Group extends DataObject {
 	// This breaks too many things for upgraded sites
 	// static $default_sort = "Sort";

security/LoginForm.php

@@ -1,13 +1,11 @@
 <?php
 
 /**
- * LoginForm base class
- *
  * @author Markus Lanthaler <markus@silverstripe.com>
+ * @package sapphire
+ * @subpackage security
  */
 
-
-
 /**
  * Abstract base class for a login form
  *

security/Member.php

@@ -2,10 +2,10 @@
 
 /**
  * Member classes
+ * @package sapphire
+ * @subpackage security
  */
 
-
-
 /**
  * The member class which represents the users of the system
  */

security/MemberAuthenticator.php

@@ -1,13 +1,11 @@
 <?php
 
 /**
- * Member authenticator
+ * @package sapphire
- *
+ * @subpackage security
  * @author Markus Lanthaler <markus@silverstripe.com>
  */
 
-
-
 /**
  * Authenticator for the default "member" method
  *

security/MemberLoginForm.php

@@ -1,11 +1,10 @@
 <?php
 
 /**
- * Log-in form for the "member" authentication method
+ * @package sapphire
+ * @subpackage security
  */
 
-
-
 /**
  * Log-in form for the "member" authentication method
  */

security/Permission.php

@@ -1,4 +1,13 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage security
+ */
+
+/**
+ * Represents a permission assigned to a group.
+ */
 class Permission extends DataObject {
 
   // the (1) after Type specifies the DB default value which is needed for

security/PermissionDropdownField.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage security
+ */
+
 /**
  * Special kind of dropdown field that has all permission codes as its dropdown source.
  * Note: This would ordinarily be overkill; the main reason we have it is that TableField doesn't let you specify a dropdown source;

security/PermissionProvider.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage security
+ */
+
 /**
  * Used to let classes provide new permission codes.
  * Every implementor of PermissionProvider is accessed and providePermissions() called to get the full list of permission codes.

security/Security.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage security
+ */
+
 /**
  * Implements a basic security model
  */

synchronise/Synchronise.php

@@ -1,4 +1,13 @@
 <?php 
+
+/**
+ * @package sapphire
+ * @subpackage synchronisation
+ */
+
+/**
+ * Synchroniser controller - used to let two servers communicate
+ */
 class Synchronise extends Controller {
 	
 	public function update() {

synchronise/Synchronised.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage synchronisation
+ */
+
 /**
  * Functions to provide synchronisation between two Silverstripe implementations. This allows the same entry to have two different
  * IDs on each installation

tests/SapphireTest.php

@@ -1,4 +1,10 @@
 <?php
+
+/**
+ * @package sapphire
+ * @subpackage testing
+ */
+
 /*
 $dir = dirname(dirname((__FILE__)));
 $_SERVER['SCRIPT_FILENAME'] = "$dir/main.php";

tests/SiteTreeTest.php

@@ -1,5 +1,12 @@
 <?php
 
+/**
+ * @package tests
+ */
+
+/**
+ * Tests for SiteTree
+ */
 class SiteTreeTest extends SapphireTest {
 	static $fixture_file = 'sapphire/tests/SiteTreeTest.yml';
 	

tests/TestRunner.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage testing
+ */
+
 // Check that PHPUnit is installed
 $hasPhpUnit = false;
 $paths = explode(PATH_SEPARATOR, ini_get('include_path'));

tools/importer.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage misc
+ */
+
 /**
  ** Contains heaps of tools that you can use when importing database information
  **/

widgets/Widget.php

@@ -1,5 +1,14 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage widgets
+ */
+
+/**
+ * Base class for widgets.
+ * Widgets let CMS authors drag and drop small pieces of functionality into defined areas of their websites.
+ */
 class Widget extends DataObject {
 	static $db = array(
 		"ParentID" => "Int",

widgets/WidgetArea.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * @package sapphire
+ * @subpackage synchronisation
+ */
+
+/**
+ * Represents a set of widgets shown on a page.
+ */
 class WidgetArea extends DataObject {
 	static $db = array();