Document WP_Dependencies

[kitchin]

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.

[DrewAPicture]

Can you re-upload the svn patch in the proper format with either a .diff or .patch extension?

[DrewAPicture]

my bad, inline docs.

[kitchin]

Some improvements, tell me if want an interdiff.

[DrewAPicture]

class.wp-dependencies.php.patch​ is a good starting point, though there's a lot more work to be done.

• ​Properties need to be documented
• ​Array parameters need to be documented
• All methods need ​x.x.x-style versions
• ​Short descriptions need periods

I'll have an incremental patch shortly to help these tasks along.

Also, we'll need to document any ​hooks or filters though that's probably best left to the hooks/filters effort going on over in #25229.

[DrewAPicture]

+ properties + _WP_Dependency + other stuff.

[DrewAPicture]

23914.diff​ builds off of class.wp-dependencies.php.patch​ to add docs for class properties, _WP_Dependency class, and other small tweaks.

[DrewAPicture]

Separated out properties to separate patches

[DrewAPicture]

WP_Dependencies properties only

[DrewAPicture]

_WP_Dependency properties only

[DrewAPicture]

In 25517:

Inline documentation for WP_Dependencies class properties.

See #23914.

[DrewAPicture]

In 25518:

Inline documentation for _WP_Dependency class properties.

See #23914.

[DrewAPicture]

In 25524:

Inline documentation for WP_Dependencies and _WP_Dependency classes.

Props kitchin for the initial patch.
Fixes #23914.