Changeset 47398

Timestamp:

03/01/2020 10:38:00 AM (3 days ago)

Author:

johnbillion

Message:

Docs: Miscellaneous docs fixes and improvements.

See #48303.

Location:

trunk/src

Files:

• wp-admin/includes/file.php (modified) (2 diffs)
• wp-admin/includes/post.php (modified) (1 diff)
• wp-includes/functions.php (modified) (1 diff)
• wp-includes/pluggable.php (modified) (2 diffs)

trunk/src/wp-admin/includes/file.php

@@ -1967 +1967 @@
  * @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 ) {
@@ -1973 +1974 @@
 
     /**
-     * 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.

trunk/src/wp-admin/includes/post.php

@@ -1968 +1968 @@
 /**
  * Redirect to previous page.
+ *
+ * @since 2.7.0
  *
  * @param int $post_id Optional. Post ID.

trunk/src/wp-includes/functions.php

@@ -2641 +2641 @@
      * 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

trunk/src/wp-includes/pluggable.php

@@ -856 +856 @@
         }
 
-        // 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.
          */
@@ -870 +870 @@
 
         /**
-         * 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 );