PEP 597: Revise docstring and warning text in text_encoding function

pep-0597.rst

@@ -144,23 +144,26 @@ except that ``io.TextIOWrapper`` doesn't emit ``EncodingWarning`` when
 A pure Python implementation will look like this::
 
    def text_encoding(encoding, stacklevel=1):
-       """Helper function to choose the text encoding.
+       """A helper function to choose the text encoding.
 
        When *encoding* is not None, just return it.
-       Otherwise, return the default text encoding (i.e., "locale").
+       Otherwise, return the default text encoding (i.e. "locale").
 
-       This function emits EncodingWarning if *encoding* is None and
-       sys.flags.encoding_warning is true.
+       This function emits an EncodingWarning if *encoding* is None and
+       sys.flags.encoding_warning is True.
 
-       This function can be used in APIs having encoding=None option
-       and pass it to TextIOWrapper or open.
-       But please consider using encoding="utf-8" for new APIs.
+       This function can be used in APIs with an encoding=None parameter
+       that pass it to TextIOWrapper or open.
+       However, please consider using encoding="utf-8" for new APIs.
        """
        if encoding is None:
            if sys.flags.encoding_warning:
                import warnings
-               warnings.warn("'encoding' option is omitted",
-                            EncodingWarning, stacklevel + 2)
+               warnings.warn(
+                   "The 'encoding' argument was omitted; please "
+                   "explicitly specify one (e.g. 'utf-8'), or 'locale' "
+                   "to use the current system's locale encoding",
+                   EncodingWarning, stacklevel + 2)
            encoding = "locale"
        return encoding