Docs: Correct @return value for wp_get_http_headers().

Following the update to replace the HTTP API internals with Requests library in WordPress 4.6, the return value of `wp_remote_retrieve_headers()` has changed from a simple array to an object which implements `ArrayAccess`.

Since `wp_get_http_headers()` directly returns the result of `wp_remote_retrieve_headers()`, its return value should reflect that change.

Includes:
* Updating the return value for the deprecated `wp_get_http()` function, which also directly returns the result of `wp_remote_retrieve_headers()`.
* Minor DocBlock formatting changes for some other HTTP API functions per the documentation standards.

Follow-up to [2416], [6390], [8092], [9013], [37428], [37989], [38730].

Props mhkuu.
See #54225, #55646.
Built from https://develop.svn.wordpress.org/trunk@54157

wp-includes/deprecated.php

@@ -3654,7 +3654,7 @@ function post_permalink( $post = 0 ) {
  * @param string|bool $file_path Optional. File path to write request to. Default false.
  * @param int         $red       Optional. The number of Redirects followed, Upon 5 being hit,
  *                               returns false. Default 1.
- * @return bool|string False on failure and string of headers if HEAD request.
+ * @return \Requests_Utility_CaseInsensitiveDictionary|false Headers on success, false on failure.
  */
 function wp_get_http( $url, $file_path = false, $red = 1 ) {
 	_deprecated_function( __FUNCTION__, '4.4.0', 'WP_Http' );

wp-includes/functions.php

@@ -978,7 +978,7 @@ function do_enclose( $content, $post ) {
  *
  * @param string $url        URL to retrieve HTTP headers from.
  * @param bool   $deprecated Not Used.
- * @return string|false Headers on success, false on failure.
+ * @return \Requests_Utility_CaseInsensitiveDictionary|false Headers on success, false on failure.
  */
 function wp_get_http_headers( $url, $deprecated = false ) {
 	if ( ! empty( $deprecated ) ) {

wp-includes/http.php

@@ -205,7 +205,8 @@ function wp_remote_head( $url, $args = array() ) {
  * @see \Requests_Utility_CaseInsensitiveDictionary
  *
  * @param array|WP_Error $response HTTP response.
- * @return array|\Requests_Utility_CaseInsensitiveDictionary The headers of the response. Empty array if incorrect parameter given.
+ * @return \Requests_Utility_CaseInsensitiveDictionary|array The headers of the response, or empty array
+ *                                                           if incorrect parameter given.
  */
 function wp_remote_retrieve_headers( $response ) {
 	if ( is_wp_error( $response ) || ! isset( $response['headers'] ) ) {
@@ -245,7 +246,7 @@ function wp_remote_retrieve_header( $response, $header ) {
  * @since 2.7.0
  *
  * @param array|WP_Error $response HTTP response.
- * @return int|string The response code as an integer. Empty string on incorrect parameter given.
+ * @return int|string The response code as an integer. Empty string if incorrect parameter given.
  */
 function wp_remote_retrieve_response_code( $response ) {
 	if ( is_wp_error( $response ) || ! isset( $response['response'] ) || ! is_array( $response['response'] ) ) {
@@ -263,7 +264,7 @@ function wp_remote_retrieve_response_code( $response ) {
  * @since 2.7.0
  *
  * @param array|WP_Error $response HTTP response.
- * @return string The response message. Empty string on incorrect parameter given.
+ * @return string The response message. Empty string if incorrect parameter given.
  */
 function wp_remote_retrieve_response_message( $response ) {
 	if ( is_wp_error( $response ) || ! isset( $response['response'] ) || ! is_array( $response['response'] ) ) {
@@ -295,7 +296,8 @@ function wp_remote_retrieve_body( $response ) {
  * @since 4.4.0
  *
  * @param array|WP_Error $response HTTP response.
- * @return WP_Http_Cookie[] An array of `WP_Http_Cookie` objects from the response. Empty array if there are none, or the response is a WP_Error.
+ * @return WP_Http_Cookie[] An array of `WP_Http_Cookie` objects from the response.
+ *                          Empty array if there are none, or the response is a WP_Error.
  */
 function wp_remote_retrieve_cookies( $response ) {
 	if ( is_wp_error( $response ) || empty( $response['cookies'] ) ) {
@@ -312,7 +314,8 @@ function wp_remote_retrieve_cookies( $response ) {
  *
  * @param array|WP_Error $response HTTP response.
  * @param string         $name     The name of the cookie to retrieve.
- * @return WP_Http_Cookie|string The `WP_Http_Cookie` object. Empty string if the cookie isn't present in the response.
+ * @return WP_Http_Cookie|string The `WP_Http_Cookie` object, or empty string
+ *                               if the cookie is not present in the response.
  */
 function wp_remote_retrieve_cookie( $response, $name ) {
 	$cookies = wp_remote_retrieve_cookies( $response );
@@ -337,7 +340,8 @@ function wp_remote_retrieve_cookie( $response, $name ) {
  *
  * @param array|WP_Error $response HTTP response.
  * @param string         $name     The name of the cookie to retrieve.
- * @return string The value of the cookie. Empty string if the cookie isn't present in the response.
+ * @return string The value of the cookie, or empty string
+ *                if the cookie is not present in the response.
  */
 function wp_remote_retrieve_cookie_value( $response, $name ) {
 	$cookie = wp_remote_retrieve_cookie( $response, $name );

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.1-alpha-54156';
+$wp_version = '6.1-alpha-54157';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.