Improved API documentation

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

_config.php

@@ -1,6 +1,7 @@
 <?php
 /**
  * URL rules for the CMS module
+ * @package cms
  */
 Director::addRules(50, array(
 	'processes/$Action/$ID/$Batch' => 'BatchProcess_Controller',

code/AssetAdmin.php

@@ -2,12 +2,14 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage assets
  */
 
 /**
  * AssetAdmin is the 'file store' section of the CMS.
  * It provides an interface for maniupating the File and Folder objects in the system.
+ * @package cms
+ * @subpackage assets
  */
 class AssetAdmin extends LeftAndMain {
 	static $tree_class = "File";

code/AssetTableField.php

@@ -1,11 +1,13 @@
 <?php
 /**
  * @package cms
- * @subpackage
+ * @subpackage assets
  */
 
 /**
  * A special kind of complex table field for manipulating assets.
+ * @package cms
+ * @subpackage assets
  */
 class AssetTableField extends ComplexTableField {
 	

code/BulkLoader.php

@@ -2,12 +2,14 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage bulkloading
  */
 
 /**
  * An abstract base for bulk loaders of content into the SilverStripe database.
  * Bulk loaders give SilverStripe authors the ability to do large-scale CSV uploads into their Sapphire databases.
+ * @package cms
+ * @subpackage bulkloading
  */
 abstract class BulkLoader extends ViewableData {
 	/**

code/BulkLoaderAdmin.php

@@ -2,7 +2,7 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage bulkloading
  */
 
 /**
@@ -11,6 +11,8 @@
  * each of which defines a particular bulk loading operation.
  * 
  * This code was originally developed for Per Week in collaboration with Brian Calhoun.
+ * @package cms
+ * @subpackage bulkloading
  */
 class BulkLoaderAdmin extends LeftAndMain {
 

code/CMSActionOptionsForm.php

@@ -2,12 +2,14 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage core
  */
 
 /**
  * A special kind of form used to make the action dialogs that appear just underneath the top-right
  * buttons in the CMS
+ * @package cms
+ * @subpackage core
  */
 class CMSActionOptionsForm extends Form {
 	function FormAttributes() {

code/CMSMain.php

@@ -1,13 +1,15 @@
 <?php
 /**
  * @package cms
- * @subpackage
+ * @subpackage content
  */
 
 /**
  * The main "content" area of the CMS.
  * This class creates a 2-frame layout - left-tree and right-form - to sit beneath the main
  * admin menu.
+ * @package cms
+ * @subpackage content
  * @todo Create some base classes to contain the generic functionality that will be replicated.
  */
 class CMSMain extends LeftAndMain implements CurrentPageIdentifier, PermissionProvider {

code/CommentAdmin.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage comments
  */
 
 /**
  * Comment administration system within the CMS
+ * @package cms
+ * @subpackage comments
  */
 class CommentAdmin extends LeftAndMain {
 	

code/CommentTableField.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage comments
  */
 
 /**
  * Special kind of ComplexTableField for managing comments.
+ * @package cms
+ * @subpackage comments
  */
 class CommentTableField extends ComplexTableField {
 	protected $template = "CommentTableField";
@@ -157,7 +159,11 @@ class CommentTableField extends ComplexTableField {
 	}
 }
 
-
+/**
+ * Single row of a {@link CommentTableField}
+ * @package cms
+ * @subpackage comments
+ */
 class CommentTableField_Item extends ComplexTableField_Item {
 	function HasSpamButton() {
 		return $this->parent()->HasSpamButton();

code/Diff.php

@@ -2,7 +2,7 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage core
  * A PHP diff engine
  */
 
@@ -17,8 +17,15 @@
 // FIXME: possibly remove assert()'s for production version?
 
 // PHP3 does not have assert()
+/**
+ */
 define('USE_ASSERTS', function_exists('assert'));
 
+/**
+ * @package cms
+ * @subpackage core
+ * @access private
+ */
 class _DiffOp {
     var $type;
     var $orig;
@@ -37,6 +44,11 @@ class _DiffOp {
     }
 }
 
+/**
+ * @package cms
+ * @subpackage core
+ * @access private
+ */
 class _DiffOp_Copy extends _DiffOp {
     var $type = 'copy';
 
@@ -52,6 +64,11 @@ class _DiffOp_Copy extends _DiffOp {
     }
 }
 
+/**
+ * @package cms
+ * @subpackage core
+ * @access private
+ */
 class _DiffOp_Delete extends _DiffOp {
     var $type = 'delete';
 
@@ -65,6 +82,11 @@ class _DiffOp_Delete extends _DiffOp {
     }
 }
 
+/**
+ * @package cms
+ * @subpackage core
+ * @access private
+ */
 class _DiffOp_Add extends _DiffOp {
     var $type = 'add';
 
@@ -78,6 +100,11 @@ class _DiffOp_Add extends _DiffOp {
     }
 }
 
+/**
+ * @package cms
+ * @subpackage core
+ * @access private
+ */
 class _DiffOp_Change extends _DiffOp {
     var $type = 'change';
 
@@ -111,6 +138,8 @@ class _DiffOp_Change extends _DiffOp {
  *
  * @author Geoffrey T. Dairiki
  * @access private
+ * @package cms
+ * @subpackage core
  */
 class _DiffEngine
 {
@@ -495,6 +524,8 @@ class _DiffEngine
 
 /**
  * Class representing a 'diff' between two sequences of strings.
+ * @package cms
+ * @subpackage core
  */
 class Diff
 {
@@ -743,7 +774,9 @@ class Diff
 
 
 /**
- * FIXME: bad name.
+ * Computes diff between sequences of strings.
+ * @package cms
+ * @subpackage core
  */
 class MappedDiff
 extends Diff

code/FileList.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage assets
  */
 
 /**
  * A FormField showing a list of files
+ * @package cms
+ * @subpackage assets
  */
 class FileList extends TableListField {
 	// bdc: added sort by Title as default behaviour

code/GenericDataAdmin.php

@@ -2,16 +2,15 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage core
  */
 
 /**
  * Provides a common interface for searching, viewing and editing DataObjects.
  * Extend the class to adjust functionality to your specific DataObjects.
  * 
- * @var $data_type DataObject The base class
+ * @package cms
- * @var $data_type_extra Array Additional DataObjects which are included in the search.
+ * @subpackage core
- * @var $resultColumnts Array Columnnames shown in the result-table.
  */
 abstract class GenericDataAdmin extends LeftAndMain {
 

code/ImageEditor.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage assets
  */
 
 /**
  * This Controller handles all operation needed for ImageEditor to work(expect for GD operations).
+ * @package cms
+ * @subpackage assets
  */
 class ImageEditor extends Controller {
 	

code/ImprintStats.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage livesite
  */
 
 /**
  * Module to provide imprint statistics integration.
+ * @package cms
+ * @subpackage livesite
  */
 class ImprintStats extends ViewableData {
 	protected static $imprintID;

code/LeftAndMain.php

@@ -2,12 +2,14 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage core
  */
 
 /**
  * LeftAndMain is the parent class of all the two-pane views in the CMS.
  * If you are wanting to add more areas to the CMS, you can do it by subclassing LeftAndMain.
+ * @package cms
+ * @subpackage core
  */
 abstract class LeftAndMain extends Controller {
 	static $tree_class = null;

code/MemberList.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage security
  */
 
 /**
  * Form field showing a list of members.
+ * @package cms
+ * @subpackage security
  */
 class MemberList extends FormField {
 	protected $members;

code/MemberTableField.php

@@ -2,7 +2,7 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage security
  */
 
 /**
@@ -17,6 +17,8 @@
  * - members of a provided group
  * - all members
  * - members based on a search-query
+ * @package cms
+ * @subpackage security
  */
 class MemberTableField extends ComplexTableField {
 	
@@ -348,10 +350,11 @@ class MemberTableField extends ComplexTableField {
 	}
 }
 
-
+/**
-
+ * Popup window for {@link MemberTableField}.
-
+ * @package cms
-
+ * @subpackage security
+ */
 class MemberTableField_Popup extends ComplexTableField_Popup {
 	
 	function __construct($controller, $name, $fields, $sourceClass, $readonly=false, $validator = null) {

code/Newsletter/BatchProcess.php

@@ -7,6 +7,8 @@
 
 /**
  * Create a process in session which is incremented to calls from the client
+ * @package cms
+ * @subpackage newsletter
  */
 class BatchProcess extends Object {
 	
@@ -74,6 +76,11 @@ class BatchProcess extends Object {
 	}
 }
 
+/**
+ * Controller for calling the batch processes via Ajax.
+ * @package cms
+ * @subpackage newsletter
+ */
 class BatchProcess_Controller extends Controller {
 	
 	function next() {

code/Newsletter/BouncedList.php

@@ -7,6 +7,8 @@
 
 /**
  * Form field showing a list of bounced addresses
+ * @package cms
+ * @subpackage newsletter
  */
 class BouncedList extends FormField {
     

code/Newsletter/Newsletter.php

@@ -7,6 +7,8 @@
 
 /**
  * Single newsletter instance.  Each Newsletter belongs to a NewsletterType.
+ * @package cms
+ * @subpackage newsletter
  */
 class Newsletter extends DataObject {
 	
@@ -126,6 +128,11 @@ class Newsletter extends DataObject {
   }
 }
 
+/**
+ * Database record for recipients that have had the newsletter sent to them.
+ * @package cms
+ * @subpackage newsletter
+ */ 
 class Newsletter_SentRecipient extends DataObject {
 	/**
 	 * The DB schema for Newsletter_SentRecipient.
@@ -144,6 +151,12 @@ class Newsletter_SentRecipient extends DataObject {
 		"Member" => "Member",
 	);
 }
+
+/**
+ * Single recipient of the newsletter
+ * @package cms
+ * @subpackage newsletter
+ */
 class Newsletter_Recipient extends DataObject {
 	static $db = array(
 		"ParentID" => "Int",
@@ -153,6 +166,11 @@ class Newsletter_Recipient extends DataObject {
 	);
 }
 
+/**
+ * Email object for sending newsletters.
+ * @package cms
+ * @subpackage newsletter
+ */
 class Newsletter_Email extends Email_Template {
 	protected $nlType;
 	

code/Newsletter/NewsletterEmailProcess.php

@@ -7,6 +7,8 @@
 
 /**
  * Batch process for sending newsletters.
+ * @package cms
+ * @subpackage newsletter
  */
 class NewsletterEmailProcess extends BatchProcess {
 	
@@ -20,7 +22,7 @@ class NewsletterEmailProcess extends BatchProcess {
 	/** 
 	 * Set up a Newsletter Email Process
 	 *
-	 * @recipients A DataObject containing the addresses of the recipients of this newsletter
+	 * @param $recipients DataObjectSet The recipients of this newsletter
 	 */
 	function __construct( $subject, $body, $from, $newsletter, $nlType, $messageID = null, $recipients) {
 		

code/Newsletter/NewsletterList.php

@@ -7,6 +7,8 @@
 
 /**
  * Simple form field shown when the NewsletterAdmin first loads.
+ * @package cms
+ * @subpackage newsletter
  */
 class NewsletterList extends FormField {
 	function __construct($name, $mailtype, $status = "Draft") {
@@ -50,4 +52,4 @@ class NewsletterList extends FormField {
 	}
 }
 
-?>
+?>

code/Newsletter/NewsletterType.php

@@ -8,6 +8,8 @@
 /**
  * Represents a type of newsletter, for example the weekly products update.
  * The NewsletterType is associated with a recipient list and a bunch of Newsletter objects, which are each either Sent or Draft.
+ * @package cms
+ * @subpackage newsletter
  */
 class NewsletterType extends DataObject {
 

code/Newsletter/RecipientImportField.php

@@ -7,6 +7,8 @@
 
 /**
  * Displays a field for importing recipients. 
+ * @package cms
+ * @subpackage newsletter
  */
 class RecipientImportField extends FormField {
 	
@@ -180,6 +182,11 @@ class RecipientImportField extends FormField {
 	}
 }
 
+/**
+ * Single cell of the recipient import field
+ * @package cms
+ * @subpackage newsletter
+ */
 class RecipientImportField_Cell extends ViewableData {
 	protected $value;
 	
@@ -192,6 +199,11 @@ class RecipientImportField_Cell extends ViewableData {
 	}
 }
 
+/**
+ * Upload form that appears in the iframe
+ * @package cms
+ * @subpackage newsletter
+ */
 class RecipientImportField_UploadForm extends Form {
 	function import( $data, $form ) {
 		$id = $data['ID'];

code/Newsletter/SubscribeForm.php

@@ -7,6 +7,8 @@
 
 /**
  * Page type for creating a page that contains a form that visitors can use to subscript to a newsletter.
+ * @package cms
+ * @subpackage newsletter
  */
 class SubscribeForm extends UserDefinedForm {
 	static $add_action = "a newsletter subscription form";
@@ -157,6 +159,11 @@ class SubscribeForm extends UserDefinedForm {
     }
 }
 
+/**
+ * Email for sending subscribe form submissions.
+ * @package cms
+ * @subpackage newsletter
+ */
 class SubscribeForm_SubscribeEmail extends Email_Template {
     protected $to = '$Email';
     protected $subject = '$Subject';
@@ -164,6 +171,11 @@ class SubscribeForm_SubscribeEmail extends Email_Template {
     protected $from = '';   
 }
 
+/**
+ * Controller for the SubscribeForm page
+ * @package cms
+ * @subpackage newsletter
+ */
 class SubscribeForm_Controller extends UserDefinedForm_Controller {
  
     function process( $data, $form ) {

code/Newsletter/TemplateList.php

@@ -7,6 +7,8 @@
 
 /**
  * Subclass of DropdownField for showing a list of the newsletter templates available.
+ * @package cms
+ * @subpackage newsletter
  */
 class TemplateList extends DropdownField {
 	

code/Newsletter/Unsubscribe.php

@@ -7,6 +7,8 @@
 
 /**
  * Create a form that a user can use to unsubscribe from a mailing list
+ * @package cms
+ * @subpackage newsletter
  */
 class Unsubscribe_Controller extends Page_Controller {
     function __construct($data = null) {
@@ -112,6 +114,12 @@ class Unsubscribe_Controller extends Page_Controller {
     }
 }
 
+/**
+ * 2nd step form for the Unsubcribe page.
+ * The form will list all the mailing lists that the user is subscribed to.
+ * @package cms
+ * @subpackage newsletter
+ */
 class Unsubscribe_MailingListForm extends Form {
     
     protected $memberEmail;
@@ -151,6 +159,12 @@ class Unsubscribe_MailingListForm extends Form {
     }
 }
 
+/**
+ * 1st step form for the Unsubcribe page.
+ * The form will let people enter an email address and press a button to continue.
+ * @package cms
+ * @subpackage newsletter
+ */
 class Unsubscribe_EmailAddressForm extends Form {
 
     function __construct( $controller, $name ) {
@@ -171,6 +185,12 @@ class Unsubscribe_EmailAddressForm extends Form {
     }    
 }
 
+/**
+ * Final stage form for the Unsubcribe page.
+ * The form just gives you a success message.
+ * @package cms
+ * @subpackage newsletter
+ */
 class Unsubscribe_Successful extends Form {
 	function __construct($controller, $name){
 		$fields = new FieldSet();

code/Newsletter/UnsubscribedList.php

@@ -7,6 +7,8 @@
 
 /**
  * Displays a list of all members that have unsubscribed from the list
+ * @package cms
+ * @subpackage newsletter
  */
 class UnsubscribedList extends FormField {
     

code/NewsletterAdmin.php

@@ -7,6 +7,8 @@
 
 /**
  * Newsletter administration section
+ * @package cms
+ * @subpackage newsletter
  */
 class NewsletterAdmin extends LeftAndMain {
 	static $subitem_class = "Member";

code/PageTypes/UserDefinedForm.php

@@ -7,6 +7,8 @@
 
 /**
  * Page type that lets users build a contact form.
+ * @package cms
+ * @subpackage pagetypes
  */
 class UserDefinedForm extends Page {
 	static $add_action = "a contact form";
@@ -157,6 +159,11 @@ class UserDefinedForm extends Page {
 	}
 }
 
+/**
+ * Controller for the {@link UserDefinedForm} page type.
+ * @package cms
+ * @subpackage pagetypes
+ */
 class UserDefinedForm_Controller extends Page_Controller {
 	
 	function init() {
@@ -309,6 +316,11 @@ class UserDefinedForm_Controller extends Page_Controller {
 	}
 }
 
+/**
+ * Email that gets sent when a submission is made.
+ * @package cms
+ * @subpackage pagetypes
+ */
 class UserDefinedForm_SubmittedFormEmail extends Email_Template {
 	protected $ss_template = "SubmittedFormEmail";
 	protected $from = '$Sender.Email';

code/ReportAdmin.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage reports
  */
 
 /**
  * Reports section of the CMS
+ * @package cms
+ * @subpackage reports
  */
 class ReportAdmin extends LeftAndMain {
 	static $subitem_class = "GrantObject";

code/SecurityAdmin.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage security
  */
 
 /**
  * Security section of the CMS
+ * @package cms
+ * @subpackage security
  */
 class SecurityAdmin extends LeftAndMain implements PermissionProvider {
 	static $tree_class = "Group";

code/SideReport.php

@@ -2,12 +2,14 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage content
  */
 
 /**
  * Base class for the small reports that appear in the left hand site of the Site Content section of the CMS.
  * Create subclasses of this class to build new reports.
+ * @package cms
+ * @subpackage content
  */
 abstract class SideReport extends Object {
 	abstract function records();
@@ -45,6 +47,8 @@ abstract class SideReport extends Object {
 
 /**
  * Content side-report listing empty pages
+ * @package cms
+ * @subpackage content
  */
 class SideReport_EmptyPages extends SideReport {
 	function title() {
@@ -62,6 +66,8 @@ class SideReport_EmptyPages extends SideReport {
 
 /**
  * Content side-report listing recently editing pages.
+ * @package cms
+ * @subpackage content
  */
 class SideReport_RecentlyEdited extends SideReport {
 	function title() {

code/StaticExporter.php

@@ -2,13 +2,15 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage export
  */
 
 /**
  * This class lets you export a static copy of your site.
  * It creates a huge number of folders each containing an index.html file.
  * This preserves the URL naming format.
+ * @package cms
+ * @subpackage export
  */
 class StaticExporter extends Controller {
 	function init() {

code/StatisticsAdmin.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage reports
  */
 
 /**
  * Statistics section of the CMS
+ * @package cms
+ * @subpackage reports
  */
 class StatisticsAdmin extends LeftAndMain {
 	static $tree_class = "SiteTree";

code/ThumbnailStripField.php

@@ -2,13 +2,15 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage assets
  */
 
 /**
  * Provides a strip of thumbnails showing all of the images in the system.
  * It will be tied to a 'parent field' that will provide it with a filter by which to reduce the number
  * of thumbnails displayed.
+ * @package cms
+ * @subpackage assets
  */
 class ThumbnailStripField extends FormField {
 	protected $parentField;

code/WidgetAreaEditor.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage content
  */
 
 /**
  * Special field type for selecting and configuring widgets on a page.
+ * @package cms
+ * @subpackage content
  */
 class WidgetAreaEditor extends FormField {
 	function FieldHolder() {

code/sitefeatures/Akismet.php

@@ -16,7 +16,7 @@
  * See the Akismet class documentation page linked to below for usage information.
  *
  * @package cms
- * @subpackage
+ * @subpackage comments
  * @author Alex Potsides, {@link http://www.achingbrain.net http://www.achingbrain.net}
  * @version 0.1
  * @copyright Alex Potsides, {@link http://www.achingbrain.net http://www.achingbrain.net}
@@ -47,6 +47,8 @@
  *	@version	0.2
  *  @author		Alex Potsides
  *  @link		http://www.achingbrain.net/
+ * @package cms
+ * @subpackage comments
  */
 class Akismet
 	{
@@ -301,6 +303,8 @@ class Akismet
  *	@version	0.1
  *  @author		Alex Potsides
  *  @link		http://www.achingbrain.net/
+ * @package cms
+ * @subpackage comments
  */
 class SocketWriteRead
 	{

code/sitefeatures/MathSpamProtection.php

@@ -2,12 +2,14 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage comments
  */
 
 /**
  * Tools for adding an optional protection question to a form.
  * Remember to add MathSpamProtection::enabled(true); to _config.php for this question to be added to the comments form.
+ * @package cms
+ * @subpackage comments
  */
 class MathSpamProtection {
 

code/sitefeatures/PageComment.php

@@ -2,11 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage comments
  */
 
 /**
  * Represents a single comment on a page
+ * @package cms
+ * @subpackage comments
  */
 class PageComment extends DataObject {
 	static $db = array(

code/sitefeatures/PageCommentInterface.php

@@ -2,13 +2,15 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage comments
  */
 
 /**
  * Represents an interface for viewing and adding page comments
  * Create one, passing the page discussed to the constructor.  It can then be
  * inserted into a template.
+ * @package cms
+ * @subpackage comments
  */
 class PageCommentInterface extends ViewableData {
 	protected $controller, $methodName, $page;
@@ -85,6 +87,10 @@ class PageCommentInterface extends ViewableData {
 	
 }
 
+/**
+ * @package cms
+ * @subpackage comments
+ */
 class PageCommentInterface_Form extends Form {
 	function postcomment($data) {
 		// Spam filtering
@@ -144,6 +150,10 @@ class PageCommentInterface_Form extends Form {
 	}
 }
 
+/**
+ * @package cms
+ * @subpackage comments
+ */
 class PageCommentInterface_Controller extends ContentController {
 	function __construct() {
 		parent::__construct(null);

code/sitefeatures/SSAkismet.php

@@ -2,9 +2,13 @@
 
 /**
  * @package cms
- * @subpackage
+ * @subpackage comments
  */
 
+/**
+ * @package cms
+ * @subpackage comments
+ */
 class SSAkismet extends Akismet {
 	private static $apiKey;
 	private static $saveSpam = true;