WordPress.org

Make WordPress Core

Opened 7 years ago

Closed 7 years ago

Last modified 7 years 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 7 years ago.
class.wp-dependencies.php.patch (8.7 KB) - added by kitchin 7 years ago.
Some improvements, tell me if want an interdiff.
23914.diff (11.9 KB) - added by DrewAPicture 7 years ago.
+ properties + _WP_Dependency + other stuff.
23914.2.diff (11.8 KB) - added by DrewAPicture 7 years ago.
Separated out properties to separate patches
23914-properties.diff (1.4 KB) - added by DrewAPicture 7 years ago.
WP_Dependencies properties only
23914-properties-2.diff (1.1 KB) - added by DrewAPicture 7 years ago.
_WP_Dependency properties only

Download all attachments as: .zip

Change History (16)

#1 @DrewAPicture
7 years 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?

#2 @DrewAPicture
7 years ago

  • Cc xoodrew@… added

#3 @DrewAPicture
7 years ago

  • Component changed from Text Changes to Inline Docs

my bad, inline docs.

@kitchin
7 years ago

Some improvements, tell me if want an interdiff.

#4 @markoheijnen
7 years ago

  • Milestone changed from Awaiting Review to 3.7

#5 @DrewAPicture
7 years 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.

@DrewAPicture
7 years ago

+ properties + _WP_Dependency + other stuff.

#6 @DrewAPicture
7 years ago

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

@DrewAPicture
7 years ago

Separated out properties to separate patches

@DrewAPicture
7 years ago

WP_Dependencies properties only

@DrewAPicture
7 years ago

_WP_Dependency properties only

#7 @DrewAPicture
7 years ago

In 25517:

Inline documentation for WP_Dependencies class properties.

See #23914.

#8 @DrewAPicture
7 years ago

In 25518:

Inline documentation for _WP_Dependency class properties.

See #23914.

#9 @DrewAPicture
7 years 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.

#10 @DrewAPicture
7 years ago

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