From 86b0faf219709d750e67c30da391b7a63254508f Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Mon, 7 Oct 2019 19:06:41 +0000 Subject: [PATCH] Docs: Miscellaneous inline docs corrections and improvements. See #47110 git-svn-id: https://develop.svn.wordpress.org/trunk@46424 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/class-http.php | 30 +++++++-------- .../class-wp-http-requests-response.php | 2 - src/wp-includes/http.php | 37 ++++++++++--------- src/wp-includes/taxonomy.php | 12 +++--- 4 files changed, 40 insertions(+), 41 deletions(-) diff --git a/src/wp-includes/class-http.php b/src/wp-includes/class-http.php index 1d0d5074e5..00fd2ad849 100644 --- a/src/wp-includes/class-http.php +++ b/src/wp-includes/class-http.php @@ -133,7 +133,7 @@ class WP_Http { * compressed content is returned in the response anyway, it will * need to be separately decompressed. Default true. * @type bool $sslverify Whether to verify SSL for the request. Default true. - * @type string sslcertificates Absolute path to an SSL certificate .crt file. + * @type string $sslcertificates Absolute path to an SSL certificate .crt file. * Default ABSPATH . WPINC . '/certificates/ca-bundle.crt'. * @type bool $stream Whether to stream to a file. If set to true and no filename was * given, it will be droped it in the WP temp dir and its name will @@ -215,7 +215,7 @@ class WP_Http { // Pre-parse for the HEAD checks. $args = wp_parse_args( $args ); - // By default, Head requests do not cause redirections. + // By default, HEAD requests do not cause redirections. if ( isset( $args['method'] ) && 'HEAD' == $args['method'] ) { $defaults['redirection'] = 0; } @@ -250,9 +250,9 @@ class WP_Http { * * @since 2.9.0 * - * @param false|array|WP_Error $preempt Whether to preempt an HTTP request's return value. Default false. - * @param array $parsed_args HTTP request arguments. - * @param string $url The request URL. + * @param false|array|WP_Error $preempt Whether to preempt an HTTP request's return value. Default false. + * @param array $parsed_args HTTP request arguments. + * @param string $url The request URL. */ $pre = apply_filters( 'pre_http_request', false, $parsed_args, $url ); @@ -409,11 +409,11 @@ class WP_Http { * * @since 2.8.0 * - * @param array|WP_Error $response HTTP response or WP_Error object. - * @param string $context Context under which the hook is fired. - * @param string $class HTTP transport used. - * @param array $parsed_args HTTP request arguments. - * @param string $url The request URL. + * @param array|WP_Error $response HTTP response or WP_Error object. + * @param string $context Context under which the hook is fired. + * @param string $class HTTP transport used. + * @param array $parsed_args HTTP request arguments. + * @param string $url The request URL. */ do_action( 'http_api_debug', $response, 'response', 'Requests', $parsed_args, $url ); if ( is_wp_error( $response ) ) { @@ -438,9 +438,9 @@ class WP_Http { * * @since 2.9.0 * - * @param array $response HTTP response. - * @param array $parsed_args HTTP request arguments. - * @param string $url The request URL. + * @param array $response HTTP response. + * @param array $parsed_args HTTP request arguments. + * @param string $url The request URL. */ return apply_filters( 'http_response', $response, $parsed_args, $url ); } @@ -890,7 +890,7 @@ class WP_Http { if ( ! empty( $wildcard_regex ) ) { return ! preg_match( $wildcard_regex, $check['host'] ); } else { - return ! in_array( $check['host'], $accessible_hosts ); //Inverse logic, If it's in the array, then we can't access it. + return ! in_array( $check['host'], $accessible_hosts ); // Inverse logic, if it's in the array, then don't block it. } } @@ -989,7 +989,7 @@ class WP_Http { } /** - * Handles HTTP Redirects and follows them if appropriate. + * Handles an HTTP redirect and follows it if appropriate. * * @since 3.7.0 * diff --git a/src/wp-includes/class-wp-http-requests-response.php b/src/wp-includes/class-wp-http-requests-response.php index b6c5f24a96..2c836f6c15 100644 --- a/src/wp-includes/class-wp-http-requests-response.php +++ b/src/wp-includes/class-wp-http-requests-response.php @@ -60,8 +60,6 @@ class WP_HTTP_Requests_Response extends WP_HTTP_Response { * * @since 4.6.0 * - * @see \Requests_Utility_CaseInsensitiveDictionary - * * @return \Requests_Utility_CaseInsensitiveDictionary Map of header name to header value. */ public function get_headers() { diff --git a/src/wp-includes/http.php b/src/wp-includes/http.php index 7b82b5e7ae..73eaefa603 100644 --- a/src/wp-includes/http.php +++ b/src/wp-includes/http.php @@ -154,7 +154,7 @@ function wp_remote_request( $url, $args = array() ) { } /** - * Retrieve the raw response from the HTTP request using the GET method. + * Performs an HTTP request using the GET method and returns its response. * * @since 2.7.0 * @@ -171,7 +171,7 @@ function wp_remote_get( $url, $args = array() ) { } /** - * Retrieve the raw response from the HTTP request using the POST method. + * Performs an HTTP request using the POST method and returns its response. * * @since 2.7.0 * @@ -188,7 +188,7 @@ function wp_remote_post( $url, $args = array() ) { } /** - * Retrieve the raw response from the HTTP request using the HEAD method. + * Performs an HTTP request using the HEAD method and returns its response. * * @since 2.7.0 * @@ -417,7 +417,7 @@ function get_http_origin() { * * @since 3.4.0 * - * @return array Array of origin URLs. + * @return string[] Array of origin URLs. */ function get_allowed_http_origins() { $admin_origin = parse_url( admin_url() ); @@ -438,12 +438,13 @@ function get_allowed_http_origins() { * * @since 3.4.0 * - * @param array $allowed_origins { - * Default allowed HTTP origins. - * @type string Non-secure URL for admin origin. - * @type string Secure URL for admin origin. - * @type string Non-secure URL for home origin. - * @type string Secure URL for home origin. + * @param string[] $allowed_origins { + * Array of default allowed HTTP origins. + * + * @type string $0 Non-secure URL for admin origin. + * @type string $1 Secure URL for admin origin. + * @type string $2 Non-secure URL for home origin. + * @type string $3 Secure URL for home origin. * } */ return apply_filters( 'allowed_http_origins', $allowed_origins ); @@ -517,7 +518,7 @@ function send_origin_headers() { * * @since 3.5.2 * - * @param string $url + * @param string $url Request URL. * @return false|string URL or false on failure. */ function wp_http_validate_url( $url ) { @@ -572,9 +573,9 @@ function wp_http_validate_url( $url ) { * * @since 3.6.0 * - * @param bool false Whether HTTP request is external or not. - * @param string $host IP of the requested host. - * @param string $url URL of the requested host. + * @param bool $external Whether HTTP request is external or not. + * @param string $host Host name of the requested URL. + * @param string $url Requested URL. */ if ( ! apply_filters( 'http_request_host_is_external', false, $host, $url ) ) { return false; @@ -715,9 +716,9 @@ function wp_parse_url( $url, $component = -1 ) { * @link https://secure.php.net/manual/en/function.parse-url.php * * @param array|false $url_parts The parsed URL. Can be false if the URL failed to parse. - * @param int $component The specific component to retrieve. Use one of the PHP - * predefined constants to specify which one. - * Defaults to -1 (= return all parts as an array). + * @param int $component The specific component to retrieve. Use one of the PHP + * predefined constants to specify which one. + * Defaults to -1 (= return all parts as an array). * @return mixed False on parse failure; Array of URL components on success; * When a specific component has been requested: null if the component * doesn't exist in the given URL; a string or - in the case of @@ -747,7 +748,7 @@ function _get_component_from_parsed_url_array( $url_parts, $component = -1 ) { * @link https://secure.php.net/manual/en/url.constants.php * * @param int $constant PHP_URL_* constant. - * @return string|bool The named key or false. + * @return string|false The named key or false. */ function _wp_translate_php_url_constant_to_key( $constant ) { $translation = array( diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php index d93da9f138..4631a534dd 100644 --- a/src/wp-includes/taxonomy.php +++ b/src/wp-includes/taxonomy.php @@ -3305,21 +3305,21 @@ function clean_taxonomy_cache( $taxonomy ) { } /** - * Retrieves the taxonomy relationship to the term object id. + * Retrieves the cached term objects for the given object ID. * * Upstream functions (like get_the_terms() and is_object_in_term()) are * responsible for populating the object-term relationship cache. The current * function only fetches relationship data that is already in the cache. * * @since 2.3.0 - * @since 4.7.0 Returns a `WP_Error` object if `get_term()` returns an error for + * @since 4.7.0 Returns a `WP_Error` object if there's an error with * any of the matched terms. * - * @param int $id Term object ID. + * @param int $id Term object ID, for example a post, comment, or user ID. * @param string $taxonomy Taxonomy name. - * @return bool|array|WP_Error Array of `WP_Term` objects, if cached. - * False if cache is empty for `$taxonomy` and `$id`. - * WP_Error if get_term() returns an error object for any term. + * @return bool|WP_Term[]|WP_Error Array of `WP_Term` objects, if cached. + * False if cache is empty for `$taxonomy` and `$id`. + * WP_Error if get_term() returns an error object for any term. */ function get_object_term_cache( $id, $taxonomy ) { $_term_ids = wp_cache_get( $id, "{$taxonomy}_relationships" );