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.

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

src/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 ) ) {