From b20dc7aaafa198258ff1e92ba773278d4919fd27 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Mon, 5 Mar 2018 21:49:53 +0000 Subject: [PATCH] Docs: Standardise and correct documentation relating to parameters which accept plugin names. See #42505 git-svn-id: https://develop.svn.wordpress.org/trunk@42787 602fd350-edb4-49c9-b593-d223f7449a82 --- .../includes/class-plugin-installer-skin.php | 2 +- .../includes/class-plugin-upgrader-skin.php | 2 +- .../includes/class-plugin-upgrader.php | 11 +++-- .../includes/class-wp-plugins-list-table.php | 8 ++-- src/wp-admin/includes/class-wp-upgrader.php | 2 +- src/wp-admin/includes/file.php | 6 +-- src/wp-admin/includes/plugin.php | 44 +++++++++---------- src/wp-includes/functions.php | 4 +- src/wp-includes/load.php | 6 +-- 9 files changed, 42 insertions(+), 43 deletions(-) diff --git a/src/wp-admin/includes/class-plugin-installer-skin.php b/src/wp-admin/includes/class-plugin-installer-skin.php index 300d6684d9..737837f2b5 100644 --- a/src/wp-admin/includes/class-plugin-installer-skin.php +++ b/src/wp-admin/includes/class-plugin-installer-skin.php @@ -93,7 +93,7 @@ class Plugin_Installer_Skin extends WP_Upgrader_Skin { * @param object $api Object containing WordPress.org API plugin data. Empty * for non-API installs, such as when a plugin is installed * via upload. - * @param string $plugin_file Path to the plugin file. + * @param string $plugin_file Path to the plugin file relative to the plugins directory. */ $install_actions = apply_filters( 'install_plugin_complete_actions', $install_actions, $this->api, $plugin_file ); diff --git a/src/wp-admin/includes/class-plugin-upgrader-skin.php b/src/wp-admin/includes/class-plugin-upgrader-skin.php index 036166a2b0..0e24da4a1d 100644 --- a/src/wp-admin/includes/class-plugin-upgrader-skin.php +++ b/src/wp-admin/includes/class-plugin-upgrader-skin.php @@ -65,7 +65,7 @@ class Plugin_Upgrader_Skin extends WP_Upgrader_Skin { * @since 2.7.0 * * @param array $update_actions Array of plugin action links. - * @param string $plugin Path to the plugin file. + * @param string $plugin Path to the plugin file relative to the plugins directory. */ $update_actions = apply_filters( 'update_plugin_complete_actions', $update_actions, $this->plugin ); diff --git a/src/wp-admin/includes/class-plugin-upgrader.php b/src/wp-admin/includes/class-plugin-upgrader.php index fb5c1eb8c9..bd00b7283f 100644 --- a/src/wp-admin/includes/class-plugin-upgrader.php +++ b/src/wp-admin/includes/class-plugin-upgrader.php @@ -135,7 +135,7 @@ class Plugin_Upgrader extends WP_Upgrader { * @since 2.8.0 * @since 3.7.0 The `$args` parameter was added, making clearing the plugin update cache optional. * - * @param string $plugin The basename path to the main plugin file. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @param array $args { * Optional. Other arguments for upgrading a plugin package. Default empty array. * @@ -209,12 +209,11 @@ class Plugin_Upgrader extends WP_Upgrader { * @since 2.8.0 * @since 3.7.0 The `$args` parameter was added, making clearing the plugin update cache optional. * - * @param array $plugins Array of the basename paths of the plugins' main files. - * @param array $args { - * Optional. Other arguments for upgrading several plugins at once. Default empty array. + * @param string[] $plugins Array of paths to plugin files relative to the plugins directory. + * @param array $args { + * Optional. Other arguments for upgrading several plugins at once. * - * @type bool $clear_update_cache Whether to clear the plugin updates cache if successful. - * Default true. + * @type bool $clear_update_cache Whether to clear the plugin updates cache if successful. Default true. * } * @return array|false An array of results indexed by plugin file, or false if unable to connect to the filesystem. */ diff --git a/src/wp-admin/includes/class-wp-plugins-list-table.php b/src/wp-admin/includes/class-wp-plugins-list-table.php index 4ae764547a..959c4e96ab 100644 --- a/src/wp-admin/includes/class-wp-plugins-list-table.php +++ b/src/wp-admin/includes/class-wp-plugins-list-table.php @@ -827,7 +827,7 @@ class WP_Plugins_List_Table extends WP_List_Table { * @param array $plugin_meta An array of the plugin's metadata, * including the version, author, * author URI, and plugin URI. - * @param string $plugin_file Path to the plugin file, relative to the plugins directory. + * @param string $plugin_file Path to the plugin file relative to the plugins directory. * @param array $plugin_data An array of plugin data. * @param string $status Status of the plugin. Defaults are 'All', 'Active', * 'Inactive', 'Recently Activated', 'Upgrade', 'Must-Use', @@ -849,7 +849,7 @@ class WP_Plugins_List_Table extends WP_List_Table { * @since 3.1.0 * * @param string $column_name Name of the column. - * @param string $plugin_file Path to the plugin file. + * @param string $plugin_file Path to the plugin file relative to the plugins directory. * @param array $plugin_data An array of plugin data. */ do_action( 'manage_plugins_custom_column', $column_name, $plugin_file, $plugin_data ); @@ -865,7 +865,7 @@ class WP_Plugins_List_Table extends WP_List_Table { * * @since 2.3.0 * - * @param string $plugin_file Path to the plugin file, relative to the plugins directory. + * @param string $plugin_file Path to the plugin file relative to the plugins directory. * @param array $plugin_data An array of plugin data. * @param string $status Status of the plugin. Defaults are 'All', 'Active', * 'Inactive', 'Recently Activated', 'Upgrade', 'Must-Use', @@ -881,7 +881,7 @@ class WP_Plugins_List_Table extends WP_List_Table { * * @since 2.7.0 * - * @param string $plugin_file Path to the plugin file, relative to the plugins directory. + * @param string $plugin_file Path to the plugin file relative to the plugins directory. * @param array $plugin_data An array of plugin data. * @param string $status Status of the plugin. Defaults are 'All', 'Active', * 'Inactive', 'Recently Activated', 'Upgrade', 'Must-Use', diff --git a/src/wp-admin/includes/class-wp-upgrader.php b/src/wp-admin/includes/class-wp-upgrader.php index a8425b99a8..d8433b4516 100644 --- a/src/wp-admin/includes/class-wp-upgrader.php +++ b/src/wp-admin/includes/class-wp-upgrader.php @@ -691,7 +691,7 @@ class WP_Upgrader { * @type string $action Type of action. Default 'update'. * @type string $type Type of update process. Accepts 'plugin', 'theme', or 'core'. * @type bool $bulk Whether the update process is a bulk update. Default true. - * @type string $plugin The base plugin path from the plugins directory. + * @type string $plugin Path to the plugin file relative to the plugins directory. * @type string $theme The stylesheet or template name of the theme. * @type string $language_update_type The language pack update type. Accepts 'plugin', 'theme', * or 'core'. diff --git a/src/wp-admin/includes/file.php b/src/wp-admin/includes/file.php index 0d35ce45c2..2b8a4fac1e 100644 --- a/src/wp-admin/includes/file.php +++ b/src/wp-admin/includes/file.php @@ -175,7 +175,7 @@ function list_files( $folder = '', $levels = 100, $exclusions = array() ) { * * @since 4.9.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @return string[] Array of editable file extensions. */ function wp_get_plugin_file_editable_extensions( $plugin ) { @@ -222,7 +222,7 @@ function wp_get_plugin_file_editable_extensions( $plugin ) { * @since 4.9.0 Added the `$plugin` parameter. * * @param string[] $editable_extensions An array of editable plugin file extensions. - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. */ $editable_extensions = (array) apply_filters( 'editable_extensions', $editable_extensions, $plugin ); @@ -342,7 +342,7 @@ function wp_print_file_editor_templates() { * coming straight from `$_POST` and are not validated or sanitized in any way. * * @type string $file Relative path to file. - * @type string $plugin Plugin being edited. + * @type string $plugin Path to the plugin file relative to the plugins directory. * @type string $theme Theme being edited. * @type string $newcontent New content for the file. * @type string $nonce Nonce. diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php index 84bb3d82a4..d2ed56d76b 100644 --- a/src/wp-admin/includes/plugin.php +++ b/src/wp-admin/includes/plugin.php @@ -47,7 +47,7 @@ * * @since 1.5.0 * - * @param string $plugin_file Path to the main plugin file. + * @param string $plugin_file Absolute path to the main plugin file. * @param bool $markup Optional. If the returned data should have HTML markup applied. * Default true. * @param bool $translate Optional. If the returned data should be translated. Default true. @@ -194,7 +194,7 @@ function _get_plugin_data_markup_translate( $plugin_file, $plugin_data, $markup * * @since 2.8.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @return array List of files relative to the plugin root. */ function get_plugin_files( $plugin ) { @@ -470,7 +470,7 @@ function _get_dropins() { * * @since 2.5.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @return bool True, if in the active plugins list. False, not in the list. */ function is_plugin_active( $plugin ) { @@ -489,7 +489,7 @@ function is_plugin_active( $plugin ) { * @since 3.1.0 * @see is_plugin_active() * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @return bool True if inactive. False if active. */ function is_plugin_inactive( $plugin ) { @@ -510,7 +510,7 @@ function is_plugin_inactive( $plugin ) { * * @since 3.0.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @return bool True if active for the network, otherwise false. */ function is_plugin_active_for_network( $plugin ) { @@ -535,7 +535,7 @@ function is_plugin_active_for_network( $plugin ) { * * @since 3.0.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @return bool True if plugin is network only, false otherwise. */ function is_network_only_plugin( $plugin ) { @@ -566,7 +566,7 @@ function is_network_only_plugin( $plugin ) { * * @since 2.5.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @param string $redirect Optional. URL to redirect to. * @param bool $network_wide Optional. Whether to enable the plugin for all sites in the network * or just the current site. Multisite only. Default false. @@ -608,7 +608,7 @@ function activate_plugin( $plugin, $redirect = '', $network_wide = false, $silen * * @since 2.9.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @param bool $network_wide Whether to enable the plugin for all sites in the network * or just the current site. Multisite only. Default is false. */ @@ -650,7 +650,7 @@ function activate_plugin( $plugin, $redirect = '', $network_wide = false, $silen * * @since 2.9.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @param bool $network_wide Whether to enable the plugin for all sites in the network * or just the current site. Multisite only. Default is false. */ @@ -704,7 +704,7 @@ function deactivate_plugins( $plugins, $silent = false, $network_wide = null ) { * * @since 2.9.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @param bool $network_deactivating Whether the plugin is deactivated for all sites in the network * or just the current site. Multisite only. Default is false. */ @@ -752,7 +752,7 @@ function deactivate_plugins( $plugins, $silent = false, $network_wide = null ) { * * @since 2.9.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @param bool $network_deactivating Whether the plugin is deactivated for all sites in the network. * or just the current site. Multisite only. Default false. */ @@ -814,10 +814,10 @@ function activate_plugins( $plugins, $redirect = '', $network_wide = false, $sil * * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass. * - * @param array $plugins List of plugins to delete. - * @param string $deprecated Deprecated. - * @return bool|null|WP_Error True on success, false if `$plugins` is empty, WP_Error on failure. - * Null if filesystem credentials are required to proceed. + * @param string[] $plugins List of plugin paths to delete, relative to the plugins directory. + * @param string $deprecated Not used. + * @return bool|null|WP_Error True on success, false if `$plugins` is empty, `WP_Error` on failure. + * `null` if filesystem credentials are required to proceed. */ function delete_plugins( $plugins, $deprecated = '' ) { global $wp_filesystem; @@ -892,7 +892,7 @@ function delete_plugins( $plugins, $deprecated = '' ) { * * @since 4.4.0 * - * @param string $plugin_file Plugin file name. + * @param string $plugin_file Path to the plugin file relative to the plugins directory. */ do_action( 'delete_plugin', $plugin_file ); @@ -910,7 +910,7 @@ function delete_plugins( $plugins, $deprecated = '' ) { * * @since 4.4.0 * - * @param string $plugin_file Plugin file name. + * @param string $plugin_file Path to the plugin file relative to the plugins directory. * @param bool $deleted Whether the plugin deletion was successful. */ do_action( 'deleted_plugin', $plugin_file, $deleted ); @@ -1005,7 +1005,7 @@ function validate_active_plugins() { * * @since 2.5.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @return WP_Error|int 0 on success, WP_Error on failure. */ function validate_plugin( $plugin ) { @@ -1028,7 +1028,7 @@ function validate_plugin( $plugin ) { * * @since 2.7.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @return bool Whether plugin can be uninstalled. */ function is_uninstallable_plugin( $plugin ) { @@ -1049,7 +1049,7 @@ function is_uninstallable_plugin( $plugin ) { * * @since 2.7.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @return true True if a plugin's uninstall.php file has been found and included. */ function uninstall_plugin( $plugin ) { @@ -1062,7 +1062,7 @@ function uninstall_plugin( $plugin ) { * * @since 4.5.0 * - * @param string $plugin Path to the main plugin file from plugins directory. + * @param string $plugin Path to the plugin file relative to the plugins directory. * @param array $uninstallable_plugins Uninstallable plugins. */ do_action( 'pre_uninstall_plugin', $plugin, $uninstallable_plugins ); @@ -2008,7 +2008,7 @@ function wp_clean_plugins_cache( $clear_update_cache = true ) { * @since 3.0.0 * @since 4.4.0 Function was moved into the `wp-admin/includes/plugin.php` file. * - * @param string $plugin Plugin file to load. + * @param string $plugin Path to the plugin file relative to the plugins directory. */ function plugin_sandbox_scrape( $plugin ) { wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $plugin ); diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php index 53a2204376..f3afe60a9c 100644 --- a/src/wp-includes/functions.php +++ b/src/wp-includes/functions.php @@ -5070,8 +5070,8 @@ function wp_scheduled_delete() { * * @since 2.9.0 * - * @param string $file Path to the file. - * @param array $default_headers List of headers, in the format array('HeaderKey' => 'Header Name'). + * @param string $file Absolute path to the file. + * @param array $default_headers List of headers, in the format `array('HeaderKey' => 'Header Name')`. * @param string $context Optional. If specified adds filter hook {@see 'extra_$context_headers'}. * Default empty. * @return array Array of file headers in `HeaderKey => Header Value` format. diff --git a/src/wp-includes/load.php b/src/wp-includes/load.php index 9c7053eb14..99112f0ce2 100644 --- a/src/wp-includes/load.php +++ b/src/wp-includes/load.php @@ -653,14 +653,14 @@ function wp_get_mu_plugins() { * * While upgrading or installing WordPress, no plugins are returned. * - * The default directory is wp-content/plugins. To change the default + * The default directory is `wp-content/plugins`. To change the default * directory manually, define `WP_PLUGIN_DIR` and `WP_PLUGIN_URL` - * in wp-config.php. + * in `wp-config.php`. * * @since 3.0.0 * @access private * - * @return array Files. + * @return string[] $plugin_file Array of paths to plugin files relative to the plugins directory. */ function wp_get_active_and_valid_plugins() { $plugins = array();