From b31b69ab494a8abb741c0d63eb0e0eb4d00807c3 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Mon, 5 Oct 2020 13:42:04 +0000
Subject: [PATCH] Docs: Add missing `@return` tag to
 `Language_Pack_Upgrader::check_package()`.

Synchronize documentation of the `::check_package()` method between `Plugin_Upgrader`, `Theme_Upgrader`, and `Language_Pack_Upgrader`.

Props ankitmaru, mukesh27, desrosj.
Fixes #51448.

git-svn-id: https://develop.svn.wordpress.org/trunk@49091 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/class-language-pack-upgrader.php | 9 +++++----
 src/wp-admin/includes/class-plugin-upgrader.php        | 8 +++-----
 src/wp-admin/includes/class-theme-upgrader.php         | 8 +++-----
 3 files changed, 11 insertions(+), 14 deletions(-)

diff --git a/src/wp-admin/includes/class-language-pack-upgrader.php b/src/wp-admin/includes/class-language-pack-upgrader.php
index e88db55848..2ac6e76329 100644
--- a/src/wp-admin/includes/class-language-pack-upgrader.php
+++ b/src/wp-admin/includes/class-language-pack-upgrader.php
@@ -309,17 +309,18 @@ class Language_Pack_Upgrader extends WP_Upgrader {
 	}
 
 	/**
-	 * Check the package source to make sure there are .mo and .po files.
+	 * Checks that the package source contains .mo and .po files.
 	 *
 	 * Hooked to the {@see 'upgrader_source_selection'} filter by
 	 * Language_Pack_Upgrader::bulk_upgrade().
 	 *
 	 * @since 3.7.0
 	 *
-	 * @global WP_Filesystem_Base $wp_filesystem Subclass
+	 * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass.
 	 *
-	 * @param string|WP_Error $source
-	 * @param string          $remote_source
+	 * @param string|WP_Error $source        The path to the downloaded package source.
+	 * @param string          $remote_source Remote file source location.
+	 * @return string|WP_Error The source as passed, or a WP_Error object on failure.
 	 */
 	public function check_package( $source, $remote_source ) {
 		global $wp_filesystem;
diff --git a/src/wp-admin/includes/class-plugin-upgrader.php b/src/wp-admin/includes/class-plugin-upgrader.php
index c750399277..b171f9228b 100644
--- a/src/wp-admin/includes/class-plugin-upgrader.php
+++ b/src/wp-admin/includes/class-plugin-upgrader.php
@@ -398,10 +398,9 @@ class Plugin_Upgrader extends WP_Upgrader {
 	}
 
 	/**
-	 * Check a source package to be sure it contains a plugin.
+	 * Checks that the source package contains a valid plugin.
 	 *
-	 * This function is added to the {@see 'upgrader_source_selection'} filter by
-	 * Plugin_Upgrader::install().
+	 * Hooked to the {@see 'upgrader_source_selection'} filter by Plugin_Upgrader::install().
 	 *
 	 * @since 3.3.0
 	 *
@@ -409,8 +408,7 @@ class Plugin_Upgrader extends WP_Upgrader {
 	 * @global string             $wp_version    The WordPress version string.
 	 *
 	 * @param string $source The path to the downloaded package source.
-	 * @return string|WP_Error The source as passed, or a WP_Error object
-	 *                         if no plugins were found.
+	 * @return string|WP_Error The source as passed, or a WP_Error object on failure.
 	 */
 	public function check_package( $source ) {
 		global $wp_filesystem, $wp_version;
diff --git a/src/wp-admin/includes/class-theme-upgrader.php b/src/wp-admin/includes/class-theme-upgrader.php
index 3c8f2d9abf..229a8115bd 100644
--- a/src/wp-admin/includes/class-theme-upgrader.php
+++ b/src/wp-admin/includes/class-theme-upgrader.php
@@ -510,19 +510,17 @@ class Theme_Upgrader extends WP_Upgrader {
 	}
 
 	/**
-	 * Check that the package source contains a valid theme.
+	 * Checks that the package source contains a valid theme.
 	 *
 	 * Hooked to the {@see 'upgrader_source_selection'} filter by Theme_Upgrader::install().
-	 * It will return an error if the theme doesn't have style.css or index.php
-	 * files.
 	 *
 	 * @since 3.3.0
 	 *
 	 * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass.
 	 * @global string             $wp_version    The WordPress version string.
 	 *
-	 * @param string $source The full path to the package source.
-	 * @return string|WP_Error The source or a WP_Error.
+	 * @param string $source The path to the downloaded package source.
+	 * @return string|WP_Error The source as passed, or a WP_Error object on failure.
 	 */
 	public function check_package( $source ) {
 		global $wp_filesystem, $wp_version;