From 8727f27f2a514e3d6d237eb4a199b7e855bd5f7a Mon Sep 17 00:00:00 2001
From: Nik Rolls <nik@rolls.cc>
Date: Wed, 29 Apr 2015 20:17:08 +1200
Subject: [PATCH] Documentation tidy for Requirements.php

Documentation-only changes, except where a couple of methods have been moved to live next to other related functions.
---
 view/Requirements.php | 734 ++++++++++++++++++++++++------------------
 1 file changed, 416 insertions(+), 318 deletions(-)

diff --git a/view/Requirements.php b/view/Requirements.php
index 932dbe9d6..c87d72cb5 100644
--- a/view/Requirements.php
+++ b/view/Requirements.php
@@ -1,8 +1,7 @@
 <?php
 
 /**
- * Requirements tracker, for javascript and css.
- * @todo Document the requirements tracker, and discuss it with the others.
+ * Requirements tracker for JavaScript and CSS.
  *
  * @package framework
  * @subpackage view
@@ -10,7 +9,7 @@
 class Requirements implements Flushable {
 
 	/**
-	 * Triggered early in the request when someone requests a flush.
+	 * Triggered early in the request when a flush is requested
 	 */
 	public static function flush() {
 		self::delete_all_combined_files();
@@ -18,7 +17,8 @@ class Requirements implements Flushable {
 
 	/**
 	 * Enable combining of css/javascript files.
-	 * @param boolean $enable
+	 * 
+	 * @param bool $enable
 	 */
 	public static function set_combined_files_enabled($enable) {
 		self::backend()->set_combined_files_enabled($enable);
@@ -26,14 +26,16 @@ class Requirements implements Flushable {
 
 	/**
 	 * Checks whether combining of css/javascript files is enabled.
-	 * @return boolean
+	 * 
+	 * @return bool
 	 */
 	public static function get_combined_files_enabled() {
 		return self::backend()->get_combined_files_enabled();
 	}
 
 	/**
-	 * Set the relative folder e.g. "assets" for where to store combined files
+	 * Set the relative folder e.g. 'assets' for where to store combined files
+	 * 
 	 * @param string $folder Path to folder
 	 */
 	public static function set_combined_files_folder($folder) {
@@ -41,8 +43,10 @@ class Requirements implements Flushable {
 	}
 
 	/**
-	 * Set whether we want to suffix requirements with the time /
-	 * location on to the requirements
+	 * Set whether to add caching query params to the requests for file-based requirements. 
+	 * Eg: themes/myTheme/js/main.js?m=123456789. The parameter is a timestamp generated by
+	 * filemtime. This has the benefit of allowing the browser to cache the URL infinitely,
+	 * while automatically busting this cache every time the file is changed.
 	 *
 	 * @param bool
 	 */
@@ -51,7 +55,7 @@ class Requirements implements Flushable {
 	}
 
 	/**
-	 * Return whether we want to suffix requirements
+	 * Check whether we want to suffix requirements
 	 *
 	 * @return bool
 	 */
@@ -60,9 +64,10 @@ class Requirements implements Flushable {
 	}
 
 	/**
-	 * Instance of requirements for storage
+	 * Instance of the requirements for storage. You can create your own backend to change the 
+	 * default JS and CSS inclusion behaviour. 
 	 *
-	 * @var Requirements
+	 * @var Requirements_Backend
 	 */
 	private static $backend = null;
 
@@ -76,74 +81,78 @@ class Requirements implements Flushable {
 	/**
 	 * Setter method for changing the Requirements backend
 	 *
-	 * @param Requirements $backend
+	 * @param Requirements_Backend $backend
 	 */
 	public static function set_backend(Requirements_Backend $backend) {
 		self::$backend = $backend;
 	}
 
 	/**
-	 * Register the given javascript file as required.
-	 *
-	 * See {@link Requirements_Backend::javascript()} for more info
-	 *
+	 * Register the given JavaScript file as required.
+	 * 
+	 * @param string $file Relative to docroot
 	 */
 	public static function javascript($file) {
 		self::backend()->javascript($file);
 	}
 
 	/**
-	 * Add the javascript code to the header of the page
+	 * Register the given JavaScript code into the list of requirements
 	 *
-	 * See {@link Requirements_Backend::customScript()} for more info
-	 * @param script The script content
-	 * @param uniquenessID Use this to ensure that pieces of code only get added once.
+	 * @param string     $script       The script content as a string (without enclosing <script> tag)
+	 * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
 	 */
 	public static function customScript($script, $uniquenessID = null) {
 		self::backend()->customScript($script, $uniquenessID);
 	}
 
 	/**
-	 * Include custom CSS styling to the header of the page.
+	 * Return all registered custom scripts
 	 *
-	 * See {@link Requirements_Backend::customCSS()}
+	 * @return array
+	 */
+	public static function get_custom_scripts() {
+		return self::backend()->get_custom_scripts();
+	}
+
+	/**
+	 * Register the given CSS styles into the list of requirements 
 	 *
-	 * @param string $script CSS selectors as a string (without <style> tag enclosing selectors).
-	 * @param int $uniquenessID Group CSS by a unique ID as to avoid duplicate custom CSS in header
+	 * @param string     $script       CSS selectors as a string (without enclosing <style> tag)
+	 * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
 	 */
 	public static function customCSS($script, $uniquenessID = null) {
 		self::backend()->customCSS($script, $uniquenessID);
 	}
 
 	/**
-	 * Add the following custom code to the <head> section of the page.
-	 * See {@link Requirements_Backend::insertHeadTags()}
+	 * Add the following custom HTML code to the <head> section of the page
 	 *
-	 * @param string $html
-	 * @param string $uniquenessID
+	 * @param string     $html         Custom HTML code
+	 * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
 	 */
 	public static function insertHeadTags($html, $uniquenessID = null) {
 		self::backend()->insertHeadTags($html, $uniquenessID);
 	}
 
 	/**
-	 * Load the given javascript template with the page.
-	 * See {@link Requirements_Backend::javascriptTemplate()}
+	 * Include the content of the given JavaScript file in the list of requirements. Dollar-sign
+	 * variables will be interpolated with values from $vars similar to a .ss template.
 	 *
-	 * @param file The template file to load.
-	 * @param vars The array of variables to load.  These variables are loaded via string search & replace.
+	 * @param string         $file         The template file to load, relative to docroot
+	 * @param string[]|int[] $vars         The array of variables to interpolate.
+	 * @param string|int     $uniquenessID A unique ID that ensures a piece of code is only added once
 	 */
 	public static function javascriptTemplate($file, $vars, $uniquenessID = null) {
 		self::backend()->javascriptTemplate($file, $vars, $uniquenessID);
 	}
 
 	/**
-	 * Register the given stylesheet file as required.
-	 * See {@link Requirements_Backend::css()}
+	 * Register the given stylesheet into the list of requirements.
 	 *
-	 * @param $file String Filenames should be relative to the base, eg, 'framework/javascript/tree/tree.css'
-	 * @param $media String Comma-separated list of media-types (e.g. "screen,projector")
-	 * @see http://www.w3.org/TR/REC-CSS2/media.html
+	 * @param string $file  The CSS file to load, relative to site root
+	 * @param string $media Comma-separated list of media types to use in the link tag 
+	 *                      (e.g. 'screen,projector')
 	 */
 	public static function css($file, $media = null) {
 		self::backend()->css($file, $media);
@@ -152,116 +161,166 @@ class Requirements implements Flushable {
 	/**
 	 * Registers the given themeable stylesheet as required.
 	 *
-	 * A CSS file in the current theme path name "themename/css/$name.css" is
-	 * first searched for, and it that doesn't exist and the module parameter is
-	 * set then a CSS file with that name in the module is used.
+	 * A CSS file in the current theme path name 'themename/css/$name.css' is first searched for,
+	 * and it that doesn't exist and the module parameter is set then a CSS file with that name in 
+	 * the module is used.
 	 *
-	 * NOTE: This API is experimental and may change in the future.
-	 *
-	 * @param string $name The name of the file - e.g. "/css/File.css" would have
-	 *        the name "File".
-	 * @param string $module The module to fall back to if the css file does not
-	 *        exist in the current theme.
-	 * @param string $media The CSS media attribute.
+	 * @param string $name   The name of the file - eg '/css/File.css' would have the name 'File'
+	 * @param string $module The module to fall back to if the css file does not exist in the 
+	 *                       current theme.
+	 * @param string $media  Comma-separated list of media types to use in the link tag 
+	 *                       (e.g. 'screen,projector')
 	 */
 	public static function themedCSS($name, $module = null, $media = null) {
 		return self::backend()->themedCSS($name, $module, $media);
 	}
 
 	/**
-	 * Clear either a single or all requirements.
-	 * Caution: Clearing single rules works only with customCSS and customScript if you specified a {@uniquenessID}.
+	 * Clear either a single or all requirements
+	 * 
+	 * Caution: Clearing single rules added via customCSS and customScript only works if you 
+	 * originally specified a $uniquenessID.
 	 *
-	 * See {@link Requirements_Backend::clear()}
-	 *
-	 * @param $file String
+	 * @param string|int $fileOrID
 	 */
 	public static function clear($fileOrID = null) {
 		self::backend()->clear($fileOrID);
 	}
 
-	/**
-	 * Blocks inclusion of a specific file
-	 * See {@link Requirements_Backend::block()}
-	 *
-	 * @param unknown_type $fileOrID
-	 */
-	public static function block($fileOrID) {
-		self::backend()->block($fileOrID);
-	}
-
-	/**
-	 * Removes an item from the blocking-list.
-	 * See {@link Requirements_Backend::unblock()}
-	 *
-	 * @param string $fileOrID
-	 */
-	public static function unblock($fileOrID) {
-		self::backend()->unblock($fileOrID);
-	}
-
-	/**
-	 * Removes all items from the blocking-list.
-	 * See {@link Requirements_Backend::unblock_all()}
-	 */
-	public static function unblock_all() {
-		self::backend()->unblock_all();
-	}
-
 	/**
 	 * Restore requirements cleared by call to Requirements::clear
-	 * See {@link Requirements_Backend::restore()}
 	 */
 	public static function restore() {
 		self::backend()->restore();
 	}
 
 	/**
-	 * Update the given HTML content with the appropriate include tags for the registered
-	 * requirements.
-	 * See {@link Requirements_Backend::includeInHTML()} for more information.
+	 * Block inclusion of a specific file 
+	 * 
+	 * The difference between this and {@link clear} is that the calling order does not matter; 
+	 * {@link clear} must be called after the initial registration, whereas {@link block} can be
+	 * used in advance. This is useful, for example, to block scripts included by a superclass 
+	 * without having to override entire functions and duplicate a lot of code.
 	 *
-	 * @param string $templateFilePath Absolute path for the *.ss template file
-	 * @param string $content HTML content that has already been parsed from the $templateFilePath
-	 * through {@link SSViewer}.
-	 * @return string HTML content thats augumented with the requirements before the closing <head> tag.
+	 * Note that blocking should be used sparingly because it's hard to trace where an file is
+	 * being blocked from.
+	 *
+	 * @param string|int $fileOrID
+	 */
+	public static function block($fileOrID) {
+		self::backend()->block($fileOrID);
+	}
+	
+	/**
+	 * Remove an item from the block list
+	 *
+	 * @param string|int $fileOrID
+	 */
+	public static function unblock($fileOrID) {
+		self::backend()->unblock($fileOrID);
+	}
+
+	/**
+	 * Removes all items from the block list
+	 */
+	public static function unblock_all() {
+		self::backend()->unblock_all();
+	}
+
+	/**
+	 * Update the given HTML content with the appropriate include tags for the registered
+	 * requirements. Needs to receive a valid HTML/XHTML template in the $content parameter,
+	 * including a head and body tag.
+	 *
+	 * @param string $templateFile No longer used, only retained for compatibility
+	 * @param string $content      HTML content that has already been parsed from the $templateFile
+	 *                             through {@link SSViewer}
+	 * @return string HTML content augmented with the requirements tags
 	 */
 	public static function includeInHTML($templateFile, $content) {
 		return self::backend()->includeInHTML($templateFile, $content);
 	}
 
+	/**
+	 * Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the given 
+	 * HTTP Response
+	 * 
+	 * @param SS_HTTPResponse $response
+	 */
 	public static function include_in_response(SS_HTTPResponse $response) {
 		return self::backend()->include_in_response($response);
 	}
 
 	/**
-	 * Add i18n files from the given javascript directory.
+	 * Add i18n files from the given javascript directory. SilverStripe expects that the given 
+	 * directory will contain a number of JavaScript files named by language: en_US.js, de_DE.js, 
+	 * etc.
 	 *
-	 * @param String
-	 * @param Boolean
-	 * @param Boolean
-	 *
-	 * See {@link Requirements_Backend::add_i18n_javascript()} for more information.
+	 * @param string $langDir  The JavaScript lang directory, relative to the site root, e.g., 
+	 *                         'framework/javascript/lang'
+	 * @param bool   $return   Return all relative file paths rather than including them in 
+	 *                         requirements
+	 * @param bool   $langOnly Only include language files, not the base libraries
+	 * 
+	 * @return array
 	 */
 	public static function add_i18n_javascript($langDir, $return = false, $langOnly = false) {
 		return self::backend()->add_i18n_javascript($langDir, $return, $langOnly);
 	}
 
 	/**
-	 * Concatenate several css or javascript files into a single dynamically generated file.
-	 * See {@link Requirements_Backend::combine_files()} for more info.
+	 * Concatenate several css or javascript files into a single dynamically generated file. This
+	 * increases performance by fewer HTTP requests.
 	 *
-	 * @param string $combinedFileName
-	 * @param array $files
-	 * @param string $media
+	 * The combined file is regenerated based on every file modification time. Optionally a
+	 * rebuild can be triggered by appending ?flush=1 to the URL. If all files to be combined are
+	 * JavaScript, we use the external JSMin library to minify the JavaScript.
+	 *
+	 * All combined files will have a comment on the start of each concatenated file denoting their
+	 * original position. For easier debugging, we only minify JavaScript if not in development
+	 * mode ({@link Director::isDev()}).
+	 *
+	 * CAUTION: You're responsible for ensuring that the load order for combined files is
+	 * retained - otherwise combining JavaScript files can lead to functional errors in the
+	 * JavaScript logic, and combining CSS can lead to incorrect inheritance. You can also
+	 * only include each file once across all includes and comibinations in a single page load.
+	 *
+	 * CAUTION: Combining CSS Files discards any "media" information.
+	 *
+	 * Example for combined JavaScript:
+	 * <code>
+	 * Requirements::combine_files(
+	 *  'foobar.js',
+	 *  array(
+	 *        'mysite/javascript/foo.js',
+	 *        'mysite/javascript/bar.js',
+	 *    )
+	 * );
+	 * </code>
+	 *
+	 * Example for combined CSS:
+	 * <code>
+	 * Requirements::combine_files(
+	 *  'foobar.css',
+	 *    array(
+	 *        'mysite/javascript/foo.css',
+	 *        'mysite/javascript/bar.css',
+	 *    )
+	 * );
+	 * </code>
+	 *
+	 * @param string $combinedFileName Filename of the combined file relative to docroot
+	 * @param array  $files            Array of filenames relative to docroot
+	 *
+	 * @return bool|void
 	 */
-	public static function combine_files($combinedFileName, $files, $media = null) {
-		self::backend()->combine_files($combinedFileName, $files, $media);
+	public static function combine_files($combinedFileName, $files) {
+		self::backend()->combine_files($combinedFileName, $files);
 	}
 
 	/**
-	 * Returns all combined files.
-	 * See {@link Requirements_Backend::get_combine_files()}
+	 * Return all combined files; keys are the combined file names, values are lists of 
+	 * files being combined.
 	 *
 	 * @return array
 	 */
@@ -270,8 +329,7 @@ class Requirements implements Flushable {
 	}
 
 	/**
-	 * Deletes all dynamically generated combined files from the filesystem.
-	 * See {@link Requirements_Backend::delete_combine_files()}
+	 * Delete all dynamically generated combined files from the filesystem
 	 *
 	 * @param string $combinedFileName If left blank, all combined files are deleted.
 	 */
@@ -281,7 +339,7 @@ class Requirements implements Flushable {
 
 	/**
 	 * Deletes all generated combined files in the configured combined files directory,
-	 * but doesn't delete the directory itself.
+	 * but doesn't delete the directory itself
 	 */
 	public static function delete_all_combined_files() {
 		return self::backend()->delete_all_combined_files();
@@ -295,44 +353,36 @@ class Requirements implements Flushable {
 	}
 
 	/**
-	 * See {@link combine_files()}.
+	 * Do the heavy lifting involved in combining (and, in the case of JavaScript minifying) the
+	 * combined files. 
  	 */
 	public static function process_combined_files() {
 		return self::backend()->process_combined_files();
 	}
 
 	/**
-	 * Returns all custom scripts
-	 * See {@link Requirements_Backend::get_custom_scripts()}
+	 * Set whether you want to write the JS to the body of the page rather than at the end of the
+	 * head tag.
 	 *
-	 * @return array
-	 */
-	public static function get_custom_scripts() {
-		return self::backend()->get_custom_scripts();
-	}
-
-	/**
-	 * Set whether you want to write the JS to the body of the page or
-	 * in the head section
-	 *
-	 * @see Requirements_Backend::set_write_js_to_body()
-	 * @param boolean
+	 * @param bool
 	 */
 	public static function set_write_js_to_body($var) {
 		self::backend()->set_write_js_to_body($var);
 	}
 
 	/**
-	 * Set the javascript to be forced to end of the HTML, or use the default.
-	 * Useful if you use inline <script> tags, that don't need the javascripts
-	 * included via Requirements::require();
+	 * Set whether to force the JavaScript to end of the body. Useful if you use inline script tags
+	 * that don't rely on scripts included via {@link Requirements::javascript()).
 	 *
-	 * @param boolean $var If true, force the javascripts to be included at the bottom.
+	 * @param boolean $var If true, force the JavaScript to be included at the bottom of the page
 	 */
 	public static function set_force_js_to_bottom($var) {
 		self::backend()->set_force_js_to_bottom($var);
 	}
 
+	/**
+	 * Output debugging information
+	 */
 	public static function debug() {
 		return self::backend()->debug();
 	}
@@ -346,72 +396,70 @@ class Requirements implements Flushable {
 class Requirements_Backend {
 
 	/**
-	 * Do we want requirements to suffix onto the requirement link
-	 * tags for caching or is it disabled. Getter / Setter available
-	 * through {@link Requirements::set_suffix_requirements()}
-	 *
+	 * Whether to add caching query params to the requests for file-based requirements. 
+	 * Eg: themes/myTheme/js/main.js?m=123456789. The parameter is a timestamp generated by
+	 * filemtime. This has the benefit of allowing the browser to cache the URL infinitely,
+	 * while automatically busting this cache every time the file is changed.
+	 * 
 	 * @var bool
 	 */
 	protected $suffix_requirements = true;
 
 	/**
-	 * Enable combining of css/javascript files.
+	 * Whether to combine CSS and JavaScript files
 	 *
-	 * @var boolean
+	 * @var bool
 	 */
 	protected $combined_files_enabled = true;
 
 	/**
-	 * Paths to all required .js files relative to the webroot.
+	 * Paths to all required JavaScript files relative to docroot
 	 *
 	 * @var array $javascript
 	 */
 	protected $javascript = array();
 
 	/**
-	 * Paths to all required .css files relative to the webroot.
+	 * Paths to all required CSS files relative to the docroot.
 	 *
 	 * @var array $css
 	 */
 	protected $css = array();
 
 	/**
-	 * All custom javascript code that is inserted
-	 * directly at the bottom of the HTML <head> tag.
+	 * All custom javascript code that is inserted into the page's HTML
 	 *
 	 * @var array $customScript
 	 */
 	protected $customScript = array();
 
 	/**
-	 * All custom CSS rules which are inserted
-	 * directly at the bottom of the HTML <head> tag.
+	 * All custom CSS rules which are inserted directly at the bottom of the HTML <head> tag
 	 *
 	 * @var array $customCSS
 	 */
 	protected $customCSS = array();
 
 	/**
-	 * All custom HTML markup which is added before
-	 * the closing <head> tag, e.g. additional metatags.
-	 * This is preferred to entering tags directly into
+	 * All custom HTML markup which is added before the closing <head> tag, e.g. additional 
+	 * metatags.
 	 */
 	protected $customHeadTags = array();
 
 	/**
-	 * Remembers the filepaths of all cleared Requirements
-	 * through {@link clear()}.
+	 * Remembers the file paths or uniquenessIDs of all Requirements cleared through 
+	 * {@link clear()}, so that they can be restored later.
 	 *
 	 * @var array $disabled
 	 */
 	protected $disabled = array();
 
 	/**
-	 * The filepaths (relative to webroot) or
-	 * uniquenessIDs of any included requirements
-	 * which should be blocked when executing {@link inlcudeInHTML()}.
-	 * This is useful to e.g. prevent core classes to modifying
-	 * Requirements without subclassing the entire functionality.
+	 * The file paths (relative to docroot) or uniquenessIDs of any included requirements which
+	 * should be blocked when executing {@link inlcudeInHTML()}. This is useful, for example, 
+	 * to block scripts included by a superclass without having to override entire functions and
+	 * duplicate a lot of code.
+	 * 
 	 * Use {@link unblock()} or {@link unblock_all()} to revert changes.
 	 *
 	 * @var array $blocked
@@ -419,82 +467,93 @@ class Requirements_Backend {
 	protected $blocked = array();
 
 	/**
-	 * See {@link combine_files()}.
+	 * A list of combined files registered via {@link combine_files()}. Keys are the output file
+	 * names, values are lists of input files.
 	 *
 	 * @var array $combine_files
 	 */
 	public $combine_files = array();
 
 	/**
-	 * Using the JSMin library to minify any
-	 * javascript file passed to {@link combine_files()}.
+	 * Use the JSMin library to minify any javascript file passed to {@link combine_files()}.
 	 *
-	 * @var boolean
+	 * @var bool
 	 */
 	public $combine_js_with_jsmin = true;
 
 	/**
-	 * Setting for whether or not a file header should be written when
-	 * combining files.
+	 * Whether or not file headers should be written when combining files
 	 *
 	 * @var boolean
 	 */
 	public $write_header_comment = true;
-
+	
 	/**
-	 * @var string By default, combined files are stored in assets/_combinedfiles.
-	 * Set this by calling Requirements::set_combined_files_folder()
+	 * Where to save combined files. By default they're placed in assets/_combinedfiles, however
+	 * this may be an issue depending on your setup, especially for CSS files which often contain
+	 * relative paths. 
+	 * 
+	 * @var string
 	 */
 	protected $combinedFilesFolder = null;
 
 	/**
-	 * Put all javascript includes at the bottom of the template
-	 * before the closing <body> tag instead of the <head> tag.
-	 * This means script downloads won't block other HTTP-requests,
-	 * which can be a performance improvement.
-	 * Caution: Doesn't work when modifying the DOM from those external
-	 * scripts without listening to window.onload/document.ready
-	 * (e.g. toplevel document.write() calls).
-	 *
-	 * @see http://developer.yahoo.com/performance/rules.html#js_bottom
-	 *
-	 * @var boolean
+	 * Put all JavaScript includes at the bottom of the template before the closing <body> tag,
+	 * rather than the default behaviour of placing them at the end of the <head> tag. This means 
+	 * script downloads won't block other HTTP requests, which can be a performance improvement.
+	 * 
+	 * @var bool
 	 */
 	public $write_js_to_body = true;
-	
+
 	/**
-	 * Force the javascripts to the bottom of the page, even if there's a
-	 * <script> tag in the body already
-	 *  
+	 * Force the JavaScript to the bottom of the page, even if there's a script tag in the body already
+	 *
 	 * @var boolean
 	 */
 	protected $force_js_to_bottom = false;
 
+	/**
+	 * Enable or disable the combination of CSS and JavaScript files
+	 * 
+	 * @param $enable
+	 */
 	public function set_combined_files_enabled($enable) {
 		$this->combined_files_enabled = (bool) $enable;
 	}
 
+	/**
+	 * Check whether file combination is enabled.
+	 * 
+	 * @return bool
+	 */
 	public function get_combined_files_enabled() {
 		return $this->combined_files_enabled;
 	}
 
 	/**
-	 * @param String $folder
+	 * Set the folder to save combined files in. By default they're placed in assets/_combinedfiles,
+	 * however this may be an issue depending on your setup, especially for CSS files which often 
+	 * contain relative paths.
+	 * 
+	 * @param string $folder
 	 */
 	public function setCombinedFilesFolder($folder) {
 		$this->combinedFilesFolder = $folder;
 	}
 
 	/**
-	 * @return String Folder relative to the webroot
+	 * @return string Folder relative to the webroot
 	 */
 	public function getCombinedFilesFolder() {
 		return ($this->combinedFilesFolder) ? $this->combinedFilesFolder : ASSETS_DIR . '/_combinedfiles';
 	}
 
 	/**
-	 * Set whether we want to suffix requirements with the time /
-	 * location on to the requirements
+	 * Set whether to add caching query params to the requests for file-based requirements.
+	 * Eg: themes/myTheme/js/main.js?m=123456789. The parameter is a timestamp generated by
+	 * filemtime. This has the benefit of allowing the browser to cache the URL infinitely,
+	 * while automatically busting this cache every time the file is changed.
 	 *
 	 * @param bool
 	 */
@@ -503,7 +562,7 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Return whether we want to suffix requirements
+	 * Check whether we want to suffix requirements
 	 *
 	 * @return bool
 	 */
@@ -512,45 +571,47 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Set whether you want the files written to the head or the body. It
-	 * writes to the body by default which can break some scripts
+	 * Set whether you want to write the JS to the body of the page rather than at the end of the
+	 * head tag.
 	 *
-	 * @param boolean
+	 * @param bool
 	 */
 	public function set_write_js_to_body($var) {
 		$this->write_js_to_body = $var;
 	}
+
 	/**
-	 * Forces the javascript to the end of the body, just before the closing body-tag.
+	 * Forces the JavaScript requirements to the end of the body, right before the closing tag
 	 *
-	 * @param boolean
+	 * @param bool
 	 */
 	public function set_force_js_to_bottom($var) {
 		$this->force_js_to_bottom = $var;
 	}
+	
 	/**
-	 * Register the given javascript file as required.
-	 * Filenames should be relative to the base, eg, 'framework/javascript/loader.js'
+	 * Register the given JavaScript file as required.
+	 *
+	 * @param string $file Relative to docroot
 	 */
-
 	public function javascript($file) {
 		$this->javascript[$file] = true;
 	}
 
 	/**
-	 * Returns an array of all included javascript
+	 * Returns an array of all required JavaScript
 	 *
 	 * @return array
 	 */
 	public function get_javascript() {
-		return array_keys(array_diff_key($this->javascript,$this->blocked));
+		return array_keys(array_diff_key($this->javascript, $this->blocked));
 	}
 
 	/**
-	 * Add the javascript code to the header of the page
-	 * @todo Make Requirements automatically put this into a separate file :-)
-	 * @param script The script content
-	 * @param uniquenessID Use this to ensure that pieces of code only get added once.
+	 * Register the given JavaScript code into the list of requirements
+	 *
+	 * @param string     $script       The script content as a string (without enclosing <script> tag)
+	 * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
 	 */
 	public function customScript($script, $uniquenessID = null) {
 		if($uniquenessID) $this->customScript[$uniquenessID] = $script;
@@ -560,10 +621,27 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Include custom CSS styling to the header of the page.
+	 * Return all registered custom scripts
 	 *
-	 * @param string $script CSS selectors as a string (without <style> tag enclosing selectors).
-	 * @param int $uniquenessID Group CSS by a unique ID as to avoid duplicate custom CSS in header
+	 * @return array
+	 */
+	public function get_custom_scripts() {
+		$requirements = "";
+
+		if($this->customScript) {
+			foreach($this->customScript as $script) {
+				$requirements .= "$script\n";
+			}
+		}
+
+		return $requirements;
+	}
+
+	/**
+	 * Register the given CSS styles into the list of requirements
+	 *
+	 * @param string     $script       CSS selectors as a string (without enclosing <style> tag)
+	 * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
 	 */
 	public function customCSS($script, $uniquenessID = null) {
 		if($uniquenessID) $this->customCSS[$uniquenessID] = $script;
@@ -571,10 +649,10 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Add the following custom code to the <head> section of the page.
+	 * Add the following custom HTML code to the <head> section of the page
 	 *
-	 * @param string $html
-	 * @param string $uniquenessID
+	 * @param string     $html         Custom HTML code
+	 * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
 	 */
 	public function insertHeadTags($html, $uniquenessID = null) {
 		if($uniquenessID) $this->customHeadTags[$uniquenessID] = $html;
@@ -582,9 +660,12 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Load the given javascript template with the page.
-	 * @param file The template file to load.
-	 * @param vars The array of variables to load.  These variables are loaded via string search & replace.
+	 * Include the content of the given JavaScript file in the list of requirements. Dollar-sign
+	 * variables will be interpolated with values from $vars similar to a .ss template.
+	 *
+	 * @param string         $file         The template file to load, relative to docroot
+	 * @param string[]|int[] $vars         The array of variables to interpolate.
+	 * @param string|int     $uniquenessID A unique ID that ensures a piece of code is only added once
 	 */
 	public function javascriptTemplate($file, $vars, $uniquenessID = null) {
 		$script = file_get_contents(Director::getAbsFile($file));
@@ -601,11 +682,11 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Register the given stylesheet file as required.
+	 * Register the given stylesheet into the list of requirements.
 	 *
-	 * @param $file String Filenames should be relative to the base, eg, 'framework/javascript/tree/tree.css'
-	 * @param $media String Comma-separated list of media-types (e.g. "screen,projector")
-	 * @see http://www.w3.org/TR/REC-CSS2/media.html
+	 * @param string $file  The CSS file to load, relative to site root
+	 * @param string $media Comma-separated list of media types to use in the link tag
+	 *                      (e.g. 'screen,projector')
 	 */
 	public function css($file, $media = null) {
 		$this->css[$file] = array(
@@ -613,28 +694,22 @@ class Requirements_Backend {
 		);
 	}
 
+	/**
+	 * Get the list of registered CSS file requirements, excluding blocked files
+	 * 
+	 * @return array
+	 */
 	public function get_css() {
 		return array_diff_key($this->css, $this->blocked);
 	}
 
 	/**
-	 * Needed to actively prevent the inclusion of a file,
-	 * e.g. when using your own jQuery version.
-	 * Blocking should only be used as an exception, because
-	 * it is hard to trace back. You can just block items with an
-	 * ID, so make sure you add an unique identifier to customCSS() and customScript().
+	 * Clear either a single or all requirements
 	 *
-	 * @param string $fileOrID
-	 */
-	public function block($fileOrID) {
-		$this->blocked[$fileOrID] = $fileOrID;
-	}
-
-	/**
-	 * Clear either a single or all requirements.
-	 * Caution: Clearing single rules works only with customCSS and customScript if you specified a {@uniquenessID}.
+	 * Caution: Clearing single rules added via customCSS and customScript only works if you
+	 * originally specified a $uniquenessID.
 	 *
-	 * @param $file String
+	 * @param string|int $fileOrID
 	 */
 	public function clear($fileOrID = null) {
 		if($fileOrID) {
@@ -659,21 +734,6 @@ class Requirements_Backend {
 		}
 	}
 
-	/**
-	 * Removes an item from the blocking-list.
-	 * CAUTION: Does not "re-add" any previously blocked elements.
-	 * @param string $fileOrID
-	 */
-	public function unblock($fileOrID) {
-		if(isset($this->blocked[$fileOrID])) unset($this->blocked[$fileOrID]);
-	}
-	/**
-	 * Removes all items from the blocking-list.
-	 */
-	public function unblock_all() {
-		$this->blocked = array();
-	}
-
 	/**
 	 * Restore requirements cleared by call to Requirements::clear
 	 */
@@ -684,18 +744,48 @@ class Requirements_Backend {
 		$this->customCSS = $this->disabled['customCSS'];
 		$this->customHeadTags = $this->disabled['customHeadTags'];
 	}
+	/**
+	 * Block inclusion of a specific file
+	 *
+	 * The difference between this and {@link clear} is that the calling order does not matter;
+	 * {@link clear} must be called after the initial registration, whereas {@link block} can be
+	 * used in advance. This is useful, for example, to block scripts included by a superclass
+	 * without having to override entire functions and duplicate a lot of code.
+	 *
+	 * Note that blocking should be used sparingly because it's hard to trace where an file is
+	 * being blocked from.
+	 *
+	 * @param string|int $fileOrID
+	 */
+	public function block($fileOrID) {
+		$this->blocked[$fileOrID] = $fileOrID;
+	}
+
+	/**
+	 * Remove an item from the block list
+	 *
+	 * @param string|int $fileOrID
+	 */
+	public function unblock($fileOrID) {
+		if(isset($this->blocked[$fileOrID])) unset($this->blocked[$fileOrID]);
+	}
+
+	/**
+	 * Removes all items from the block list
+	 */
+	public function unblock_all() {
+		$this->blocked = array();
+	}
 
 	/**
 	 * Update the given HTML content with the appropriate include tags for the registered
 	 * requirements. Needs to receive a valid HTML/XHTML template in the $content parameter,
-	 * including a <head> tag. The requirements will insert before the closing <head> tag automatically.
+	 * including a head and body tag.
 	 *
-	 * @todo Calculate $prefix properly
-	 *
-	 * @param string $templateFilePath Absolute path for the *.ss template file
-	 * @param string $content HTML content that has already been parsed from the $templateFilePath
-	 *                        through {@link SSViewer}.
-	 * @return string HTML content thats augumented with the requirements before the closing <head> tag.
+	 * @param string $templateFile No longer used, only retained for compatibility
+	 * @param string $content      HTML content that has already been parsed from the $templateFile
+	 *                             through {@link SSViewer}
+	 * @return string HTML content augmented with the requirements tags
 	 */
 	public function includeInHTML($templateFile, $content) {
 		if(
@@ -715,8 +805,7 @@ class Requirements_Backend {
 				}
 			}
 
-			// add all inline javascript *after* including external files which
-			// they might rely on
+			// Add all inline JavaScript *after* including external files they might rely on
 			if($this->customScript) {
 				foreach(array_diff_key($this->customScript,$this->blocked) as $script) {
 					$jsRequirements .= "<script type=\"text/javascript\">\n//<![CDATA[\n";
@@ -746,9 +835,8 @@ class Requirements_Backend {
 				// Remove all newlines from code to preserve layout
 				$jsRequirements = preg_replace('/>\n*/', '>', $jsRequirements);
 
-				// We put script tags into the body, for performance.
-				// We forcefully put it at the bottom instead of before
-				// the first script-tag occurence
+				// Forcefully put the scripts at the bottom of the body instead of before the first
+				// script tag.
 				$content = preg_replace("/(<\/body[^>]*>)/i", $jsRequirements . "\\1", $content);
 				
 				// Put CSS at the bottom of the head
@@ -756,8 +844,7 @@ class Requirements_Backend {
 			} elseif($this->write_js_to_body) {
 				// Remove all newlines from code to preserve layout
 				$jsRequirements = preg_replace('/>\n*/', '>', $jsRequirements);
-
-				// We put script tags into the body, for performance.
+				
 				// If your template already has script tags in the body, then we try to put our script
 				// tags just before those. Otherwise, we put it at the bottom.
 				$p2 = stripos($content, '<body');
@@ -766,7 +853,7 @@ class Requirements_Backend {
 				$commentTags = array();
 				$canWriteToBody = ($p1 !== false)
 					&&
-					//check that the script tag is not inside a html comment tag
+					// Check that the script tag is not inside a html comment tag
 					!(
 						preg_match('/.*(?|(<!--)|(-->))/U', $content, $commentTags, 0, $p1)
 						&& 
@@ -791,7 +878,10 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the HTTP response
+	 * Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the given
+	 * HTTP Response
+	 *
+	 * @param SS_HTTPResponse $response
 	 */
 	public function include_in_response(SS_HTTPResponse $response) {
 		$this->process_combined_files();
@@ -819,12 +909,17 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Add i18n files from the given javascript directory.  SilverStripe expects that the given directory
-	 * will contain a number of java script files named by language: en_US.js, de_DE.js, etc.
+	 * Add i18n files from the given javascript directory. SilverStripe expects that the given
+	 * directory will contain a number of JavaScript files named by language: en_US.js, de_DE.js,
+	 * etc.
 	 *
-	 * @param String The javascript lang directory, relative to the site root, e.g., 'framework/javascript/lang'
-	 * @param Boolean Return all relative file paths rather than including them in requirements
-	 * @param Boolean Only include language files, not the base libraries
+	 * @param string $langDir  The JavaScript lang directory, relative to the site root, e.g.,
+	 *                         'framework/javascript/lang'
+	 * @param bool   $return   Return all relative file paths rather than including them in
+	 *                         requirements
+	 * @param bool   $langOnly Only include language files, not the base libraries
+	 *
+	 * @return array
 	 */
 	public function add_i18n_javascript($langDir, $return = false, $langOnly = false) {
 		$files = array();
@@ -863,10 +958,10 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Finds the path for specified file.
+	 * Finds the path for specified file
 	 *
 	 * @param string $fileOrUrl
-	 * @return string|boolean
+	 * @return string|bool
 	 */
 	protected function path_for_file($fileOrUrl) {
 		if(preg_match('{^//|http[s]?}', $fileOrUrl)) {
@@ -896,27 +991,22 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Concatenate several css or javascript files into a single dynamically generated
-	 * file (stored in {@link Director::baseFolder()}). This increases performance
-	 * by fewer HTTP requests.
+	 * Concatenate several css or javascript files into a single dynamically generated file. This 
+	 * increases performance by fewer HTTP requests.
 	 *
-	 * The combined file is regenerated
-	 * based on every file modification time. Optionally a rebuild can be triggered
-	 * by appending ?flush=1 to the URL.
-	 * If all files to be combined are javascript, we use the external JSMin library
-	 * to minify the javascript. This can be controlled by {@link $combine_js_with_jsmin}.
+	 * The combined file is regenerated based on every file modification time. Optionally a 
+	 * rebuild can be triggered by appending ?flush=1 to the URL. If all files to be combined are 
+	 * JavaScript, we use the external JSMin library to minify the JavaScript. This can be 
+	 * controlled using {@link $combine_js_with_jsmin}.
 	 *
-	 * All combined files will have a comment on the start of each concatenated file
-	 * denoting their original position. For easier debugging, we recommend to only
-	 * minify javascript if not in development mode ({@link Director::isDev()}).
+	 * All combined files will have a comment on the start of each concatenated file denoting their 
+	 * original position. For easier debugging, we only minify JavaScript if not in development
+	 * mode ({@link Director::isDev()}).
 	 *
-	 * CAUTION: You're responsible for ensuring that the load order for combined files
-	 * is retained - otherwise combining javascript files can lead to functional errors
-	 * in the javascript logic, and combining css can lead to wrong styling inheritance.
-	 * Depending on the javascript logic, you also have to ensure that files are not included
-	 * in more than one combine_files() call.
-	 * Best practice is to include every javascript file in exactly *one* combine_files()
-	 * directive to avoid the issues mentioned above - this is enforced by this function.
+	 * CAUTION: You're responsible for ensuring that the load order for combined files is 
+	 * retained - otherwise combining JavaScript files can lead to functional errors in the 
+	 * JavaScript logic, and combining CSS can lead to incorrect inheritance. You can also
+	 * only include each file once across all includes and combinations in a single page load.
 	 *
 	 * CAUTION: Combining CSS Files discards any "media" information.
 	 *
@@ -925,9 +1015,9 @@ class Requirements_Backend {
 	 * Requirements::combine_files(
 	 *  'foobar.js',
 	 *  array(
-	 * 		'mysite/javascript/foo.js',
-	 * 		'mysite/javascript/bar.js',
-	 * 	)
+	 *        'mysite/javascript/foo.js',
+	 *        'mysite/javascript/bar.js',
+	 *    )
 	 * );
 	 * </code>
 	 *
@@ -935,22 +1025,17 @@ class Requirements_Backend {
 	 * <code>
 	 * Requirements::combine_files(
 	 *  'foobar.css',
-	 * 	array(
-	 * 		'mysite/javascript/foo.css',
-	 * 		'mysite/javascript/bar.css',
-	 * 	)
+	 *    array(
+	 *        'mysite/javascript/foo.css',
+	 *        'mysite/javascript/bar.css',
+	 *    )
 	 * );
 	 * </code>
 	 *
-	 * @see http://code.google.com/p/jsmin-php/
-	 *
-	 * @todo Should we enforce unique inclusion of files, or leave it to the developer? Can auto-detection cause
-	 *       breaks?
-	 *
-	 * @param string $combinedFileName Filename of the combined file (will be stored in {@link Director::baseFolder()}
-	 *                                 by default)
-	 * @param array $files Array of filenames relative to the webroot
-	 * @param string $media Comma-separated list of media-types (e.g. "screen,projector").
+	 * @param string $combinedFileName Filename of the combined file relative to docroot
+	 * @param array  $files            Array of filenames relative to docroot
+	 * 
+	 * @return bool|void
 	 */
 	public function combine_files($combinedFileName, $files, $media = null) {
 		// duplicate check
@@ -1004,8 +1089,10 @@ class Requirements_Backend {
 		$this->combine_files[$combinedFileName] = $files;
 	}
 
-		/**
-	 * Returns all combined files.
+	/**
+	 * Return all combined files; keys are the combined file names, values are lists of
+	 * files being combined.
+	 *
 	 * @return array
 	 */
 	public function get_combine_files() {
@@ -1013,7 +1100,7 @@ class Requirements_Backend {
 	}
 
 	/**
-	 * Deletes all dynamically generated combined files from the filesystem.
+	 * Delete all dynamically generated combined files from the filesystem
 	 *
 	 * @param string $combinedFileName If left blank, all combined files are deleted.
 	 */
@@ -1043,16 +1130,19 @@ class Requirements_Backend {
 		}
 	}
 
+	/**
+	 * Clear all registered CSS and JavaScript file combinations
+	 */
 	public function clear_combined_files() {
 		$this->combine_files = array();
 	}
 
 	/**
-	 * See {@link combine_files()}
-	 *
+	 * Do the heavy lifting involved in combining (and, in the case of JavaScript minifying) the
+	 * combined files.
 	 */
 	public function process_combined_files() {
-		// The class_exists call prevents us from loading SapphireTest.php (slow) just to know that
+		// The class_exists call prevents us loading SapphireTest.php (slow) just to know that
 		// SapphireTest isn't running :-)
 		if(class_exists('SapphireTest', false)) $runningTest = SapphireTest::is_running_test();
 		else $runningTest = false;
@@ -1077,7 +1167,7 @@ class Requirements_Backend {
 		// Work out the relative URL for the combined files from the base folder
 		$combinedFilesFolder = ($this->getCombinedFilesFolder()) ? ($this->getCombinedFilesFolder() . '/') : '';
 
-		// Figure out which ones apply to this pageview
+		// Figure out which ones apply to this request
 		$combinedFiles = array();
 		$newJSRequirements = array();
 		$newCSSRequirements = array();
@@ -1112,8 +1202,9 @@ class Requirements_Backend {
 				Filesystem::makeFolder(dirname($combinedFilePath));
 			}
 
-			// If the file isn't writeable, don't even bother trying to make the combined file and return (falls back
-			//  to uncombined).  Complex test because is_writable fails if the file doesn't exist yet.
+			// If the file isn't writeable, don't even bother trying to make the combined file and return. The
+			// files will be included individually instead. This is a complex test because is_writable fails
+			// if the file doesn't exist yet.
 			if((file_exists($combinedFilePath) && !is_writable($combinedFilePath))
 				|| (!file_exists($combinedFilePath) && !is_writable(dirname($combinedFilePath)))
 			) {
@@ -1133,7 +1224,7 @@ class Requirements_Backend {
 				}
 				$refresh = $srcLastMod > filemtime($combinedFilePath);
 			} else {
-				// file doesn't exist, or refresh was explicitly required
+				// File doesn't exist, or refresh was explicitly required
 				$refresh = true;
 			}
 
@@ -1151,8 +1242,7 @@ class Requirements_Backend {
 				}
 
 				if ($this->write_header_comment) {
-					// write a header comment for each file for easier identification and debugging
-					// also the semicolon between each file is required for jQuery to be combinable properly
+					// Write a header comment for each file for easier identification and debugging. The semicolon between each file is required for jQuery to be combined properly and protects against unterminated statements.
 					$combinedData .= "/****** FILE: $file *****/\n";
 				}
 
@@ -1168,7 +1258,7 @@ class Requirements_Backend {
 			}
 			
 			if($failedToMinify){
-				// Failed to minify, use unminified. This warning is raised at the end to allow code execution
+				// Failed to minify, use unminified files instead. This warning is raised at the end to allow code execution
 				// to complete in case this warning is caught inside a try-catch block. 
 				user_error('Failed to minify '.$file.', exception: '.$e->getMessage(), E_USER_WARNING);
 			}
@@ -1181,12 +1271,19 @@ class Requirements_Backend {
 			}
 		}
 
-		// @todo Alters the original information, which means you can't call this
-		// method repeatedly - it will behave different on the second call!
+		// Note: Alters the original information, which means you can't call this method repeatedly - it will behave
+		// differently on the subsequent calls
 		$this->javascript = $newJSRequirements;
 		$this->css = $newCSSRequirements;
 	}
 
+	/**
+	 * Minify the given $content according to the file type indicated in $filename
+	 * 
+	 * @param string $filename
+	 * @param string $content
+	 * @return string
+	 */
 	protected function minifyFile($filename, $content) {
 		// if we have a javascript file and jsmin is enabled, minify the content
 		$isJS = stripos($filename, '.js');
@@ -1200,20 +1297,18 @@ class Requirements_Backend {
 		return $content;
 	}
 
-	public function get_custom_scripts() {
-		$requirements = "";
-
-		if($this->customScript) {
-			foreach($this->customScript as $script) {
-				$requirements .= "$script\n";
-			}
-		}
-
-		return $requirements;
-	}
-
 	/**
-	 * @see Requirements::themedCSS()
+	 * Registers the given themeable stylesheet as required.
+	 *
+	 * A CSS file in the current theme path name 'themename/css/$name.css' is first searched for,
+	 * and it that doesn't exist and the module parameter is set then a CSS file with that name in
+	 * the module is used.
+	 *
+	 * @param string $name   The name of the file - eg '/css/File.css' would have the name 'File'
+	 * @param string $module The module to fall back to if the css file does not exist in the
+	 *                       current theme.
+	 * @param string $media  Comma-separated list of media types to use in the link tag
+	 *                       (e.g. 'screen,projector')
 	 */
 	public function themedCSS($name, $module = null, $media = null) {
 		$theme = SSViewer::get_theme_folder();
@@ -1234,6 +1329,9 @@ class Requirements_Backend {
 		}
 	}
 
+	/**
+	 * Output debugging information.
+	 */
 	public function debug() {
 		Debug::show($this->javascript);
 		Debug::show($this->css);