Merge branch 'pulls/apidocs-package-list' of https://github.com/madma…

…tt/silverstripe-framework into madmatt-pulls/apidocs-package-list Conflicts: view/SSTemplateParser.php view/SSTemplateParser.php.inc
mertenhanisch · Jan 31, 2014 · ab07094 · ab07094
2 parents 91b363b + bebe0f6
commit ab07094
Show file tree

Hide file tree

Showing 43 changed files with 193 additions and 52 deletions.
diff --git a/control/RequestFilter.php b/control/RequestFilter.php
@@ -7,6 +7,8 @@
  *
  * @author [email protected]
  * @license BSD License http://silverstripe.org/bsd-license/
+ * @package framework
+ * @subpackage control
  */
 interface RequestFilter {
 	/**

diff --git a/core/DAG.php b/core/DAG.php
@@ -3,6 +3,9 @@
 /**
  * A Directed Acyclic Graph - used for doing topological sorts on dependencies, such as the before/after conditions
  * in config yaml fragments
+ *
+ * @package framework
+ * @subpackage manifest
  */
 class SS_DAG implements IteratorAggregate {
 	/**
@@ -88,17 +91,31 @@ public function getIterator() {
 	}
 }
 
+/**
+ * Exception thrown when the {@link SS_DAG} class is unable to resolve sorting the DAG due to cyclic dependencies.
+ *
+ * @package framework
+ * @subpackage manifest
+ */
 class SS_DAG_CyclicException extends Exception {
 
 	public $dag;
 
+	/**
+	 * @param string $message The Exception message
+	 * @param SS_DAG $dag The remainder of the Directed Acyclic Graph (DAG) after the last successful sort
+	 */
 	public function __construct($message, $dag) {
 		$this->dag = $dag;
 		parent::__construct($message);
 	}
 
 }
 
+/**
+ * @package framework
+ * @subpackage manifest
+ */
 class SS_DAG_Iterator implements Iterator {
 
 	protected $data;

diff --git a/core/TempPath.php b/core/TempPath.php
@@ -2,6 +2,9 @@
 /**
  * Returns the temporary folder path that silverstripe should use for its cache files.
  *
+ * @package framework
+ * @subpackage core
+ *
  * @param $base The base path to use for determining the temporary path
  * @return string Path to temp
  */
@@ -20,6 +23,9 @@ function getTempFolder($base = null) {
 
 /**
  * Returns as best a representation of the current username as we can glean.
+ *
+ * @package framework
+ * @subpackage core
  */
 function getTempFolderUsername() {
 	$user = getenv('APACHE_RUN_USER');
@@ -38,6 +44,9 @@ function getTempFolderUsername() {
  * Return the parent folder of the temp folder.
  * The temp folder will be a subfolder of this, named by username.
  * This structure prevents permission problems.
+ *
+ * @package framework
+ * @subpackage core
  */
 function getTempParentFolder($base = null) {
 	if(!$base && defined('BASE_PATH')) $base = BASE_PATH;

diff --git a/core/manifest/ConfigStaticManifest.php b/core/manifest/ConfigStaticManifest.php
@@ -9,6 +9,7 @@
  * optionally catch attempts to modify the config statics (otherwise the modification will appear
  * to work, but won't actually have any effect - the equvilent of failing silently)
  *
+ * @package framework
  * @subpackage manifest
  */
 class SS_ConfigStaticManifest {
@@ -150,6 +151,9 @@ public function getStatics() {
  * We can't do this using TokenisedRegularExpression because we need to keep track of state
  * as we process the token list (when we enter and leave a namespace or class, when we see
  * an access level keyword, etc)
+ *
+ * @package framework
+ * @subpackage manifest
  */
 class SS_ConfigStaticManifest_Parser {
 

diff --git a/core/manifest/ManifestCache.php b/core/manifest/ManifestCache.php
@@ -2,6 +2,9 @@
 
 /**
  * A basic caching interface that manifests use to store data.
+ *
+ * @package framework
+ * @subpackage manifest
  */
 interface ManifestCache {
 	public function __construct($name);
@@ -12,6 +15,9 @@ public function clear();
 
 /**
  * Stores manifest data in files in TEMP_DIR dir on filesystem
+ *
+ * @package framework
+ * @subpackage manifest
  */
 class ManifestCache_File implements ManifestCache {
 	function __construct($name) {
@@ -37,6 +43,9 @@ function clear() {
 /**
  * Same as ManifestCache_File, but stores the data as valid PHP which gets included to load
  * This is a bit faster if you have an opcode cache installed, but slower otherwise
+ *
+ * @package framework
+ * @subpackage manifest
  */
 class ManifestCache_File_PHP extends ManifestCache_File {
 	function load($key) {
@@ -58,6 +67,9 @@ function save($data, $key) {
 /**
  * Stores manifest data in APC.
  * Note: benchmarks seem to indicate this is not particularly faster than _File
+ *
+ * @package framework
+ * @subpackage manifest
  */
 class ManifestCache_APC implements ManifestCache {
 	protected $pre;

diff --git a/dev/SilverStripeListener.php b/dev/SilverStripeListener.php
@@ -1,8 +1,12 @@
 <?php
-
-// Inject SilverStripe 'setUpOnce' and 'tearDownOnce' unittest extension methods into phpunit
-// This is already in later SilverStripe 2.4 versions, but having it here extends compatibility to older versions
-
+/**
+ * Inject SilverStripe 'setUpOnce' and 'tearDownOnce' unittest extension methods into PHPUnit.
+ *
+ * This is already in later SilverStripe 2.4 versions, but having it here extends compatibility to older versions.
+ *
+ * @package framework
+ * @subpackage testing
+ */
 class SilverStripeListener implements PHPUnit_Framework_TestListener {
 
 	protected function isValidClass($name) {

diff --git a/dev/TeamCityListener.php b/dev/TeamCityListener.php
@@ -1,7 +1,10 @@
 <?php
-
-// Bind TeamCity test listener. Echos messages to stdout that TeamCity interprets into the test results
-
+/**
+ * Bind TeamCity test listener. Echos messages to stdout that TeamCity interprets into the test results
+ *
+ * @package framework
+ * @subpackage testing
+ */
 class TeamCityListener implements PHPUnit_Framework_TestListener {
 
 	private function escape($str) {

diff --git a/email/Mailer.php b/email/Mailer.php
@@ -437,6 +437,8 @@ function wrapImagesInline_rewriter($url) {
 }
 
 /**
+ * @package framework
+ * @subpackage email
  * @deprecated 3.1
  */
 function htmlEmail($to, $from, $subject, $htmlContent, $attachedFiles = false, $customheaders = false,
@@ -449,6 +451,8 @@ function htmlEmail($to, $from, $subject, $htmlContent, $attachedFiles = false, $
 }
 
 /**
+ * @package framework
+ * @subpackage email
  * @deprecated 3.1
  */
 function plaintextEmail($to, $from, $subject, $plainContent, $attachedFiles, $customheaders = false) {
@@ -459,6 +463,8 @@ function plaintextEmail($to, $from, $subject, $plainContent, $attachedFiles, $cu
 }
 
 /**
+ * @package framework
+ * @subpackage email
  * @deprecated 3.1
  */
 function encodeMultipart($parts, $contentType, $headers = false) {
@@ -469,6 +475,8 @@ function encodeMultipart($parts, $contentType, $headers = false) {
 }
 
 /**
+ * @package framework
+ * @subpackage email
  * @deprecated 3.1
  */
 function wrapImagesInline($htmlContent) {
@@ -479,6 +487,8 @@ function wrapImagesInline($htmlContent) {
 }
 
 /**
+ * @package framework
+ * @subpackage email
  * @deprecated 3.1
  */
 function wrapImagesInline_rewriter($url) {
@@ -490,6 +500,8 @@ function wrapImagesInline_rewriter($url) {
 }
 
 /**
+ * @package framework
+ * @subpackage email
  * @deprecated 3.1
  */
 function processHeaders($headers, $body = false) {
@@ -500,6 +512,8 @@ function processHeaders($headers, $body = false) {
 }
 
 /**
+ * @package framework
+ * @subpackage email
  * @deprecated 3.1
  */
 function encodeFileForEmail($file, $destFileName = false, $disposition = NULL, $extraHeaders = "") {
@@ -510,6 +524,8 @@ function encodeFileForEmail($file, $destFileName = false, $disposition = NULL, $
 }
 
 /**
+ * @package framework
+ * @subpackage email
  * @deprecated 3.1
  */
 function QuotedPrintable_encode($quotprint) {
@@ -520,6 +536,8 @@ function QuotedPrintable_encode($quotprint) {
 }
 
 /**
+ * @package framework
+ * @subpackage email
  * @deprecated 3.1
  */
 function validEmailAddr($emailAddress) {

diff --git a/filesystem/GD.php b/filesystem/GD.php
@@ -486,7 +486,10 @@ public function writeTo($filename) {
 }
 
 /**
- * Backwards compatibility
+ * This class is maintained for backwards-compatibility only. Please use the {@link GDBackend} class instead.
+ *
+ * @package framework
+ * @subpackage filesystem
  */
 class GD extends GDBackend {
 

diff --git a/forms/HtmlEditorField.php b/forms/HtmlEditorField.php
@@ -759,6 +759,8 @@ protected function getAllowedExtensions() {
  * such as file name or the URL.
  *
  * @todo Remove once core has support for remote files
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class HtmlEditorField_File extends ViewableData {
 
@@ -827,6 +829,13 @@ public function appCategory() {
 
 }
 
+/**
+ * Encapsulation of an oembed tag, linking to an external media source.
+ *
+ * @see Oembed
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class HtmlEditorField_Embed extends HtmlEditorField_File {
 	protected $oembed;
 
@@ -910,6 +919,12 @@ public function getInfo() {
 	}
 }
 
+/**
+ * Encapsulation of an image tag, linking to an image either internal or external to the site.
+ *
+ * @package forms
+ * @subpackage fields-formattedinput
+ */
 class HtmlEditorField_Image extends HtmlEditorField_File {
 
 	protected $width;

diff --git a/forms/HtmlEditorSanitiser.php b/forms/HtmlEditorSanitiser.php
@@ -7,7 +7,8 @@
  * See www.tinymce.com/wiki.php/configuration:valid_elements for details on the spec of TinyMCE's
  * whitelist configuration
  *
- * Class HtmlEditorSanitiser
+ * @package forms
+ * @subpackage fields-formattedinput
  */
 class HtmlEditorSanitiser {
 

diff --git a/forms/MoneyField.php b/forms/MoneyField.php
@@ -6,7 +6,7 @@
  * 
  * @author Ingo Schommer, SilverStripe Ltd. (<firstname>@silverstripe.com)
  * 
- * @package framework
+ * @package forms
  * @subpackage fields-formattedinput
  */
 class MoneyField extends FormField {

diff --git a/forms/UploadField.php b/forms/UploadField.php
@@ -22,8 +22,8 @@
  * </code>
  * 
  * @author Zauberfisch
- * @package framework
- * @subpackage forms
+ * @package forms
+ * @subpackages fields-files
  */
 class UploadField extends FileField {
 
@@ -1325,8 +1325,8 @@ public function getRelationAutosetClass($default = 'File') {
  * RequestHandler for actions (edit, remove, delete) on a single item (File) of the UploadField
  * 
  * @author Zauberfisch
- * @package framework
- * @subpackage forms
+ * @package forms
+ * @subpackages fields-files
  */
 class UploadField_ItemHandler extends RequestHandler {
 
@@ -1486,6 +1486,9 @@ public function doEdit(array $data, Form $form, SS_HTTPRequest $request) {
 
 /**
  * File selection popup for attaching existing files.
+ *
+ * @package forms
+ * @subpackages fields-files
  */
 class UploadField_SelectHandler extends RequestHandler {
 

diff --git a/forms/gridfield/GridField.php b/forms/gridfield/GridField.php
@@ -15,7 +15,7 @@
  * 
  * @see SS_List
  * 
- * @package framework
+ * @package forms
  * @subpackage fields-gridfield
  */
 class GridField extends FormField {
@@ -764,7 +764,7 @@ public function saveInto(DataObjectInterface $record) {
  * This class is the base class when you want to have an action that alters 
  * the state of the {@link GridField}, rendered as a button element. 
  * 
- * @package framework
+ * @package forms
  * @subpackage fields-gridfield
  */
 class GridField_FormAction extends FormAction {

diff --git a/forms/gridfield/GridFieldAddExistingAutocompleter.php b/forms/gridfield/GridFieldAddExistingAutocompleter.php
@@ -15,7 +15,7 @@
  * For easier setup, have a look at a sample configuration in 
  * {@link GridFieldConfig_RelationEditor}.
  *
- * @package framework
+ * @package forms
  * @subpackage fields-gridfield
  */
 class GridFieldAddExistingAutocompleter 

diff --git a/forms/gridfield/GridFieldAddNewButton.php b/forms/gridfield/GridFieldAddNewButton.php
@@ -6,7 +6,7 @@
  * Only returns a button if {@link DataObject->canCreate()} for this record 
  * returns true.
  *
- * @package framework
+ * @package forms
  * @subpackage fields-gridfield
  */
 class GridFieldAddNewButton implements GridField_HTMLProvider {

diff --git a/forms/gridfield/GridFieldButtonRow.php b/forms/gridfield/GridFieldButtonRow.php
@@ -8,7 +8,7 @@
  * This row provides two new HTML fragment spaces: 'toolbar-header-left' and 
  * 'toolbar-header-right'.
  *
- * @package framework
+ * @package forms
  * @subpackage fields-gridfield
  */
 class GridFieldButtonRow implements GridField_HTMLProvider {