From 7a7bb0d6b413cdbe1dfdfc46baa424d8f13c98c1 Mon Sep 17 00:00:00 2001
From: Scott Taylor <wonderboymusic@git.wordpress.org>
Date: Mon, 1 Dec 2014 00:12:05 +0000
Subject: [PATCH] Improve various `@param` docs for
 `src/wp-admin/includes/class-wp-filesystem-*.php`.

See #30224.


git-svn-id: https://develop.svn.wordpress.org/trunk@30678 602fd350-edb4-49c9-b593-d223f7449a82
---
 .../includes/class-wp-filesystem-base.php     |  59 ++++----
 .../includes/class-wp-filesystem-direct.php   |  82 ++++++++++-
 .../includes/class-wp-filesystem-ftpext.php   | 135 ++++++++++++++++--
 .../class-wp-filesystem-ftpsockets.php        | 118 ++++++++++++++-
 .../includes/class-wp-filesystem-ssh2.php     | 131 +++++++++++++++--
 5 files changed, 464 insertions(+), 61 deletions(-)

diff --git a/src/wp-admin/includes/class-wp-filesystem-base.php b/src/wp-admin/includes/class-wp-filesystem-base.php
index 4630f710ea..08dfabddd0 100644
--- a/src/wp-admin/includes/class-wp-filesystem-base.php
+++ b/src/wp-admin/includes/class-wp-filesystem-base.php
@@ -469,7 +469,7 @@ class WP_Filesystem_Base {
 	 * Connect filesystem.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @return bool True on success or false on failure (always true for WP_Filesystem_Direct).
 	 */
 	public function connect() {
@@ -480,9 +480,9 @@ class WP_Filesystem_Base {
 	 * Read entire file into a string.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file Name of the file to read.
-	 * @return string|bool Returns the read data or false on failure.
+	 * @return mixed|bool Returns the read data or false on failure.
 	 */
 	public function get_contents( $file ) {
 		return false;
@@ -492,7 +492,7 @@ class WP_Filesystem_Base {
 	 * Read entire file into an array.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file Path to the file.
 	 * @return array|bool the file contents in an array or false on failure.
 	 */
@@ -504,7 +504,7 @@ class WP_Filesystem_Base {
 	 * Write a string to a file.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file     Remote path to the file where to write the data.
 	 * @param string $contents The data to write.
 	 * @param int    $mode     Optional. The file permissions as octal number, usually 0644.
@@ -518,7 +518,7 @@ class WP_Filesystem_Base {
 	 * Get the current working directory.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @return string|bool The current working directory on success, or false on failure.
 	 */
 	public function cwd() {
@@ -529,7 +529,7 @@ class WP_Filesystem_Base {
 	 * Change current directory.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $dir The new current directory.
 	 * @return bool Returns true on success or false on failure.
 	 */
@@ -541,7 +541,7 @@ class WP_Filesystem_Base {
 	 * Change the file group.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file      Path to the file.
 	 * @param mixed  $group     A group name or number.
 	 * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
@@ -555,7 +555,7 @@ class WP_Filesystem_Base {
 	 * Change filesystem permissions.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file      Path to the file.
 	 * @param int    $mode      Optional. The permissions as octal number, usually 0644 for files, 0755 for dirs.
 	 * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
@@ -569,7 +569,7 @@ class WP_Filesystem_Base {
 	 * Get the file owner.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file Path to the file.
 	 * @return string|bool Username of the user or false on error.
 	 */
@@ -581,7 +581,7 @@ class WP_Filesystem_Base {
 	 * Get the file's group.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file Path to the file.
 	 * @return string|bool The group or false on error.
 	 */
@@ -593,7 +593,7 @@ class WP_Filesystem_Base {
 	 * Copy a file.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $source      Path to the source file.
 	 * @param string $destination Path to the destination file.
 	 * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
@@ -610,7 +610,7 @@ class WP_Filesystem_Base {
 	 * Move a file.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $source      Path to the source file.
 	 * @param string $destination Path to the destination file.
 	 * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
@@ -625,7 +625,7 @@ class WP_Filesystem_Base {
 	 * Delete a file or directory.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file      Path to the file.
 	 * @param bool   $recursive Optional. If set True changes file group recursively. Defaults to False.
 	 *                          Default false.
@@ -641,7 +641,7 @@ class WP_Filesystem_Base {
 	 * Check if a file or directory exists.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file Path to file/directory.
 	 * @return bool Whether $file exists or not.
 	 */
@@ -653,7 +653,7 @@ class WP_Filesystem_Base {
 	 * Check if resource is a file.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file File path.
 	 * @return bool Whether $file is a file.
 	 */
@@ -665,7 +665,7 @@ class WP_Filesystem_Base {
 	 * Check if resource is a directory.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $path Directory path.
 	 * @return bool Whether $path is a directory.
 	 */
@@ -677,7 +677,7 @@ class WP_Filesystem_Base {
 	 * Check if a file is readable.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file Path to file.
 	 * @return bool Whether $file is readable.
 	 */
@@ -689,8 +689,7 @@ class WP_Filesystem_Base {
 	 * Check if a file or directory is writable.
 	 *
 	 * @since 2.5.0
-	 *
-	 * @param string $path Path to file/directory.
+	 * @abstract
 	 * @return bool Whether $file is writable.
 	 */
 	public function is_writable( $file ) {
@@ -701,9 +700,9 @@ class WP_Filesystem_Base {
 	 * Gets the file's last access time.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file Path to file.
-	 * @return int Unix timestamp representing last access time.
+	 * @return int|bool Unix timestamp representing last access time.
 	 */
 	public function atime( $file ) {
 		return false;
@@ -713,9 +712,9 @@ class WP_Filesystem_Base {
 	 * Gets the file modification time.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file Path to file.
-	 * @return int Unix timestamp representing modification time.
+	 * @return int|bool Unix timestamp representing modification time.
 	 */
 	public function mtime( $file ) {
 		return false;
@@ -725,9 +724,9 @@ class WP_Filesystem_Base {
 	 * Gets the file size (in bytes).
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file Path to file.
-	 * @return int Size of the file in bytes.
+	 * @return int|bool Size of the file in bytes.
 	 */
 	public function size( $file ) {
 		return false;
@@ -739,7 +738,7 @@ class WP_Filesystem_Base {
 	 * Note: If $file doesn't exist, it will be created.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $file  Path to file.
 	 * @param int    $time  Optional. Modified time to set for file.
 	 *                      Default 0.
@@ -755,7 +754,7 @@ class WP_Filesystem_Base {
 	 * Create a directory.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $path  Path for new directory.
 	 * @param mixed  $chmod Optional. The permissions as octal number, (or False to skip chmod)
 	 *                      Default false.
@@ -773,7 +772,7 @@ class WP_Filesystem_Base {
 	 * Delete a directory.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $path      Path to directory.
 	 * @param bool   $recursive Optional. Whether to recursively remove files/directories.
 	 *                          Default false.
@@ -787,7 +786,7 @@ class WP_Filesystem_Base {
 	 * Get details for files in a directory or a specific file.
 	 *
 	 * @since 2.5.0
-	 *
+	 * @abstract
 	 * @param string $path           Path to directory or file.
 	 * @param bool   $include_hidden Optional. Whether to include details of hidden ("." prefixed) files.
 	 *                               Default true.
diff --git a/src/wp-admin/includes/class-wp-filesystem-direct.php b/src/wp-admin/includes/class-wp-filesystem-direct.php
index a426bd273f..7e23b46b0e 100644
--- a/src/wp-admin/includes/class-wp-filesystem-direct.php
+++ b/src/wp-admin/includes/class-wp-filesystem-direct.php
@@ -200,6 +200,10 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 		return substr( decoct( @fileperms( $file ) ), -3 );
 	}
 
+	/**
+	 * @param string $file
+	 * @return string
+	 */
 	public function group($file) {
 		$gid = @filegroup($file);
 		if ( ! $gid )
@@ -210,6 +214,13 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 		return $grouparray['name'];
 	}
 
+	/**
+	 * @param string $source
+	 * @param string $destination
+	 * @param bool   $overwrite
+	 * @param int    $mode
+	 * @return bool
+	 */
 	public function copy($source, $destination, $overwrite = false, $mode = false) {
 		if ( ! $overwrite && $this->exists($destination) )
 			return false;
@@ -220,6 +231,12 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 		return $rtval;
 	}
 
+	/**
+	 * @param string $source
+	 * @param string $destination
+	 * @param bool $overwrite
+	 * @return bool
+	 */
 	public function move($source, $destination, $overwrite = false) {
 		if ( ! $overwrite && $this->exists($destination) )
 			return false;
@@ -236,6 +253,12 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 		}
 	}
 
+	/**
+	 * @param string $file
+	 * @param bool $recursive
+	 * @param string $type
+	 * @return bool
+	 */
 	public function delete($file, $recursive = false, $type = false) {
 		if ( empty( $file ) ) // Some filesystems report this as /, which can cause non-expected recursive deletion of all files in the filesystem.
 			return false;
@@ -263,39 +286,74 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 
 		return $retval;
 	}
-
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function exists($file) {
 		return @file_exists($file);
 	}
-
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_file($file) {
 		return @is_file($file);
 	}
-
+	/**
+	 * @param string $path
+	 * @return bool
+	 */
 	public function is_dir($path) {
 		return @is_dir($path);
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_readable($file) {
 		return @is_readable($file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_writable($file) {
 		return @is_writable($file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return int
+	 */
 	public function atime($file) {
 		return @fileatime($file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return int
+	 */
 	public function mtime($file) {
 		return @filemtime($file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return int
+	 */
 	public function size($file) {
 		return @filesize($file);
 	}
 
+	/**
+	 * @param string $file
+	 * @param int $time
+	 * @param int $atime
+	 * @return bool
+	 */
 	public function touch($file, $time = 0, $atime = 0) {
 		if ($time == 0)
 			$time = time();
@@ -304,6 +362,13 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 		return @touch($file, $time, $atime);
 	}
 
+	/**
+	 * @param string $path
+	 * @param mixed  $chmod
+	 * @param mixed  $chown
+	 * @param mixed  $chgrp
+	 * @return bool
+	 */
 	public function mkdir($path, $chmod = false, $chown = false, $chgrp = false) {
 		// Safe mode fails with a trailing slash under certain PHP versions.
 		$path = untrailingslashit($path);
@@ -323,10 +388,21 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 		return true;
 	}
 
+	/**
+	 * @param string $path
+	 * @param bool $recursive
+	 * @return type
+	 */
 	public function rmdir($path, $recursive = false) {
 		return $this->delete($path, $recursive);
 	}
 
+	/**
+	 * @param string $path
+	 * @param bool $include_hidden
+	 * @param bool $recursive
+	 * @return bool|array
+	 */
 	public function dirlist($path, $include_hidden = true, $recursive = false) {
 		if ( $this->is_file($path) ) {
 			$limit_file = basename($path);
diff --git a/src/wp-admin/includes/class-wp-filesystem-ftpext.php b/src/wp-admin/includes/class-wp-filesystem-ftpext.php
index 87233d0c9a..a3a5ef6a3f 100644
--- a/src/wp-admin/includes/class-wp-filesystem-ftpext.php
+++ b/src/wp-admin/includes/class-wp-filesystem-ftpext.php
@@ -87,6 +87,10 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 		return true;
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool|string
+	 */
 	public function get_contents( $file ) {
 		$tempfile = wp_tempnam($file);
 		$temp = fopen($tempfile, 'w+');
@@ -108,10 +112,20 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 		return $contents;
 	}
 
+	/**
+	 * @param string $file
+	 * @return array
+	 */
 	public function get_contents_array($file) {
 		return explode("\n", $this->get_contents($file));
 	}
 
+	/**
+	 * @param string $file
+	 * @param string $contents
+	 * @param bool|string $mode
+	 * @return bool
+	 */
 	public function put_contents($file, $contents, $mode = false ) {
 		$tempfile = wp_tempnam($file);
 		$temp = fopen( $tempfile, 'wb+' );
@@ -143,6 +157,9 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 		return $ret;
 	}
 
+	/**
+	 * @return string
+	 */
 	public function cwd() {
 		$cwd = @ftp_pwd($this->link);
 		if ( $cwd )
@@ -150,14 +167,29 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 		return $cwd;
 	}
 
+	/**
+	 * @param string $dir
+	 * @return bool
+	 */
 	public function chdir($dir) {
 		return @ftp_chdir($this->link, $dir);
 	}
 
+	/**
+	 * @param string $file
+	 * @param bool $group
+	 * @param bool $recursive
+	 */
 	public function chgrp($file, $group, $recursive = false ) {
 		return false;
 	}
 
+	/**
+	 * @param string $file
+	 * @param int $mode
+	 * @param bool $recursive
+	 * @return bool
+	 */
 	public function chmod($file, $mode = false, $recursive = false) {
 		if ( ! $mode ) {
 			if ( $this->is_file($file) )
@@ -181,21 +213,39 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 		return (bool)@ftp_chmod($this->link, $mode, $file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return string
+	 */
 	public function owner($file) {
 		$dir = $this->dirlist($file);
 		return $dir[$file]['owner'];
 	}
-
+	/**
+	 * @param string $file
+	 * @return string
+	 */
 	public function getchmod($file) {
 		$dir = $this->dirlist($file);
 		return $dir[$file]['permsn'];
 	}
-
+	/**
+	 * @param string $file
+	 * @return string
+	 */
 	public function group($file) {
 		$dir = $this->dirlist($file);
 		return $dir[$file]['group'];
 	}
 
+	/**
+	 *
+	 * @param string $source
+	 * @param string $destination
+	 * @param bool   $overwrite
+	 * @param string|bool $mode
+	 * @return bool
+	 */
 	public function copy($source, $destination, $overwrite = false, $mode = false) {
 		if ( ! $overwrite && $this->exists($destination) )
 			return false;
@@ -204,11 +254,21 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 			return false;
 		return $this->put_contents($destination, $content, $mode);
 	}
-
+	/**
+	 * @param string $source
+	 * @param string $destination
+	 * @param bool $overwrite
+	 * @return bool
+	 */
 	public function move($source, $destination, $overwrite = false) {
 		return ftp_rename($this->link, $source, $destination);
 	}
-
+	/**
+	 * @param string $file
+	 * @param bool $recursive
+	 * @param string $type
+	 * @return bool
+	 */
 	public function delete($file, $recursive = false, $type = false) {
 		if ( empty($file) )
 			return false;
@@ -223,16 +283,25 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 				$this->delete( trailingslashit($file) . $delete_file['name'], $recursive, $delete_file['type'] );
 		return @ftp_rmdir($this->link, $file);
 	}
-
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function exists($file) {
 		$list = @ftp_nlist($this->link, $file);
 		return !empty($list); //empty list = no file, so invert.
 	}
-
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_file($file) {
 		return $this->exists($file) && !$this->is_dir($file);
 	}
-
+	/**
+	 * @param string $path
+	 * @return bool
+	 */
 	public function is_dir($path) {
 		$cwd = $this->cwd();
 		$result = @ftp_chdir($this->link, trailingslashit($path) );
@@ -243,30 +312,56 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 		return false;
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_readable($file) {
 		return true;
 	}
-
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_writable($file) {
 		return true;
 	}
-
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function atime($file) {
 		return false;
 	}
-
+	/**
+	 * @param string $file
+	 * @return int
+	 */
 	public function mtime($file) {
 		return ftp_mdtm($this->link, $file);
 	}
-
+	/**
+	 * @param string $file
+	 * @return int
+	 */
 	public function size($file) {
 		return ftp_size($this->link, $file);
 	}
-
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function touch($file, $time = 0, $atime = 0) {
 		return false;
 	}
 
+	/**
+	 * @param string $path
+	 * @param mixed $chmod
+	 * @param mixed $chown
+	 * @param mixed $chgrp
+	 * @return bool
+	 */
 	public function mkdir($path, $chmod = false, $chown = false, $chgrp = false) {
 		$path = untrailingslashit($path);
 		if ( empty($path) )
@@ -282,10 +377,20 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 		return true;
 	}
 
+	/**
+	 * @param string $path
+	 * @param bool $recursive
+	 * @return bool
+	 */
 	public function rmdir($path, $recursive = false) {
 		return $this->delete($path, $recursive);
 	}
 
+	/**
+	 * @staticvar bool $is_windows
+	 * @param string $line
+	 * @return string
+	 */
 	public function parselisting($line) {
 		static $is_windows;
 		if ( is_null($is_windows) )
@@ -359,6 +464,12 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 		return $b;
 	}
 
+	/**
+	 * @param string $path
+	 * @param bool $include_hidden
+	 * @param bool $recursive
+	 * @return bool|array
+	 */
 	public function dirlist($path = '.', $include_hidden = true, $recursive = false) {
 		if ( $this->is_file($path) ) {
 			$limit_file = basename($path);
diff --git a/src/wp-admin/includes/class-wp-filesystem-ftpsockets.php b/src/wp-admin/includes/class-wp-filesystem-ftpsockets.php
index 2952ae5ba5..bb7e0c2e62 100644
--- a/src/wp-admin/includes/class-wp-filesystem-ftpsockets.php
+++ b/src/wp-admin/includes/class-wp-filesystem-ftpsockets.php
@@ -81,6 +81,10 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 		return true;
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool|string
+	 */
 	public function get_contents( $file ) {
 		if ( ! $this->exists($file) )
 			return false;
@@ -113,11 +117,20 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 		unlink($temp);
 		return $contents;
 	}
-
+	/**
+	 * @param string $file
+	 * @return array
+	 */
 	public function get_contents_array($file) {
 		return explode("\n", $this->get_contents($file) );
 	}
 
+	/**
+	 * @param string $file
+	 * @param string $contents
+	 * @param int|bool $mode
+	 * @return bool
+	 */
 	public function put_contents($file, $contents, $mode = false ) {
 		$temp = wp_tempnam( $file );
 		if ( ! $temphandle = @fopen($temp, 'w+') ) {
@@ -163,10 +176,21 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 		return $this->ftp->chdir($file);
 	}
 
+	/**
+	 * @param string $file
+	 * @param bool $group
+	 * @param bool $recursive
+	 */
 	public function chgrp($file, $group, $recursive = false ) {
 		return false;
 	}
 
+	/**
+	 * @param string $file
+	 * @param int|bool $mode
+	 * @param bool $recursive
+	 * @return bool
+	 */
 	public function chmod($file, $mode = false, $recursive = false ) {
 		if ( ! $mode ) {
 			if ( $this->is_file($file) )
@@ -188,21 +212,37 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 		return $this->ftp->chmod($file, $mode);
 	}
 
+	/**
+	 * @param string $file
+	 * @return string
+	 */
 	public function owner($file) {
 		$dir = $this->dirlist($file);
 		return $dir[$file]['owner'];
 	}
-
+	/**
+	 * @param string $file
+	 * @return string
+	 */
 	public function getchmod($file) {
 		$dir = $this->dirlist($file);
 		return $dir[$file]['permsn'];
 	}
-
+	/**
+	 * @param string $file
+	 * @return string
+	 */
 	public function group($file) {
 		$dir = $this->dirlist($file);
 		return $dir[$file]['group'];
 	}
-
+	/**
+	 * @param string $source
+	 * @param string $destination
+	 * @param bool $overwrite
+	 * @param int|bool $mode
+	 * @return bool
+	 */
 	public function copy($source, $destination, $overwrite = false, $mode = false) {
 		if ( ! $overwrite && $this->exists($destination) )
 			return false;
@@ -213,11 +253,21 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 
 		return $this->put_contents($destination, $content, $mode);
 	}
-
+	/**
+	 * @param string $source
+	 * @param string $destination
+	 * @param bool $overwrite
+	 * @return bool
+	 */
 	public function move($source, $destination, $overwrite = false ) {
 		return $this->ftp->rename($source, $destination);
 	}
-
+	/**
+	 * @param string $file
+	 * @param bool $recursive
+	 * @param string $type
+	 * @return bool
+	 */
 	public function delete($file, $recursive = false, $type = false) {
 		if ( empty($file) )
 			return false;
@@ -229,12 +279,20 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 		return $this->ftp->mdel($file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function exists( $file ) {
 		$list = $this->ftp->nlist( $file );
 		return !empty( $list ); //empty list = no file, so invert.
 		// Return $this->ftp->is_exists($file); has issues with ABOR+426 responses on the ncFTPd server.
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_file($file) {
 		if ( $this->is_dir($file) )
 			return false;
@@ -243,6 +301,10 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 		return false;
 	}
 
+	/**
+	 * @param string $path
+	 * @return bool
+	 */
 	public function is_dir($path) {
 		$cwd = $this->cwd();
 		if ( $this->chdir($path) ) {
@@ -252,30 +314,62 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 		return false;
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_readable($file) {
 		return true;
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_writable($file) {
 		return true;
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function atime($file) {
 		return false;
 	}
 
+	/**
+	 * @param string $file
+	 * @return int
+	 */
 	public function mtime($file) {
 		return $this->ftp->mdtm($file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return int
+	 */
 	public function size($file) {
 		return $this->ftp->filesize($file);
 	}
-
+	/**
+	 * @param string $file
+	 * @param int $time
+	 * @param int $atime
+	 * @return bool
+	 */
 	public function touch($file, $time = 0, $atime = 0 ) {
 		return false;
 	}
 
+	/**
+	 * @param string $path
+	 * @param mixed $chmod
+	 * @param mixed $chown
+	 * @param mixed $chgrp
+	 * @return bool
+	 */
 	public function mkdir($path, $chmod = false, $chown = false, $chgrp = false ) {
 		$path = untrailingslashit($path);
 		if ( empty($path) )
@@ -293,10 +387,20 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 		return true;
 	}
 
+	/**
+	 * @param sting $path
+	 * @param bool $recursive
+	 */
 	public function rmdir($path, $recursive = false ) {
 		$this->delete($path, $recursive);
 	}
 
+	/**
+	 * @param string $path
+	 * @param bool $include_hidden
+	 * @param bool $recursive
+	 * @return bool|array
+	 */
 	public function dirlist($path = '.', $include_hidden = true, $recursive = false ) {
 		if ( $this->is_file($path) ) {
 			$limit_file = basename($path);
diff --git a/src/wp-admin/includes/class-wp-filesystem-ssh2.php b/src/wp-admin/includes/class-wp-filesystem-ssh2.php
index d36cf3c2e6..85b71343e4 100644
--- a/src/wp-admin/includes/class-wp-filesystem-ssh2.php
+++ b/src/wp-admin/includes/class-wp-filesystem-ssh2.php
@@ -123,6 +123,10 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return true;
 	}
 
+	/**
+	 * @param string $command
+	 * @param bool $returnbool
+	 */
 	public function run_command( $command, $returnbool = false) {
 
 		if ( ! $this->link )
@@ -144,16 +148,30 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return false;
 	}
 
+	/**
+	 * @param string $file
+	 * @return string|false
+	 */
 	public function get_contents( $file ) {
 		$file = ltrim($file, '/');
 		return file_get_contents('ssh2.sftp://' . $this->sftp_link . '/' . $file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return array
+	 */
 	public function get_contents_array($file) {
 		$file = ltrim($file, '/');
 		return file('ssh2.sftp://' . $this->sftp_link . '/' . $file);
 	}
 
+	/**
+	 * @param string $file
+	 * @param string $contents
+	 * @param int $mode
+	 * @return bool
+	 */
 	public function put_contents($file, $contents, $mode = false ) {
 		$ret = file_put_contents( 'ssh2.sftp://' . $this->sftp_link . '/' . ltrim( $file, '/' ), $contents );
 
@@ -172,10 +190,19 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return $cwd;
 	}
 
+	/**
+	 * @param string $dir
+	 * @return bool
+	 */
 	public function chdir($dir) {
 		return $this->run_command('cd ' . $dir, true);
 	}
 
+	/**
+	 * @param string $file
+	 * @param bool $group
+	 * @param bool $recursive
+	 */
 	public function chgrp($file, $group, $recursive = false ) {
 		if ( ! $this->exists($file) )
 			return false;
@@ -184,6 +211,12 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return $this->run_command(sprintf('chgrp -R %s %s', escapeshellarg($group), escapeshellarg($file)), true);
 	}
 
+	/**
+	 * @param string $file
+	 * @param int $mode
+	 * @param bool $recursive
+	 * @return bool
+	 */
 	public function chmod($file, $mode = false, $recursive = false) {
 		if ( ! $this->exists($file) )
 			return false;
@@ -208,9 +241,9 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 	 * @since Unknown
 	 *
 	 * @param string $file    Path to the file.
-	 * @param mixed  $owner   A user name or number.
-	 * @param bool $recursive Optional. If set True changes file owner recursivly. Defaults to False.
-	 * @return bool Returns true on success or false on failure.
+	 * @param bool   $owner   A user name or number.
+	 * @param bool   $recursive Optional. If set True changes file owner recursivly. Defaults to False.
+	 * @return bool|string Returns true on success or false on failure.
 	 */
 	public function chown( $file, $owner, $recursive = false ) {
 		if ( ! $this->exists($file) )
@@ -220,6 +253,10 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return $this->run_command(sprintf('chown -R %s %s', escapeshellarg($owner), escapeshellarg($file)), true);
 	}
 
+	/**
+	 * @param string $file
+	 * @return string|false
+	 */
 	public function owner($file) {
 		$owneruid = @fileowner('ssh2.sftp://' . $this->sftp_link . '/' . ltrim($file, '/'));
 		if ( ! $owneruid )
@@ -229,11 +266,18 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		$ownerarray = posix_getpwuid($owneruid);
 		return $ownerarray['name'];
 	}
-
+	/**
+	 * @param string $file
+	 * @return string
+	 */
 	public function getchmod($file) {
 		return substr( decoct( @fileperms( 'ssh2.sftp://' . $this->sftp_link . '/' . ltrim( $file, '/' ) ) ), -3 );
 	}
 
+	/**
+	 * @param string $file
+	 * @return string|false
+	 */
 	public function group($file) {
 		$gid = @filegroup('ssh2.sftp://' . $this->sftp_link . '/' . ltrim($file, '/'));
 		if ( ! $gid )
@@ -244,6 +288,13 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return $grouparray['name'];
 	}
 
+	/**
+	 * @param string $source
+	 * @param string $destination
+	 * @param bool $overwrite
+	 * @param int|bool $mode
+	 * @return bool
+	 */
 	public function copy($source, $destination, $overwrite = false, $mode = false) {
 		if ( ! $overwrite && $this->exists($destination) )
 			return false;
@@ -253,10 +304,22 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return $this->put_contents($destination, $content, $mode);
 	}
 
+	/**
+	 * @param string $source
+	 * @param string $destination
+	 * @param bool $overwrite
+	 * @return bool
+	 */
 	public function move($source, $destination, $overwrite = false) {
 		return @ssh2_sftp_rename( $this->sftp_link, $source, $destination );
 	}
 
+	/**
+	 * @param string $file
+	 * @param bool $recursive
+	 * @param string|bool $type
+	 * @return bool
+	 */
 	public function delete($file, $recursive = false, $type = false) {
 		if ( 'f' == $type || $this->is_file($file) )
 			return ssh2_sftp_unlink($this->sftp_link, $file);
@@ -271,50 +334,89 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return ssh2_sftp_rmdir($this->sftp_link, $file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function exists($file) {
 		$file = ltrim($file, '/');
 		return file_exists('ssh2.sftp://' . $this->sftp_link . '/' . $file);
 	}
-
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_file($file) {
 		$file = ltrim($file, '/');
 		return is_file('ssh2.sftp://' . $this->sftp_link . '/' . $file);
 	}
-
+	/**
+	 * @param string $path
+	 * @return bool
+	 */
 	public function is_dir($path) {
 		$path = ltrim($path, '/');
 		return is_dir('ssh2.sftp://' . $this->sftp_link . '/' . $path);
 	}
-
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_readable($file) {
 		$file = ltrim($file, '/');
 		return is_readable('ssh2.sftp://' . $this->sftp_link . '/' . $file);
 	}
-
+	/**
+	 * @param string $file
+	 * @return bool
+	 */
 	public function is_writable($file) {
 		$file = ltrim($file, '/');
 		return is_writable('ssh2.sftp://' . $this->sftp_link . '/' . $file);
 	}
-
+	/**
+	 * @param string $file
+	 * @return int
+	 */
 	public function atime($file) {
 		$file = ltrim($file, '/');
 		return fileatime('ssh2.sftp://' . $this->sftp_link . '/' . $file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return int
+	 */
 	public function mtime($file) {
 		$file = ltrim($file, '/');
 		return filemtime('ssh2.sftp://' . $this->sftp_link . '/' . $file);
 	}
 
+	/**
+	 * @param string $file
+	 * @return int
+	 */
 	public function size($file) {
 		$file = ltrim($file, '/');
 		return filesize('ssh2.sftp://' . $this->sftp_link . '/' . $file);
 	}
 
+	/**
+	 * @param string $file
+	 * @param int $time
+	 * @param int $atime
+	 */
 	public function touch($file, $time = 0, $atime = 0) {
 		//Not implemented.
 	}
 
+	/**
+	 * @param string $path
+	 * @param mixed $chmod
+	 * @param mixed $chown
+	 * @param mixed $chgrp
+	 * @return bool
+	 */
 	public function mkdir($path, $chmod = false, $chown = false, $chgrp = false) {
 		$path = untrailingslashit($path);
 		if ( empty($path) )
@@ -331,10 +433,21 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return true;
 	}
 
+	/**
+	 * @param string $path
+	 * @param bool $recursive
+	 * @return bool
+	 */
 	public function rmdir($path, $recursive = false) {
 		return $this->delete($path, $recursive);
 	}
 
+	/**
+	 * @param string $path
+	 * @param bool $include_hidden
+	 * @param bool $recursive
+	 * @return bool|array
+	 */
 	public function dirlist($path, $include_hidden = true, $recursive = false) {
 		if ( $this->is_file($path) ) {
 			$limit_file = basename($path);