HTTP: Document that the return value of wp_remote_retrieve_headers() changed from a simple array to an object which implements ArrayAccess.

Props mrahmadawais, sudar, swissspidy.
Fixes #37722


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

src/wp-includes/class-wp-http-requests-response.php

@@ -65,17 +65,18 @@ class WP_HTTP_Requests_Response extends WP_HTTP_Response {
 	 * @since 4.6.0
 	 * @access public
 	 *
-	 * @return array Map of header name to header value.
+	 * @see \Requests_Utility_CaseInsensitiveDictionary
+	 *
+	 * @return \Requests_Utility_CaseInsensitiveDictionary Map of header name to header value.
 	 */
 	public function get_headers() {
-		// Ensure headers remain case-insensitive
+		// Ensure headers remain case-insensitive.
 		$converted = new Requests_Utility_CaseInsensitiveDictionary();
 
 		foreach ( $this->response->headers->getAll() as $key => $value ) {
 			if ( count( $value ) === 1 ) {
 				$converted[ $key ] = $value[0];
-			}
-			else {
+			} else {
 				$converted[ $key ] = $value;
 			}
 		}

src/wp-includes/http.php

@@ -208,9 +208,12 @@ function wp_remote_head($url, $args = array()) {
  * Retrieve only the headers from the raw response.
  *
  * @since 2.7.0
+ * @since 4.6.0 Return value changed from an array to an Requests_Utility_CaseInsensitiveDictionary instance.
+ *
+ * @see \Requests_Utility_CaseInsensitiveDictionary
  *
  * @param array $response HTTP response.
- * @return array The headers of the response. Empty array if incorrect parameter given.
+ * @return array|\Requests_Utility_CaseInsensitiveDictionary The headers of the response. Empty array if incorrect parameter given.
  */
 function wp_remote_retrieve_headers( $response ) {
 	if ( is_wp_error( $response ) || ! isset( $response['headers'] ) ) {