From 592da58d2696504f1bac748aeb5090f000b7e961 Mon Sep 17 00:00:00 2001 From: "Dominik Schilling (ocean90)" Date: Sat, 27 Feb 2016 20:33:57 +0000 Subject: [PATCH] Docs: Improve inline docs for `WP_Dependencies`, `WP_Styles`, and `WP_Scripts`. Also, make them and related files part of WordPress. See #35964. git-svn-id: https://develop.svn.wordpress.org/trunk@36744 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/class.wp-dependencies.php | 27 ++++--- src/wp-includes/class.wp-scripts.php | 97 ++++++++++++++++------- src/wp-includes/class.wp-styles.php | 80 ++++++++++++------- src/wp-includes/functions.wp-scripts.php | 4 +- src/wp-includes/functions.wp-styles.php | 4 +- src/wp-includes/script-loader.php | 15 ++-- 6 files changed, 146 insertions(+), 81 deletions(-) diff --git a/src/wp-includes/class.wp-dependencies.php b/src/wp-includes/class.wp-dependencies.php index 211fa14821..11068f970a 100644 --- a/src/wp-includes/class.wp-dependencies.php +++ b/src/wp-includes/class.wp-dependencies.php @@ -1,14 +1,19 @@ get_data( $handle, 'data' ) ) @@ -215,14 +237,17 @@ class WP_Scripts extends WP_Dependencies { } /** + * Processes a script dependency. * * @since 2.6.0 * @since 2.8.0 Added the `$group` parameter. * @access public * - * @param string $handle Name of the item. Should be unique. - * @param int|bool $group - * @return bool True on success, false if not set. + * @see WP_Dependencies::do_item() + * + * @param string $handle The script's registered handle. + * @param int|false $group Optional. Group level: (int) level, (false) no groups. Default false. + * @return bool True on success, false on failure. */ public function do_item( $handle, $group = false ) { if ( !parent::do_item($handle) ) @@ -406,7 +431,7 @@ class WP_Scripts extends WP_Dependencies { } /** - * Localizes a script, only if the script has already been added + * Localizes a script, only if the script has already been added. * * @since 2.1.0 * @access public @@ -446,13 +471,16 @@ class WP_Scripts extends WP_Dependencies { } /** + * Sets handle group. * * @since 2.8.0 * @access public * - * @param string $handle Name of the item. Should be unique. - * @param bool $recursion Internal flag that calling function was called recursively. - * @param mixed $group Group level. + * @see WP_Dependencies::set_group() + * + * @param string $handle Name of the item. Should be unique. + * @param bool $recursion Internal flag that calling function was called recursively. + * @param int|false $group Optional. Group level: (int) level, (false) no groups. Default false. * @return bool Not already in the group or a lower group */ public function set_group( $handle, $recursion, $group = false ) { @@ -468,13 +496,16 @@ class WP_Scripts extends WP_Dependencies { } /** - * + * Determines script dependencies. + * * @since 2.1.0 * @access public * - * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings). - * @param bool $recursion Internal flag that function is calling itself. - * @param mixed $group Group level: (int) level, (false) no groups. + * @see WP_Dependencies::all_deps() + * + * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings). + * @param bool $recursion Internal flag that function is calling itself. + * @param int|false $group Optional. Group level: (int) level, (false) no groups. Default false. * @return bool True on success, false on failure. */ public function all_deps( $handles, $recursion = false, $group = false ) { @@ -493,11 +524,14 @@ class WP_Scripts extends WP_Dependencies { } /** + * Processes items and dependencies for the head group. * * @since 2.8.0 * @access public * - * @return array + * @see WP_Dependencies::do_items() + * + * @return array Handles of items that have been processed. */ public function do_head_items() { $this->do_items(false, 0); @@ -505,11 +539,14 @@ class WP_Scripts extends WP_Dependencies { } /** + * Processes items and dependencies for the footer group. * * @since 2.8.0 * @access public * - * @return array + * @see WP_Dependencies::do_items() + * + * @return array Handles of items that have been processed. */ public function do_footer_items() { $this->do_items(false, 1); @@ -517,12 +554,13 @@ class WP_Scripts extends WP_Dependencies { } /** + * Whether a handle's source is in a default directory. * * @since 2.8.0 * @access public * - * @param string $src - * @return bool + * @param string $src The source of the enqueued script. + * @return bool True if found, false if not. */ public function in_default_dir( $src ) { if ( ! $this->default_dirs ) { @@ -542,6 +580,7 @@ class WP_Scripts extends WP_Dependencies { } /** + * Resets class properties. * * @since 2.8.0 * @access public diff --git a/src/wp-includes/class.wp-styles.php b/src/wp-includes/class.wp-styles.php index 3a101d77b9..788e8a3fa9 100644 --- a/src/wp-includes/class.wp-styles.php +++ b/src/wp-includes/class.wp-styles.php @@ -1,20 +1,19 @@ get_data( $handle, 'after' ); @@ -280,18 +297,21 @@ class WP_Styles extends WP_Dependencies { } /** + * Determines style dependencies. * * @since 2.6.0 * @access public * - * @param mixed $handles - * @param bool $recursion - * @param mixed $group - * @return bool + * @see WP_Dependencies::all_deps() + * + * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings). + * @param bool $recursion Internal flag that function is calling itself. + * @param int|false $group Group level: (int) level, (false) no groups. + * @return bool True on success, false on failure. */ public function all_deps( $handles, $recursion = false, $group = false ) { $r = parent::all_deps( $handles, $recursion ); - if ( !$recursion ) { + if ( ! $recursion ) { /** * Filter the array of enqueued styles before processing for output. * @@ -305,14 +325,15 @@ class WP_Styles extends WP_Dependencies { } /** + * Generates an enqueued style's fully-qualified URL. * * @since 2.6.0 * @access public * - * @param string $src - * @param string $ver - * @param string $handle - * @return string + * @param string $src The source of the enqueued style. + * @param string $ver The version of the enqueued style. + * @param string $handle The style's registered handle. + * @return string Style's fully-qualified URL. */ public function _css_href( $src, $ver, $handle ) { if ( !is_bool($src) && !preg_match('|^(https?:)?//|', $src) && ! ( $this->content_url && 0 === strpos($src, $this->content_url) ) ) { @@ -335,12 +356,13 @@ class WP_Styles extends WP_Dependencies { } /** + * Whether a handle's source is in a default directory. * * @since 2.8.0 * @access public * - * @param string $src - * @return bool + * @param string $src The source of the enqueued style. + * @return bool True if found, false if not. */ public function in_default_dir( $src ) { if ( ! $this->default_dirs ) @@ -354,13 +376,16 @@ class WP_Styles extends WP_Dependencies { } /** + * Processes items and dependencies for the footer group. * * HTML 5 allows styles in the body, grab late enqueued items and output them in the footer. * * @since 3.3.0 * @access public * - * @return array + * @see WP_Dependencies::do_items() + * + * @return array Handles of items that have been processed. */ public function do_footer_items() { $this->do_items(false, 1); @@ -368,6 +393,7 @@ class WP_Styles extends WP_Dependencies { } /** + * Resets class properties. * * @since 3.3.0 * @access public diff --git a/src/wp-includes/functions.wp-scripts.php b/src/wp-includes/functions.wp-scripts.php index cb450f48fd..96543fe1b4 100644 --- a/src/wp-includes/functions.wp-scripts.php +++ b/src/wp-includes/functions.wp-scripts.php @@ -1,11 +1,11 @@