Documentation fix

docs/request-options.rst

@@ -556,8 +556,8 @@ http_errors
 idn_conversion
 ---
 
-:Summary: Set to ``false`` to disable Internationalized Domain Name (IDN) to
-    ASCII conversion.
+:Summary: Internationalized Domain Name (IDN) support (enabled by default if
+    ``intl`` extension is available).
 :Types:
     - bool
     - int
@@ -567,15 +567,15 @@ idn_conversion
 .. code-block:: php
 
     $client->request('GET', 'https://яндекс.рф');
-    // яндекс.рф is translated to  internally
+    // яндекс.рф is translated to xn--d1acpjx3f.xn--p1ai before passing it to the handler
 
     $res = $client->request('GET', 'https://яндекс.рф', ['idn_conversion' => false]);
     // The domain part (яндекс.рф) stays unmodified
 
-Also a combination of IDNA_* constants (except IDNA_ERROR_*) also can be used
-for precise control of the IDN support (see ``$options`` parameter in
+Enables/disables IDN support, can also be used for precise control by combining
+IDNA_* constants (except IDNA_ERROR_*), see ``$options`` parameter in
 `idn_to_ascii() <https://www.php.net/manual/en/function.idn-to-ascii.php>`_
-documentation for more details).
+documentation for more details.
 
 
 json

src/RequestOptions.php

@@ -133,10 +133,10 @@ final class RequestOptions
     const HTTP_ERRORS = 'http_errors';
 
     /**
-     * idn: (bool|int, default=true) Set to false to disable exceptions
-     * when a non- successful HTTP response is received. By default,
-     * exceptions will be thrown for 4xx and 5xx responses. This option only
-     * works if your handler has the `httpErrors` middleware.
+     * idn: (bool|int, default=true) A combination of IDNA_* constants for
+     * idn_to_ascii() PHP's function (see "options" parameter). Set to false to
+     * disable IDN support completely, or to true to use the default
+     * configuration (IDNA_DEFAULT constant).
      */
     const IDN_CONVERSION = 'idn_conversion';