WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Sergey Biryukov 2020-02-03 00:19:03 +00:00
parent 982a6453c9
commit c289bb59ac
6 changed files with 79 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
wp-includes/class-wp-dependency.php
View File

@ -123,7 +123,6 @@ class _WP_Dependency {
* *
* @param string $domain The translation textdomain. * @param string $domain The translation textdomain.
* @param string $path Optional. The full file path to the directory containing translation files. * @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. * @return bool False if $domain is not a string, true otherwise.
*/ */
public function set_translations( $domain, $path = null ) { public function set_translations( $domain, $path = null ) {

53
wp-includes/class.wp-dependencies.php
View File

@ -83,8 +83,10 @@ class WP_Dependencies {
* @since 2.6.0 * @since 2.6.0
* @since 2.8.0 Added the `$group` parameter. * @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 string|string[]|false $handles Optional. Items to be processed: queue (false),
* @param int|false $group Optional. Group level: level (int), no groups (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. * @return string[] Array of handles of items that have been processed.
*/ */
public function do_items( $handles = false, $group = false ) { 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.6.0 Moved from `WP_Scripts`.
* @since 2.8.0 Added the `$group` parameter. * @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 string|string[] $handles Item handle (string) or item handles (array of strings).
* @param bool $recursion Internal flag that function is calling itself. * @param bool $recursion Optional. Internal flag that function is calling itself.
* @param int|false $group 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. * @return bool True on success, false on failure.
*/ */
public function all_deps( $handles, $recursion = false, $group = false ) { public function all_deps( $handles, $recursion = false, $group = false ) {
@ -203,14 +207,18 @@ class WP_Dependencies {
* @since 2.6.0 Moved from `WP_Scripts`. * @since 2.6.0 Moved from `WP_Scripts`.
* *
* @param string $handle Name of the item. Should be unique. * @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. * @param string|bool $src Full URL of the item, or path of the item relative
* If source is set to false, item is an alias of other items it depends on. * to the WordPress root directory. If source is set to false,
* @param string[] $deps Optional. An array of registered item handles this item depends on. Default empty array. * item is an alias of other items it depends on.
* @param string|bool|null $ver Optional. String specifying item version number, if it has one, which is added to the URL * @param string[] $deps Optional. An array of registered item handles this item depends on.
* as a query string for cache busting purposes. If version is set to false, a version * Default empty array.
* number is automatically added equal to current installed WordPress version. * @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. * 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. * @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 ) { 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 $handle Name of the item. Should be unique.
* @param string $key The data key. * @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. * @return bool True on success, false on failure.
*/ */
public function add_data( $handle, $key, $value ) { 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 $handle Name of the item. Should be unique.
* @param string $key The data key. * @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 ) { public function get_data( $handle, $key ) {
if ( ! isset( $this->registered[ $handle ] ) ) { if ( ! isset( $this->registered[ $handle ] ) ) {
@ -270,8 +278,7 @@ class WP_Dependencies {
* @since 2.1.0 * @since 2.1.0
* @since 2.6.0 Moved from `WP_Scripts`. * @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).
* @return void
*/ */
public function remove( $handles ) { public function remove( $handles ) {
foreach ( (array) $handles as $handle ) { foreach ( (array) $handles as $handle ) {
@ -290,7 +297,7 @@ class WP_Dependencies {
* @since 2.1.0 * @since 2.1.0
* @since 2.6.0 Moved from `WP_Scripts`. * @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 ) { public function enqueue( $handles ) {
foreach ( (array) $handles as $handle ) { foreach ( (array) $handles as $handle ) {
@ -313,7 +320,7 @@ class WP_Dependencies {
* @since 2.1.0 * @since 2.1.0
* @since 2.6.0 Moved from `WP_Scripts`. * @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 ) { public function dequeue( $handles ) {
foreach ( (array) $handles as $handle ) { foreach ( (array) $handles as $handle ) {
@ -358,7 +365,7 @@ class WP_Dependencies {
* @since 2.6.0 Moved from `WP_Scripts`. * @since 2.6.0 Moved from `WP_Scripts`.
* *
* @param string $handle Name of the item. Should be unique. * @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. * @return bool|_WP_Dependency Found, or object Item data.
*/ */
public function query( $handle, $list = 'registered' ) { public function query( $handle, $list = 'registered' ) {
@ -393,10 +400,10 @@ class WP_Dependencies {
* *
* @since 2.8.0 * @since 2.8.0
* *
* @param string $handle Name of the item. Should be unique. * @param string $handle Name of the item. Should be unique.
* @param bool $recursion Internal flag that calling function was called recursively. * @param bool $recursion Internal flag that calling function was called recursively.
* @param mixed $group Group level. * @param int|false $group Group level: level (int), no groups (false).
* @return bool Not already in the group or a lower group * @return bool Not already in the group or a lower group.
*/ */
public function set_group( $handle, $recursion, $group ) { public function set_group( $handle, $recursion, $group ) {
$group = (int) $group; $group = (int) $group;

64
wp-includes/class.wp-scripts.php
View File

@ -175,10 +175,11 @@ class WP_Scripts extends WP_Dependencies {
* @since 2.1.0 * @since 2.1.0
* @since 2.8.0 Added the `$group` parameter. * @since 2.8.0 Added the `$group` parameter.
* *
* @param mixed $handles Optional. Scripts to be printed. (void) prints queue, (string) prints * @param string|string[]|false $handles Optional. Scripts to be printed: queue (false),
* that script, (array of strings) prints those scripts. Default false. * single script (string), or multiple scripts (array of strings).
* @param int|false $group Optional. If scripts were queued in groups prints this group number. * Default false.
* 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. * @return string[] Handles of scripts that have been printed.
*/ */
public function print_scripts( $handles = false, $group = false ) { public function print_scripts( $handles = false, $group = false ) {
@ -195,9 +196,10 @@ class WP_Scripts extends WP_Dependencies {
* @see print_extra_script() * @see print_extra_script()
* *
* @param string $handle The script's registered handle. * @param string $handle The script's registered handle.
* @param bool $echo Optional. Whether to echo the extra script instead of just returning it. * @param bool $echo Optional. Whether to echo the extra script
* Default true. * instead of just returning it. Default true.
* @return bool|string|void Void if no data exists, extra scripts if `$echo` is true, true otherwise. * @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 ) { public function print_scripts_l10n( $handle, $echo = true ) {
_deprecated_function( __FUNCTION__, '3.3.0', 'WP_Scripts::print_extra_script()' ); _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 * @since 3.3.0
* *
* @param string $handle The script's registered handle. * @param string $handle The script's registered handle.
* @param bool $echo Optional. Whether to echo the extra script instead of just returning it. * @param bool $echo Optional. Whether to echo the extra script
* Default true. * instead of just returning it. Default true.
* @return bool|string|void Void if no data exists, extra scripts if `$echo` is true, true otherwise. * @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 ) { public function print_extra_script( $handle, $echo = true ) {
$output = $this->get_data( $handle, 'data' ); $output = $this->get_data( $handle, 'data' );
@ -251,7 +254,8 @@ class WP_Scripts extends WP_Dependencies {
* @see WP_Dependencies::do_item() * @see WP_Dependencies::do_item()
* *
* @param string $handle The script's registered handle. * @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. * @return bool True on success, false on failure.
*/ */
public function do_item( $handle, $group = false ) { public function do_item( $handle, $group = false ) {
@ -409,10 +413,11 @@ class WP_Scripts extends WP_Dependencies {
* *
* @since 4.5.0 * @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 $data String containing the javascript to be added.
* @param string $position Optional. Whether to add the inline script before the handle * @param string $position Optional. Whether to add the inline script
* or after. Default 'after'. * before the handle or after. Default 'after'.
* @return bool True on success, false on failure. * @return bool True on success, false on failure.
*/ */
public function add_inline_script( $handle, $data, $position = 'after' ) { public function add_inline_script( $handle, $data, $position = 'after' ) {
@ -435,11 +440,12 @@ class WP_Scripts extends WP_Dependencies {
* *
* @since 4.5.0 * @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.
* @param string $position Optional. Whether to add the inline script before the handle * Must be lowercase.
* or after. Default 'after'. * @param string $position Optional. Whether to add the inline script
* @param bool $echo Optional. Whether to echo the script instead of just returning it. * before the handle or after. Default 'after'.
* Default true. * @param bool $echo Optional. Whether to echo the script
* instead of just returning it. Default true.
* @return string|false Script on success, false otherwise. * @return string|false Script on success, false otherwise.
*/ */
public function print_inline_script( $handle, $position = 'after', $echo = true ) { 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 string $handle Name of the item. Should be unique.
* @param bool $recursion Internal flag that calling function was called recursively. * @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. * @param int|false $group Optional. Group level: level (int), no groups (false).
* @return bool Not already in the group or a lower group * Default false.
* @return bool Not already in the group or a lower group.
*/ */
public function set_group( $handle, $recursion, $group = false ) { public function set_group( $handle, $recursion, $group = false ) {
if ( isset( $this->registered[ $handle ]->args ) && $this->registered[ $handle ]->args === 1 ) { 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 * @since 5.0.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.
* @param bool $echo Optional. Whether to echo the script instead of just returning it. * Must be lowercase.
* Default true. * @param bool $echo Optional. Whether to echo the script
* instead of just returning it. Default true.
* @return string|false Script on success, false otherwise. * @return string|false Script on success, false otherwise.
*/ */
public function print_translations( $handle, $echo = true ) { public function print_translations( $handle, $echo = true ) {
@ -600,9 +608,11 @@ JS;
* *
* @see WP_Dependencies::all_deps() * @see WP_Dependencies::all_deps()
* *
* @param mixed $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).
* @param bool $recursion Internal flag that function is calling itself. * @param bool $recursion Optional. Internal flag that function is calling itself.
* @param int|false $group Optional. Group level: (int) level, (false) no groups. Default false. * Default false.
* @param int|false $group Optional. Group level: level (int), no groups (false).
* Default false.
* @return bool True on success, false on failure. * @return bool True on success, false on failure.
*/ */
public function all_deps( $handles, $recursion = false, $group = false ) { public function all_deps( $handles, $recursion = false, $group = false ) {

19
wp-includes/class.wp-styles.php
View File

@ -322,9 +322,10 @@ class WP_Styles extends WP_Dependencies {
* @since 3.3.0 * @since 3.3.0
* *
* @param string $handle The style's registered handle. * @param string $handle The style's registered handle.
* @param bool $echo Optional. Whether to echo the inline style instead of just returning it. * @param bool $echo Optional. Whether to echo the inline style
* Default true. * instead of just returning it. Default true.
* @return string|bool False if no data exists, inline styles if `$echo` is true, true otherwise. * @return string|bool False if no data exists, inline styles if `$echo` is true,
* true otherwise.
*/ */
public function print_inline_style( $handle, $echo = true ) { public function print_inline_style( $handle, $echo = true ) {
$output = $this->get_data( $handle, 'after' ); $output = $this->get_data( $handle, 'after' );
@ -356,9 +357,11 @@ class WP_Styles extends WP_Dependencies {
* *
* @see WP_Dependencies::all_deps() * @see WP_Dependencies::all_deps()
* *
* @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).
* @param bool $recursion Internal flag that function is calling itself. * @param bool $recursion Optional. Internal flag that function is calling itself.
* @param int|false $group 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. * @return bool True on success, false on failure.
*/ */
public function all_deps( $handles, $recursion = false, $group = false ) { public function all_deps( $handles, $recursion = false, $group = false ) {
@ -381,8 +384,8 @@ class WP_Styles extends WP_Dependencies {
* *
* @since 2.6.0 * @since 2.6.0
* *
* @param string $src The source of the enqueued style. * @param string $src The source of the enqueued style.
* @param string $ver The version of the enqueued style. * @param string $ver The version of the enqueued style.
* @param string $handle The style's registered handle. * @param string $handle The style's registered handle.
* @return string Style's fully-qualified URL. * @return string Style's fully-qualified URL.
*/ */

1
wp-includes/l10n.php
View File

@ -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 $handle Name of the script to register a translation domain to.
* @param string $domain Optional. Text domain. Default 'default'. * @param string $domain Optional. Text domain. Default 'default'.
* @param string $path Optional. The full file path to the directory containing translation files. * @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 * @return string|false False if the script textdomain could not be loaded, the translated strings
* in JSON encoding otherwise. * in JSON encoding otherwise.
*/ */

2
wp-includes/version.php
View File

@ -13,7 +13,7 @@
* *
* @global string $wp_version * @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. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.