WordPress.org

Make WordPress Core

Opened 13 months ago

Closed 7 months ago

Last modified 7 months ago

#23914 closed enhancement (fixed)

Document WP_Dependencies

Reported by: kitchin Owned by: DrewAPicture
Milestone: 3.7 Priority: normal
Severity: normal Version: 3.5
Component: Inline Docs Keywords: has-patch
Focuses: Cc:

Description

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.
  1. $handle sometimes means the registered handle, and other times means handle?args.
  1. $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.

Attachments (6)

wp-dependencies-patch.txt (8.8 KB) - added by kitchin 13 months ago.
class.wp-dependencies.php.patch (8.7 KB) - added by kitchin 13 months ago.
Some improvements, tell me if want an interdiff.
23914.diff (11.9 KB) - added by DrewAPicture 8 months ago.
+ properties + _WP_Dependency + other stuff.
23914.2.diff (11.8 KB) - added by DrewAPicture 7 months ago.
Separated out properties to separate patches
23914-properties.diff (1.4 KB) - added by DrewAPicture 7 months ago.
WP_Dependencies properties only
23914-properties-2.diff (1.1 KB) - added by DrewAPicture 7 months ago.
_WP_Dependency properties only

Download all attachments as: .zip

Change History (16)

comment:1 DrewAPicture13 months ago

  • Component changed from Template to Text Changes
  • Version trunk deleted

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

comment:2 DrewAPicture13 months ago

  • Cc xoodrew@… added

comment:3 DrewAPicture13 months ago

  • Component changed from Text Changes to Inline Docs

my bad, inline docs.

kitchin13 months ago

Some improvements, tell me if want an interdiff.

comment:4 markoheijnen8 months ago

  • Milestone changed from Awaiting Review to 3.7

comment:5 DrewAPicture8 months ago

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

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.

DrewAPicture8 months ago

+ properties + _WP_Dependency + other stuff.

comment:6 DrewAPicture8 months ago

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

DrewAPicture7 months ago

Separated out properties to separate patches

DrewAPicture7 months ago

WP_Dependencies properties only

DrewAPicture7 months ago

_WP_Dependency properties only

comment:7 DrewAPicture7 months ago

In 25517:

Inline documentation for WP_Dependencies class properties.

See #23914.

comment:8 DrewAPicture7 months ago

In 25518:

Inline documentation for _WP_Dependency class properties.

See #23914.

comment:9 DrewAPicture7 months ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

In 25524:

Inline documentation for WP_Dependencies and _WP_Dependency classes.

Props kitchin for the initial patch.
Fixes #23914.

comment:10 DrewAPicture7 months ago

  • Version set to 3.5
Note: See TracTickets for help on using tickets.