Merge pull request #543 from WordPress/feature/various-minor-docs-fixes

docs/hooks.md

@@ -35,13 +35,13 @@ Available Hooks
     Set cURL options before the transport sets any (note that Requests may
     override these).
 
-    Parameters: `cURL resource &$fp`
+    Parameters: `cURL resource|CurlHandle &$fp`
 
 * **`curl.before_send`**
 
     Set cURL options just before the request is actually sent via `curl_exec()`.
 
-    Parameters: `cURL resource &$fp`
+    Parameters: `cURL resource|CurlHandle &$fp`
 
 * **`curl.after_request`**
 

src/Auth/Basic.php

@@ -67,7 +67,7 @@ public function register(Hooks $hooks) {
 	/**
 	 * Set cURL parameters before the data is sent
 	 *
-	 * @param resource $handle cURL resource
+	 * @param resource|\CurlHandle $handle cURL handle
 	 */
 	public function curl_before_send(&$handle) {
 		curl_setopt($handle, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

src/Exception/Http.php

@@ -49,7 +49,9 @@ public function __construct($reason = null, $data = null) {
 	}
 
 	/**
-	 * Get the status message
+	 * Get the status message.
+	 *
+	 * @return string
 	 */
 	public function getReason() {
 		return $this->reason;

src/Exception/Transport/Curl.php

@@ -33,6 +33,14 @@ final class Curl extends Transport {
 	 */
 	protected $reason = 'Unknown';
 
+	/**
+	 * Create a new exception.
+	 *
+	 * @param string $message Exception message.
+	 * @param string $type    Exception type.
+	 * @param mixed  $data    Associated data, if applicable.
+	 * @param int    $code    Exception numerical code, if applicable.
+	 */
 	public function __construct($message, $type, $data = null, $code = 0) {
 		if ($type !== null) {
 			$this->type = $type;
@@ -51,7 +59,9 @@ public function __construct($message, $type, $data = null, $code = 0) {
 	}
 
 	/**
-	 * Get the error message
+	 * Get the error message.
+	 *
+	 * @return string
 	 */
 	public function getReason() {
 		return $this->reason;

src/Proxy/Http.php

@@ -102,7 +102,7 @@ public function register(Hooks $hooks) {
 	 * Set cURL parameters before the data is sent
 	 *
 	 * @since 1.6
-	 * @param resource $handle cURL resource
+	 * @param resource|\CurlHandle $handle cURL handle
 	 */
 	public function curl_before_send(&$handle) {
 		curl_setopt($handle, CURLOPT_PROXYTYPE, CURLPROXY_HTTP);

src/Requests.php

@@ -901,7 +901,7 @@ public static function compatible_gzinflate($gz_data) {
 		// If the data is Huffman Encoded, we must first strip the leading 2
 		// byte Huffman marker for gzinflate()
 		// The response is Huffman coded by many compressors such as
-		// java.util.zip.Deflater, Ruby’s Zlib::Deflate, and .NET's
+		// java.util.zip.Deflater, Ruby's Zlib::Deflate, and .NET's
 		// System.IO.Compression.DeflateStream.
 		//
 		// See https://decompres.blogspot.com/ for a quick explanation of this

src/Response/Headers.php

@@ -95,7 +95,9 @@ public function flatten($value) {
 	/**
 	 * Get an iterator for the data
 	 *
-	 * Converts the internal
+	 * Converts the internally stored values to a comma-separated string if there is more
+	 * than one value for a key.
+	 *
 	 * @return \ArrayIterator
 	 */
 	public function getIterator() {

src/Ssl.php

@@ -25,7 +25,6 @@ final class Ssl {
 	 *
 	 * @link https://tools.ietf.org/html/rfc2818#section-3.1 RFC2818, Section 3.1
 	 *
-	 * @throws \WpOrg\Requests\Exception On not obtaining a match for the host (`fsockopen.ssl.no_match`)
 	 * @param string $host Host name to verify against
 	 * @param array $cert Certificate data from openssl_x509_parse()
 	 * @return bool

src/Transport/Curl.php

@@ -57,7 +57,7 @@ final class Curl implements Transport {
 	/**
 	 * cURL handle
 	 *
-	 * @var resource
+	 * @var resource|\CurlHandle Resource in PHP < 8.0, Instance of CurlHandle in PHP >= 8.0.
 	 */
 	private $handle;
 
@@ -213,7 +213,7 @@ public function request($url, $headers = array(), $data = array(), $options = ar
 		$this->process_response($response, $options);
 
 		// Need to remove the $this reference from the curl handle.
-		// Otherwise \WpOrg\Requests\Transport\Curl wont be garbage collected and the curl_close() will never be called.
+		// Otherwise \WpOrg\Requests\Transport\Curl won't be garbage collected and the curl_close() will never be called.
 		curl_setopt($this->handle, CURLOPT_HEADERFUNCTION, null);
 		curl_setopt($this->handle, CURLOPT_WRITEFUNCTION, null);
 
@@ -315,7 +315,7 @@ public function request_multiple($requests, $options) {
 	 * @param array $headers Associative array of request headers
 	 * @param string|array $data Data to send either as the POST body, or as parameters in the URL for a GET/HEAD
 	 * @param array $options Request options, see {@see \WpOrg\Requests\Requests::response()} for documentation
-	 * @return resource Subrequest's cURL handle
+	 * @return resource|\CurlHandle Subrequest's cURL handle
 	 */
 	public function &get_subrequest_handle($url, $headers, $data, $options) {
 		$this->setup_handle($url, $headers, $data, $options);
@@ -484,7 +484,7 @@ public function process_response($response, $options) {
 	/**
 	 * Collect the headers as they are received
 	 *
-	 * @param resource $handle cURL resource
+	 * @param resource|\CurlHandle $handle cURL handle
 	 * @param string $headers Header string
 	 * @return integer Length of provided header
 	 */
@@ -509,7 +509,7 @@ public function stream_headers($handle, $headers) {
 	 *
 	 * @since 1.6.1
 	 *
-	 * @param resource $handle cURL resource
+	 * @param resource|\CurlHandle $handle cURL handle
 	 * @param string $data Body data
 	 * @return integer Length of provided data
 	 */