Apply suggestions from code review for arguments docs.

docs/arguments.rst

@@ -7,38 +7,38 @@ Arguments
 
 Arguments are:
 
-*   Are positional in nature
+*   Are positional in nature.
 *   Similar to a limited version of :ref:`options <options>` that can take an arbitrary number of inputs
-*   :ref:`documented manually <documenting-arguments>`
+*   :ref:`Documented manually <documenting-arguments>`.
 
 Useful and often used kwargs are:
 
-*   ``default`` : Passes a default
-*   ``nargs`` : Sets the number of arguments. Set to -1 to take an arbitrary number.
+*   ``default``: Passes a default.
+*   ``nargs``: Sets the number of arguments. Set to -1 to take an arbitrary number.
 
-Basic Argument
+Basic Arguments
 ---------------
 
-A minimal :class:`click.Argument` takes the name of function argument. If you just pass it this, it assumes 1 argument, required, no default and string type.
+A minimal :class:`click.Argument` solely takes one string argument: the name of the argument. This will assume the argument is required, has no default, and is of the type ``str``.
 
 Example:
 
 .. click:example::
 
     @click.command()
     @click.argument('filename')
-    def touch(filename):
+    def touch(filename: str):
         """Print FILENAME."""
         click.echo(filename)
 
-And what it looks like:
+And from the command line:
 
 .. click:run::
 
     invoke(touch, args=['foo.txt'])
 
 
-An argument may be assigned a :ref:`parameter type <parameter-types>`. If no type is provided, the type of the default value is used. If no default value is provided, the type is assumed to be STRING.
+An argument may be assigned a :ref:`parameter type <parameter-types>`. If no type is provided, the type of the default value is used. If no default value is provided, the type is assumed to be :data:`STRING`.
 
 .. admonition:: Note on Required Arguments
 
@@ -54,20 +54,20 @@ To set the number of argument use the ``nargs`` kwarg. It can be set to any posi
     @click.command()
     @click.argument('src', nargs=1)
     @click.argument('dsts', nargs=-1)
-    def copy(src, dsts):
+    def copy(src: str, dsts: tuple[str, ...]):
         """Move file SRC to DST."""
         for destination in dsts:
             click.echo(f"Copy {src} to folder {destination}")
 
-And what it looks like:
+And from the command line:
 
 .. click:run::
 
     invoke(copy, args=['foo.txt', 'usr/david/foo.txt', 'usr/mitsuko/foo.txt'])
 
-.. admonition:: Note on Handling Files.
+.. admonition:: Note on Handling Files
 
-    This is not how you would handle files and files paths, since it passes them in as strings. For more see :ref:`handling-files`.
+    This is not how you should handle files and files paths. This merely used as a simple example. See :ref:`handling-files` to learn more about how to handle files in parameters.
 
 Argument Escape Sequences
 ---------------------------
@@ -79,8 +79,8 @@ Example usage:
 .. click:example::
 
     @click.command()
-    @click.argument('files', nargs=-1, type=click.Path())
-    def touch(files):
+    @click.argument('files', nargs=-1, type=click.Path(path_type=pathlib.Path))
+    def touch(files: tuple[pathlib.Path, ...]):
         """Print all FILES file names."""
         for filename in files:
             click.echo(filename)
@@ -114,7 +114,7 @@ And from the command line:
 Environment Variables
 ---------------------
 
-Arguments can use environment variables. To do so pass the name of the environment variable(s) into ``click.argument``.
+Arguments can use environment variables. To do so, pass the name(s) of the environment variable(s) via `envvar` in ``click.argument``.
 
 Checking one environment variable:
 

docs/handling-files.rst

@@ -5,7 +5,7 @@ Handling Files
 
 .. currentmodule:: click
 
-Click has built in features to support file and file path handling. Since files and files paths are recommended to be passed in as arguments, the examples use arguments.
+Click has built in features to support file and file path handling. The examples use arguments but the same principle applies to options as well.
 
 .. _file-args:
 
@@ -14,8 +14,8 @@ File Arguments
 
 Click supports working with files with the :class:`File` type. Some notable features are:
 
-*   Support for   ``-`` to mean a special file that refers to stdin/stdout. This is common pattern for POSIX command line utilities, for example wget.
-*   Deals with Unicode and bytes correctly for all versions of Python.
+*   Support for   ``-`` to mean a special file that refers to stdin when used for reading, and stdout when used for writing. This is a common pattern for POSIX command line utilities.
+*   Deals with ``str`` and ``bytes`` correctly for all versions of Python.
 
 Example:
 
@@ -32,7 +32,7 @@ Example:
                 break
             output.write(chunk)
 
-And what it does:
+And from the command line:
 
 .. click:run::
 
@@ -44,10 +44,14 @@ And what it does:
 File Path Arguments
 ----------------------
 
-For handling paths, the :class:`Path` type is better than a string. Some notable features are:
+For handling paths, the :class:`Path` type is better than a ``str``. Some notable features are:
 
-*   It can run checks such as does the path exist or is the file executable.
-*   It also handles formatting error messages with :func:`format_filename` so any undecodable bytes will be printed nicely.
+*   The ``exists`` argument will verify whether the path exists.
+*	``readable``, ``writable``, and ``executable`` can perform permission checks.
+*	``file_okay`` and ``dir_okay`` allow specifying whether files/directories are accepted.
+*   Error messages are nicely formatted using :func:`format_filename` so any undecodable bytes will be printed nicely.
+
+See :class:`Path` for all features.
 
 Example:
 
@@ -59,7 +63,7 @@ Example:
         """Print FILENAME if the file exists."""
         click.echo(click.format_filename(filename))
 
-And what it does:
+And from the command line:
 
 .. click:run::
 
@@ -79,7 +83,7 @@ The :class:`File` type attempts to be "intelligent" about when to open a file. S
 File open behavior can be controlled by the boolean kwarg ``lazy``. If a file is opened lazily:
 
 *   A failure at first IO operation will happen by raising an :exc:`FileError`.
-*   It can help minimize resource handling confusion.  If a file is opened in lazy mode, it will receive a ``close_intelligently`` method that can help figure out if the file needs closing or not. This is not needed for parameters, but is necessary for manually prompting. For manual prompts with the :func:`prompt` function you do not know if a stream like stdout was opened (which was already open before) or a real file was opened (that needs closing).
+*   It can help minimize resource handling confusion.  If a file is opened in lazy mode, it will call :meth:`LazyFile.close_intelligently` to help figure out if the file needs closing or not. This is not needed for parameters, but is necessary for manually prompting. For manual prompts with the :func:`prompt` function you do not know if a stream like stdout was opened (which was already open before) or a real file was opened (that needs closing).
 
 Since files opened for writing will typically empty the file, the lazy mode should only be disabled if the developer is absolutely sure that this is intended behavior.