Make WordPress Core

Opened 12 years ago

Closed 12 years ago

Last modified 12 years ago

#23914 closed enhancement (fixed)

Document WP_Dependencies

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

Download all attachments as: .zip

Change History (16)

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

  • Cc xoodrew@… added

#3 @DrewAPicture
12 years ago

  • Component changed from Text Changes to Inline Docs

my bad, inline docs.

@kitchin
12 years ago

Some improvements, tell me if want an interdiff.

#4 @markoheijnen
12 years ago

  • Milestone changed from Awaiting Review to 3.7

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

+ properties + _WP_Dependency + other stuff.

#6 @DrewAPicture
12 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
12 years ago

Separated out properties to separate patches

@DrewAPicture
12 years ago

WP_Dependencies properties only

@DrewAPicture
12 years ago

_WP_Dependency properties only

#7 @DrewAPicture
12 years ago

In 25517:

Inline documentation for WP_Dependencies class properties.

See #23914.

#8 @DrewAPicture
12 years ago

In 25518:

Inline documentation for _WP_Dependency class properties.

See #23914.

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

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