From c289bb59acdd3217cdb81e15b580dc3d7cd6a007 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Mon, 3 Feb 2020 00:19:03 +0000 Subject: [PATCH] Docs: Improve documentation for `WP_Dependencies`, `WP_Scripts`, and `WP_Styles` methods. See #48303. Built from https://develop.svn.wordpress.org/trunk@47170 git-svn-id: http://core.svn.wordpress.org/trunk@46970 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-wp-dependency.php | 1 - wp-includes/class.wp-dependencies.php | 53 ++++++++++++---------- wp-includes/class.wp-scripts.php | 64 ++++++++++++++++----------- wp-includes/class.wp-styles.php | 19 ++++---- wp-includes/l10n.php | 1 - wp-includes/version.php | 2 +- 6 files changed, 79 insertions(+), 61 deletions(-) diff --git a/wp-includes/class-wp-dependency.php b/wp-includes/class-wp-dependency.php index 9648b2ffb6..2d1795334b 100644 --- a/wp-includes/class-wp-dependency.php +++ b/wp-includes/class-wp-dependency.php @@ -123,7 +123,6 @@ class _WP_Dependency { * * @param string $domain The translation textdomain. * @param string $path Optional. The full file path to the directory containing translation files. - * * @return bool False if $domain is not a string, true otherwise. */ public function set_translations( $domain, $path = null ) { diff --git a/wp-includes/class.wp-dependencies.php b/wp-includes/class.wp-dependencies.php index 6e9170eba8..d983f71e0b 100644 --- a/wp-includes/class.wp-dependencies.php +++ b/wp-includes/class.wp-dependencies.php @@ -83,8 +83,10 @@ class WP_Dependencies { * @since 2.6.0 * @since 2.8.0 Added the `$group` parameter. * - * @param mixed $handles Optional. Items to be processed: Process queue (false), process item (string), process items (array of strings). - * @param int|false $group Optional. Group level: level (int), no groups (false). + * @param string|string[]|false $handles Optional. Items to be processed: queue (false), + * single item (string), or multiple items (array of strings). + * Default false. + * @param int|false $group Optional. Group level: level (int), no groups (false). * @return string[] Array of handles of items that have been processed. */ public function do_items( $handles = false, $group = false ) { @@ -136,9 +138,11 @@ class WP_Dependencies { * @since 2.6.0 Moved from `WP_Scripts`. * @since 2.8.0 Added the `$group` parameter. * - * @param string|string[] $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. + * @param string|string[] $handles Item handle (string) or item handles (array of strings). + * @param bool $recursion Optional. Internal flag that function is calling itself. + * Default false. + * @param int|false $group Optional. Group level: level (int), no groups (false). + * Default false. * @return bool True on success, false on failure. */ public function all_deps( $handles, $recursion = false, $group = false ) { @@ -203,14 +207,18 @@ class WP_Dependencies { * @since 2.6.0 Moved from `WP_Scripts`. * * @param string $handle Name of the item. Should be unique. - * @param string|bool $src Full URL of the item, or path of the item relative to the WordPress root directory. - * If source is set to false, item is an alias of other items it depends on. - * @param string[] $deps Optional. An array of registered item handles this item depends on. Default empty array. - * @param string|bool|null $ver Optional. String specifying item version number, if it has one, which is added to the URL - * as a query string for cache busting purposes. If version is set to false, a version - * number is automatically added equal to current installed WordPress version. + * @param string|bool $src Full URL of the item, or path of the item relative + * to the WordPress root directory. If source is set to false, + * item is an alias of other items it depends on. + * @param string[] $deps Optional. An array of registered item handles this item depends on. + * Default empty array. + * @param string|bool|null $ver Optional. String specifying item version number, if it has one, + * which is added to the URL as a query string for cache busting purposes. + * If version is set to false, a version number is automatically added + * equal to current installed WordPress version. * If set to null, no version is added. - * @param mixed $args Optional. Custom property of the item. NOT the class property $args. Examples: $media, $in_footer. + * @param mixed $args Optional. Custom property of the item. NOT the class property $args. + * Examples: $media, $in_footer. * @return bool Whether the item has been registered. True on success, false on failure. */ public function add( $handle, $src, $deps = array(), $ver = false, $args = null ) { @@ -230,7 +238,7 @@ class WP_Dependencies { * * @param string $handle Name of the item. Should be unique. * @param string $key The data key. - * @param mixed $value The data value. + * @param string $value The data value. * @return bool True on success, false on failure. */ public function add_data( $handle, $key, $value ) { @@ -250,7 +258,7 @@ class WP_Dependencies { * * @param string $handle Name of the item. Should be unique. * @param string $key The data key. - * @return mixed Extra item data (string), false otherwise. + * @return string|false Extra item data (string), false otherwise. */ public function get_data( $handle, $key ) { if ( ! isset( $this->registered[ $handle ] ) ) { @@ -270,8 +278,7 @@ class WP_Dependencies { * @since 2.1.0 * @since 2.6.0 Moved from `WP_Scripts`. * - * @param string|string[] $handles Item handle and argument (string) or item handles and arguments (array of strings). - * @return void + * @param string|string[] $handles Item handle (string) or item handles (array of strings). */ public function remove( $handles ) { foreach ( (array) $handles as $handle ) { @@ -290,7 +297,7 @@ class WP_Dependencies { * @since 2.1.0 * @since 2.6.0 Moved from `WP_Scripts`. * - * @param string|string[] $handles Item handle and argument (string) or item handles and arguments (array of strings). + * @param string|string[] $handles Item handle (string) or item handles (array of strings). */ public function enqueue( $handles ) { foreach ( (array) $handles as $handle ) { @@ -313,7 +320,7 @@ class WP_Dependencies { * @since 2.1.0 * @since 2.6.0 Moved from `WP_Scripts`. * - * @param string|string[] $handles Item handle and argument (string) or item handles and arguments (array of strings). + * @param string|string[] $handles Item handle (string) or item handles (array of strings). */ public function dequeue( $handles ) { foreach ( (array) $handles as $handle ) { @@ -358,7 +365,7 @@ class WP_Dependencies { * @since 2.6.0 Moved from `WP_Scripts`. * * @param string $handle Name of the item. Should be unique. - * @param string $list Property name of list array. + * @param string $list Optional. Property name of list array. Default 'registered'. * @return bool|_WP_Dependency Found, or object Item data. */ public function query( $handle, $list = 'registered' ) { @@ -393,10 +400,10 @@ class WP_Dependencies { * * @since 2.8.0 * - * @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. - * @return bool Not already in the group or a lower 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 Group level: level (int), no groups (false). + * @return bool Not already in the group or a lower group. */ public function set_group( $handle, $recursion, $group ) { $group = (int) $group; diff --git a/wp-includes/class.wp-scripts.php b/wp-includes/class.wp-scripts.php index 37ad372db9..ff4fc76805 100644 --- a/wp-includes/class.wp-scripts.php +++ b/wp-includes/class.wp-scripts.php @@ -175,10 +175,11 @@ class WP_Scripts extends WP_Dependencies { * @since 2.1.0 * @since 2.8.0 Added the `$group` parameter. * - * @param mixed $handles Optional. Scripts to be printed. (void) prints queue, (string) prints - * that script, (array of strings) prints those scripts. Default false. - * @param int|false $group Optional. If scripts were queued in groups prints this group number. - * Default false. + * @param string|string[]|false $handles Optional. Scripts to be printed: queue (false), + * single script (string), or multiple scripts (array of strings). + * Default false. + * @param int|false $group Optional. Group level: level (int), no groups (false). + * Default false. * @return string[] Handles of scripts that have been printed. */ public function print_scripts( $handles = false, $group = false ) { @@ -195,9 +196,10 @@ class WP_Scripts extends WP_Dependencies { * @see print_extra_script() * * @param string $handle The script's registered handle. - * @param bool $echo Optional. Whether to echo the extra script instead of just returning it. - * Default true. - * @return bool|string|void Void if no data exists, extra scripts if `$echo` is true, true otherwise. + * @param bool $echo Optional. Whether to echo the extra script + * instead of just returning it. Default true. + * @return bool|string|void Void if no data exists, extra scripts if `$echo` is true, + * true otherwise. */ public function print_scripts_l10n( $handle, $echo = true ) { _deprecated_function( __FUNCTION__, '3.3.0', 'WP_Scripts::print_extra_script()' ); @@ -210,9 +212,10 @@ class WP_Scripts extends WP_Dependencies { * @since 3.3.0 * * @param string $handle The script's registered handle. - * @param bool $echo Optional. Whether to echo the extra script instead of just returning it. - * Default true. - * @return bool|string|void Void if no data exists, extra scripts if `$echo` is true, true otherwise. + * @param bool $echo Optional. Whether to echo the extra script + * instead of just returning it. Default true. + * @return bool|string|void Void if no data exists, extra scripts if `$echo` is true, + * true otherwise. */ public function print_extra_script( $handle, $echo = true ) { $output = $this->get_data( $handle, 'data' ); @@ -251,7 +254,8 @@ class WP_Scripts extends WP_Dependencies { * @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. + * @param int|false $group Optional. Group level: level (int), no groups (false). + * Default false. * @return bool True on success, false on failure. */ public function do_item( $handle, $group = false ) { @@ -409,10 +413,11 @@ class WP_Scripts extends WP_Dependencies { * * @since 4.5.0 * - * @param string $handle Name of the script to add the inline script to. Must be lowercase. + * @param string $handle Name of the script to add the inline script to. + * Must be lowercase. * @param string $data String containing the javascript to be added. - * @param string $position Optional. Whether to add the inline script before the handle - * or after. Default 'after'. + * @param string $position Optional. Whether to add the inline script + * before the handle or after. Default 'after'. * @return bool True on success, false on failure. */ public function add_inline_script( $handle, $data, $position = 'after' ) { @@ -435,11 +440,12 @@ class WP_Scripts extends WP_Dependencies { * * @since 4.5.0 * - * @param string $handle Name of the script to add the inline script to. Must be lowercase. - * @param string $position Optional. Whether to add the inline script before the handle - * or after. Default 'after'. - * @param bool $echo Optional. Whether to echo the script instead of just returning it. - * Default true. + * @param string $handle Name of the script to add the inline script to. + * Must be lowercase. + * @param string $position Optional. Whether to add the inline script + * before the handle or after. Default 'after'. + * @param bool $echo Optional. Whether to echo the script + * instead of just returning it. Default true. * @return string|false Script on success, false otherwise. */ public function print_inline_script( $handle, $position = 'after', $echo = true ) { @@ -510,8 +516,9 @@ class WP_Scripts extends WP_Dependencies { * * @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 + * @param int|false $group Optional. Group level: level (int), no groups (false). + * Default false. + * @return bool Not already in the group or a lower group. */ public function set_group( $handle, $recursion, $group = false ) { if ( isset( $this->registered[ $handle ]->args ) && $this->registered[ $handle ]->args === 1 ) { @@ -558,9 +565,10 @@ class WP_Scripts extends WP_Dependencies { * * @since 5.0.0 * - * @param string $handle Name of the script to add the inline script to. Must be lowercase. - * @param bool $echo Optional. Whether to echo the script instead of just returning it. - * Default true. + * @param string $handle Name of the script to add the inline script to. + * Must be lowercase. + * @param bool $echo Optional. Whether to echo the script + * instead of just returning it. Default true. * @return string|false Script on success, false otherwise. */ public function print_translations( $handle, $echo = true ) { @@ -600,9 +608,11 @@ JS; * * @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. + * @param string|string[] $handles Item handle (string) or item handles (array of strings). + * @param bool $recursion Optional. Internal flag that function is calling itself. + * Default false. + * @param int|false $group Optional. Group level: level (int), no groups (false). + * Default false. * @return bool True on success, false on failure. */ public function all_deps( $handles, $recursion = false, $group = false ) { diff --git a/wp-includes/class.wp-styles.php b/wp-includes/class.wp-styles.php index 5d89154f89..98232e6f11 100644 --- a/wp-includes/class.wp-styles.php +++ b/wp-includes/class.wp-styles.php @@ -322,9 +322,10 @@ class WP_Styles extends WP_Dependencies { * @since 3.3.0 * * @param string $handle The style's registered handle. - * @param bool $echo Optional. Whether to echo the inline style instead of just returning it. - * Default true. - * @return string|bool False if no data exists, inline styles if `$echo` is true, true otherwise. + * @param bool $echo Optional. Whether to echo the inline style + * instead of just returning it. Default true. + * @return string|bool False if no data exists, inline styles if `$echo` is true, + * true otherwise. */ public function print_inline_style( $handle, $echo = true ) { $output = $this->get_data( $handle, 'after' ); @@ -356,9 +357,11 @@ class WP_Styles extends WP_Dependencies { * * @see WP_Dependencies::all_deps() * - * @param string|string[] $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. + * @param string|string[] $handles Item handle (string) or item handles (array of strings). + * @param bool $recursion Optional. Internal flag that function is calling itself. + * Default false. + * @param int|false $group Optional. Group level: level (int), no groups (false). + * Default false. * @return bool True on success, false on failure. */ public function all_deps( $handles, $recursion = false, $group = false ) { @@ -381,8 +384,8 @@ class WP_Styles extends WP_Dependencies { * * @since 2.6.0 * - * @param string $src The source of the enqueued style. - * @param string $ver The version of the enqueued style. + * @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. */ diff --git a/wp-includes/l10n.php b/wp-includes/l10n.php index 9f211d4dc6..77099ffe6a 100644 --- a/wp-includes/l10n.php +++ b/wp-includes/l10n.php @@ -926,7 +926,6 @@ function load_child_theme_textdomain( $domain, $path = false ) { * @param string $handle Name of the script to register a translation domain to. * @param string $domain Optional. Text domain. Default 'default'. * @param string $path Optional. The full file path to the directory containing translation files. - * * @return string|false False if the script textdomain could not be loaded, the translated strings * in JSON encoding otherwise. */ diff --git a/wp-includes/version.php b/wp-includes/version.php index 9d50ddad74..abbf5eda59 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.4-alpha-47169'; +$wp_version = '5.4-alpha-47170'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.