[wp-trac] [WordPress Trac] #23914: Document WP_Dependencies

[WordPress Trac]

#23914: Document WP_Dependencies
-----------------------------+-------------------------
 Reporter:  kitchin          |       Type:  enhancement
   Status:  new              |   Priority:  normal
Milestone:  Awaiting Review  |  Component:  Template
  Version:  trunk            |   Severity:  normal
 Keywords:  has-patch        |
-----------------------------+-------------------------
 The code in `wp-includes/class.wp-dependencies.php` needs better
 documentation. Three confusions in particular:

 1. $args has a different meaning in WP_Dependencies and _WP_Dependency. In
 the first, it is a way to append query strings to the URL's. In the second
 it is a generic 5th parameter used by the API functions wp_register_*()
 and wp_enqueue_*(). In class WP_Styles it stands for $media. In class
 WP_Scripts it stands for $in_footer.

 2. `$handle` sometimes means the registered `handle`, and other times
 means `handle?args`.

 3. `$group` stands for page placement in WP_Styles (0=header, 1=footer),
 and is unused in WP_Scripts (false). But a prominent comment uses the word
 "Groups" to describe something entirely different, a registered item with
 dependencies but no src. In my proposed documentation I use the word
 "Alias" for this meaning. An example of an alias is in wp-includes/script-
 loader.php:
 {{{
 add( 'scriptaculous', false, array('scriptaculous-dragdrop',
 'scriptaculous-slider', 'scriptaculous-controls') );
 }}}

 Patch attached. No code changes.

 An example of contributors not knowing about Confusion 2 is #13078.

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/23914>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software