Ticket #23914: wp-dependencies-patch.txt

Index: wp-includes/class.wp-dependencies.php
===================================================================
--- wp-includes/class.wp-dependencies.php       (revision 23883)
+++ wp-includes/class.wp-dependencies.php       (working copy)
@@ -21,27 +21,35 @@
        var $queue = array();
        var $to_do = array();
        var $done = array();
-       var $args = array();
-       var $groups = array();
-       var $group = 0;
+       var $args = array();  // In extending classes, strings appended to item urls.
+       var $groups = array();  // In extending class WP_Scripts, header and footer groups.
+       var $group = 0;  // Internal group state.
 
        /**
         * Do the dependencies
         *
-        * Process the items passed to it or the queue. Processes all dependencies.
+        * Processes the items passed to it or the queue. Processes all dependencies.
         *
-        * @param mixed $handles (optional) items to be processed. (void) processes queue, (string) process that item, (array of strings) process those items
-        * @return array Items that have been processed
+        * @param mixed $handles (optional) Items to be processed: (false) Process queue, (string) process item, (array of strings) process items
+        * @param mixed $group Group level: (int) level, (false) no groups
+        * @return array Handles of items that have been processed
         */
        function do_items( $handles = false, $group = false ) {
-               // Print the queue if nothing is passed. If a string is passed, print that script. If an array is passed, print those scripts.
+               // Print the queue if nothing is passed. If a string is passed, print that item. If an array is passed, print those items.
                $handles = false === $handles ? $this->queue : (array) $handles;
                $this->all_deps( $handles );
 
                foreach( $this->to_do as $key => $handle ) {
                        if ( !in_array($handle, $this->done, true) && isset($this->registered[$handle]) ) {
 
-                               if ( ! $this->registered[$handle]->src ) { // Defines a group.
+                               /**
+                                * A single item may alias a set of items, by having dependencies but no src.
+                                * Queuing the item queues the dependencies.
+                                * Example: the extending class WP_Scripts is used to register 'scriptaculous' as a set of registered handles:
+                                *   add( 'scriptaculous', false, array('scriptaculous-dragdrop', 'scriptaculous-slider', 'scriptaculous-controls') );
+                                * The src property is false.
+                               **/
+                               if ( ! $this->registered[$handle]->src ) {
                                        $this->done[] = $handle;
                                        continue;
                                }
@@ -56,18 +64,28 @@
                return $this->done;
        }
 
+       /**
+        * Do dependency
+        *
+        * Processes one item for dependencies.
+        *
+        * @param string $handle Unique item name
+        * @return bool Success
+        */
        function do_item( $handle ) {
                return isset($this->registered[$handle]);
        }
 
        /**
-        * Determines dependencies
+        * Determine dependencies
         *
-        * Recursively builds array of items to process taking dependencies into account. Does NOT catch infinite loops.
+        * Recursively builds array of items to process taking dependencies into account.
+        * Does NOT catch infinite loops.
         *
-        *
-        * @param mixed $handles Accepts (string) dep name or (array of strings) dep names
-        * @param bool $recursion Used internally when function calls itself
+        * @param mixed $handles (string) Dependency handle and argument or (array of strings) Dependency handles and arguments
+        * @param bool $recursion Internal flag that function is calling itself
+        * @param mixed $group Group level: (int) level, (false) no groups
+        * @return bool Success
         */
        function all_deps( $handles, $recursion = false, $group = false ) {
                if ( !$handles = (array) $handles )
@@ -88,13 +106,13 @@
 
                        $keep_going = true;
                        if ( !isset($this->registered[$handle]) )
-                               $keep_going = false; // Script doesn't exist
+                               $keep_going = false; // Item doesn't exist
                        elseif ( $this->registered[$handle]->deps && array_diff($this->registered[$handle]->deps, array_keys($this->registered)) )
-                               $keep_going = false; // Script requires deps which don't exist (not a necessary check. efficiency?)
+                               $keep_going = false; // Item requires deps which don't exist (not a necessary check. efficiency?)
                        elseif ( $this->registered[$handle]->deps && !$this->all_deps( $this->registered[$handle]->deps, true, $group ) )
-                               $keep_going = false; // Script requires deps which don't exist
+                               $keep_going = false; // Item requires deps which don't exist
 
-                       if ( !$keep_going ) { // Either script or its deps don't exist.
+                       if ( !$keep_going ) { // Either item or its deps don't exist.
                                if ( $recursion )
                                        return false; // Abort this branch.
                                else
@@ -114,15 +132,16 @@
        }
 
        /**
-        * Adds item
+        * Register item
         *
-        * Adds the item only if no item of that name already exists
+        * Registers the item if no item of that name already exists.
         *
-        * @param string $handle Script name
-        * @param string $src Script url
-        * @param array $deps (optional) Array of script names on which this script depends
-        * @param string $ver (optional) Script version (used for cache busting)
-        * @return array Hierarchical array of dependencies
+        * @param string $handle Unique item name
+        * @param string $src Resource url
+        * @param array of strings $deps (optional) Item handles on which this item depends
+        * @param string $ver (optional) Version (used for cache busting)
+        * @param mixed $args (optional) Custom property of the item. NOT the class property $args. Examples: $media, $in_footer.
+        * @return bool Success
         */
        function add( $handle, $src, $deps = array(), $ver = false, $args = null ) {
                if ( isset($this->registered[$handle]) )
@@ -132,14 +151,14 @@
        }
 
        /**
-        * Adds extra data
+        * Add extra data
         *
-        * Adds data only if script has already been added.
+        * Adds data if item has been registered.
         *
-        * @param string $handle Script name
-        * @param string $key
-        * @param mixed $value
-        * @return bool success
+        * @param string $handle Unique item name
+        * @param string $key Data key
+        * @param mixed $value Data value
+        * @return bool Success
         */
        function add_data( $handle, $key, $value ) {
                if ( !isset( $this->registered[$handle] ) )
@@ -151,13 +170,13 @@
        /**
         * Get extra data
         *
-        * Gets data associated with a certain handle.
+        * Gets data associated with a registered item.
         *
         * @since WP 3.3
         *
-        * @param string $handle Script name
-        * @param string $key
-        * @return mixed
+        * @param string $handle Unique item name
+        * @param string $key Data key
+        * @return mixed Data value
         */
        function get_data( $handle, $key ) {
                if ( !isset( $this->registered[$handle] ) )
@@ -169,11 +188,27 @@
                return $this->registered[$handle]->extra[$key];
        }
 
+       /**
+        * Unregister items
+        *
+        * @param mixed $handles (string) Item handle or (array of strings) Item handles
+        * @return void
+        */
        function remove( $handles ) {
                foreach ( (array) $handles as $handle )
                        unset($this->registered[$handle]);
        }
 
+       /**
+        * Queue items
+        *
+        * Decode handle and argument, then queue handle and store argument in the class property $args.
+        * For example, in extending classes, $args is appended to the item url.
+        * Note $args is NOT the $args property of items in the $registered array.
+        *
+        * @param mixed $handles (string) Item handle and argument or (array of strings) Item handles and arguments
+        * @return void
+        */
        function enqueue( $handles ) {
                foreach ( (array) $handles as $handle ) {
                        $handle = explode('?', $handle);
@@ -185,6 +220,14 @@
                }
        }
 
+       /**
+        * Dequeue items
+        *
+        * Decode handle and argument, then dequeue handle and remove argument from the class property $args.
+        *
+        * @param mixed $handles (string) Item handle and argument or (array of strings) Item handles and arguments
+        * @return void
+        */
        function dequeue( $handles ) {
                foreach ( (array) $handles as $handle ) {
                        $handle = explode('?', $handle);
@@ -196,7 +239,12 @@
                }
        }
 
-
+       /**
+        * Query list for item
+        *
+        * @param $handle (string) Item handle
+        * @return bool Found, or object Item data
+        */
        function query( $handle, $list = 'registered' ) {
                switch ( $list ) {
                        case 'registered' :
@@ -220,6 +268,14 @@
                return false;
        }
 
+       /**
+        * Set item group, unless already in a lower group
+        *
+        * @param $handle (string) Item handle
+        * @param bool $recursion Internal flag that calling function was called recusively
+        * @param mixed $group Group level
+        * @return bool Not already in the group or a lower group
+        */
        function set_group( $handle, $recursion, $group ) {
                $group = (int) $group;
 
@@ -242,8 +298,7 @@
        var $src;
        var $deps = array();
        var $ver = false;
-       var $args = null;
-
+       var $args = null;  // Custom property, such as $in_footer or $media.
        var $extra = array();
 
        function __construct() {