Docs: Miscellaneous docs fixes and improvements.

See #48303.

git-svn-id: https://develop.svn.wordpress.org/trunk@47398 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-admin/includes/file.php

@@ -1966,21 +1966,25 @@ function get_filesystem_method( $args = array(), $context = '', $allow_relaxed_f
  *                                                    the post. Default null.
  * @param bool          $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable. Default false.
  *
- * @return bool True on success, false on failure.
+ * @return bool|array True if no filesystem credentials are required, false if they are required but have not been
+ *                    provided, array of credentials if they are required and have been provided.
  */
 function request_filesystem_credentials( $form_post, $type = '', $error = false, $context = '', $extra_fields = null, $allow_relaxed_file_ownership = false ) {
 	global $pagenow;
 
 	/**
-	 * Filters the filesystem credentials form output.
+	 * Filters the filesystem credentials.
 	 *
 	 * Returning anything other than an empty string will effectively short-circuit
 	 * output of the filesystem credentials form, returning that value instead.
 	 *
+	 * A filter should return true if no filesystem credentials are required, false if they are required but have not been
+	 * provided, or an array of credentials if they are required and have been provided.
+	 *
 	 * @since 2.5.0
 	 * @since 4.6.0 The `$context` parameter default changed from `false` to an empty string.
 	 *
-	 * @param mixed         $output                       Form output to return instead. Default empty.
+	 * @param mixed         $credentials                  Credentials to return instead. Default empty string.
 	 * @param string        $form_post                    The URL to post the form to.
 	 * @param string        $type                         Chosen type of filesystem.
 	 * @param bool|WP_Error $error                        Whether the current request has failed to connect,

src/wp-admin/includes/post.php

@@ -1968,6 +1968,8 @@ function wp_autosave( $post_data ) {
 /**
  * Redirect to previous page.
  *
+ * @since 2.7.0
+ *
  * @param int $post_id Optional. Post ID.
  */
 function redirect_post( $post_id = '' ) {

src/wp-includes/functions.php

@@ -2640,8 +2640,8 @@ function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {
 	/**
 	 * Filters whether to treat the upload bits as an error.
 	 *
-	 * Passing a non-array to the filter will effectively short-circuit preparing
-	 * the upload bits, returning that value instead.
+	 * Returning a non-array from the filter will effectively short-circuit preparing the upload
+	 * bits, returning that value instead. An error message should be returned as a string.
 	 *
 	 * @since 3.0.0
 	 *

src/wp-includes/pluggable.php

@@ -855,27 +855,27 @@ if ( ! function_exists( 'wp_set_auth_cookie' ) ) :
 			$secure = is_ssl();
 		}
 
-		// Front-end cookie is secure when the auth cookie is secure and the site's home URL is forced HTTPS.
+		// Front-end cookie is secure when the auth cookie is secure and the site's home URL uses HTTPS.
 		$secure_logged_in_cookie = $secure && 'https' === parse_url( get_option( 'home' ), PHP_URL_SCHEME );
 
 		/**
-		 * Filters whether the connection is secure.
+		 * Filters whether the auth cookie should only be sent over HTTPS.
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param bool $secure  Whether the connection is secure.
+		 * @param bool $secure  Whether the cookie should only be sent over HTTPS.
 		 * @param int  $user_id User ID.
 		 */
 		$secure = apply_filters( 'secure_auth_cookie', $secure, $user_id );
 
 		/**
-		 * Filters whether to use a secure cookie when logged-in.
+		 * Filters whether the logged in cookie should only be sent over HTTPS.
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param bool $secure_logged_in_cookie Whether to use a secure cookie when logged-in.
+		 * @param bool $secure_logged_in_cookie Whether the logged in cookie should only be sent over HTTPS.
 		 * @param int  $user_id                 User ID.
-		 * @param bool $secure                  Whether the connection is secure.
+		 * @param bool $secure                  Whether the auth cookie should only be sent over HTTPS.
 		 */
 		$secure_logged_in_cookie = apply_filters( 'secure_logged_in_cookie', $secure_logged_in_cookie, $user_id, $secure );