Miscellaneous documentation & docstring changes

12 files changed, 122 insertions, 126 deletions

diff --git a/click/__init__.py b/click/__init__.py
index 4f3ca19..748b1e3 100644
--- a/click/__init__.py
+++ b/click/__init__.py
@@ -3,11 +3,11 @@
     click
     ~~~~~
 
-    click is a simple Python module that wraps the stdlib's optparse to make
-    writing command line scripts fun.  Unlike other modules it's based around
+    Click is a simple Python module that wraps the stdlib's optparse to make
+    writing command line scripts fun.  Unlike other modules, it's based around
     a simple API that does not come with too much magic and is composable.
 
-    In case optparse ever goes away from the stdlib it will be shipped by
+    In case optparse ever gets removed from the stdlib, it will be shipped by
     this module.
 
     :copyright: (c) 2014 by Armin Ronacher.
diff --git a/click/_compat.py b/click/_compat.py
index 57c69f7..0287fd6 100644
--- a/click/_compat.py
+++ b/click/_compat.py
@@ -43,9 +43,9 @@ class _NonClosingTextIOWrapper(io.TextIOWrapper):
         io.TextIOWrapper.__init__(self, _FixupStream(stream),
                                   encoding, errors, **extra)
 
-    # The io module is already a place where Python 2 got the
-    # python 3 text behavior forced on, so we need to unbreak
-    # it to look like python 2 stuff.
+    # The io module is a place where the Python 3 text behavior
+    # was forced upon Python 2, so we need to unbreak
+    # it to look like Python 2.
     if PY2:
         def write(self, x):
             if isinstance(x, str) or is_bytes(x):
@@ -69,7 +69,7 @@ class _NonClosingTextIOWrapper(io.TextIOWrapper):
 
 class _FixupStream(object):
     """The new io interface needs more from streams than streams
-    traditionally implement.  As such this fixup stuff is necessary in
+    traditionally implement.  As such, this fix-up code is necessary in
     some circumstances.
     """
 
@@ -83,7 +83,7 @@ class _FixupStream(object):
         f = getattr(self._stream, 'read1', None)
         if f is not None:
             return f(size)
-        # Only python 2 we dispatch to readline instead of read as we
+        # We only dispatch to readline instead of read in Python 2 as we
         # do not want cause problems with the different implementation
         # of line buffering.
         if PY2:
@@ -137,14 +137,14 @@ if PY2:
 
     _identifier_re = re.compile(r'^[a-zA-Z_][a-zA-Z0-9_]*$')
 
-    # For Windows we need to force stdout/stdin/stderr to binary if it's
+    # For Windows, we need to force stdout/stdin/stderr to binary if it's
     # fetched for that.  This obviously is not the most correct way to do
-    # it as it changes global state.  Unfortunately there does not seem to
+    # it as it changes global state.  Unfortunately, there does not seem to
     # be a clear better way to do it as just reopening the file in binary
     # mode does not change anything.
     #
-    # An option would be to do what python 3 does and to open the file as
-    # binary only, patch it back to the system and then use a wrapper
+    # An option would be to do what Python 3 does and to open the file as
+    # binary only, patch it back to the system, and then use a wrapper
     # stream that converts newlines.  It's not quite clear what's the
     # correct option here.
     if sys.platform == 'win32':
@@ -203,7 +203,7 @@ else:
         except Exception:
             return default
             # This happens in some cases where the stream was already
-            # closed.  In this case we assume the defalt.
+            # closed.  In this case, we assume the default.
 
     def _is_binary_writer(stream, default=False):
         try:
@@ -219,16 +219,15 @@ else:
 
     def _find_binary_reader(stream):
         # We need to figure out if the given stream is already binary.
-        # This can happen because the official docs recommend detatching
+        # This can happen because the official docs recommend detaching
         # the streams to get binary streams.  Some code might do this, so
         # we need to deal with this case explicitly.
-        is_binary = _is_binary_reader(stream, False)
-
-        if is_binary:
+        if _is_binary_reader(stream, False):
             return stream
 
         buf = getattr(stream, 'buffer', None)
-        # Same situation here, this time we assume that the buffer is
+
+        # Same situation here; this time we assume that the buffer is
         # actually binary in case it's closed.
         if buf is not None and _is_binary_reader(buf, True):
             return buf
@@ -243,13 +242,13 @@ else:
 
         buf = getattr(stream, 'buffer', None)
 
-        # Same situation here, this time we assume that the buffer is
+        # Same situation here; this time we assume that the buffer is
         # actually binary in case it's closed.
         if buf is not None and _is_binary_writer(buf, True):
             return buf
 
     def _stream_is_misconfigured(stream):
-        """A stream is misconfigured if it's encoding is ASCII."""
+        """A stream is misconfigured if its encoding is ASCII."""
         return is_ascii_encoding(getattr(stream, 'encoding', None))
 
     def _is_compatible_text_stream(stream, encoding, errors):
@@ -260,7 +259,7 @@ else:
         if stream_encoding == encoding and stream_errors == errors:
             return True
 
-        # Otherwise it's only a compatible stream if we did not ask for
+        # Otherwise, it's only a compatible stream if we did not ask for
         # an encoding.
         if encoding is None:
             return stream_encoding is not None
@@ -271,24 +270,24 @@ else:
         if _is_binary_reader(text_reader, False):
             binary_reader = text_reader
         else:
-            # If there is no target encoding set we need to verify that the
-            # reader is actually not misconfigured.
+            # If there is no target encoding set, we need to verify that the
+            # reader is not actually misconfigured.
             if encoding is None and not _stream_is_misconfigured(text_reader):
                 return text_reader
 
             if _is_compatible_text_stream(text_reader, encoding, errors):
                 return text_reader
 
-            # If the reader has no encoding we try to find the underlying
+            # If the reader has no encoding, we try to find the underlying
             # binary reader for it.  If that fails because the environment is
             # misconfigured, we silently go with the same reader because this
-            # is too common to happen.  In that case mojibake is better than
+            # is too common to happen.  In that case, mojibake is better than
             # exceptions.
             binary_reader = _find_binary_reader(text_reader)
             if binary_reader is None:
                 return text_reader
 
-        # At this point we default the errors to replace instead of strict
+        # At this point, we default the errors to replace instead of strict
         # because nobody handles those errors anyways and at this point
         # we're so fundamentally fucked that nothing can repair it.
         if errors is None:
@@ -299,24 +298,24 @@ else:
         if _is_binary_writer(text_writer, False):
             binary_writer = text_writer
         else:
-            # If there is no target encoding set we need to verify that the
-            # writer is actually not misconfigured.
+            # If there is no target encoding set, we need to verify that the
+            # writer is not actually misconfigured.
             if encoding is None and not _stream_is_misconfigured(text_writer):
                 return text_writer
 
             if _is_compatible_text_stream(text_writer, encoding, errors):
                 return text_writer
 
-            # If the writer has no encoding we try to find the underlying
+            # If the writer has no encoding, we try to find the underlying
             # binary writer for it.  If that fails because the environment is
             # misconfigured, we silently go with the same writer because this
-            # is too common to happen.  In that case mojibake is better than
+            # is too common to happen.  In that case, mojibake is better than
             # exceptions.
             binary_writer = _find_binary_writer(text_writer)
             if binary_writer is None:
                 return text_writer
 
-        # At this point we default the errors to replace instead of strict
+        # At this point, we default the errors to replace instead of strict
         # because nobody handles those errors anyways and at this point
         # we're so fundamentally fucked that nothing can repair it.
         if errors is None:
@@ -377,7 +376,7 @@ def get_streerror(e, default=None):
 
 def open_stream(filename, mode='r', encoding=None, errors='strict',
                 atomic=False):
-    # standard streams first.  These are simple because they don't need
+    # Standard streams first.  These are simple because they don't need
     # special handling for the atomic flag.  It's entirely ignored.
     if filename == '-':
         if 'w' in mode:
@@ -388,8 +387,7 @@ def open_stream(filename, mode='r', encoding=None, errors='strict',
             return get_binary_stdin(), False
         return get_text_stdin(encoding=encoding, errors=errors), False
 
-    # Non-atomic writes directly go out through the regular open
-    # functions.
+    # Non-atomic writes directly go out through the regular open functions.
     if not atomic:
         if encoding is None:
             return open(filename, mode), True
@@ -397,7 +395,7 @@ def open_stream(filename, mode='r', encoding=None, errors='strict',
 
     # Atomic writes are more complicated.  They work by opening a file
     # as a proxy in the same folder and then using the fdopen
-    # functionality to wrap it in a python file.  Then we wrap it in an
+    # functionality to wrap it in a Python file.  Then we wrap it in an
     # atomic file that moves the file over on close.
     import tempfile
     fd, tmp_filename = tempfile.mkstemp(dir=os.path.dirname(filename),
@@ -411,8 +409,7 @@ def open_stream(filename, mode='r', encoding=None, errors='strict',
     return _AtomicFile(f, tmp_filename, filename), True
 
 
-# Used in a destructor call, needs extra protection from interpreter
-# cleanup.
+# Used in a destructor call, needs extra protection from interpreter cleanup.
 _rename = os.rename
 
 
@@ -452,8 +449,8 @@ auto_wrap_for_ansi = None
 colorama = None
 
 
-# If we're on windows we provide transparent integration through
-# colorama.  This will make ansi colors through the echo function
+# If we're on Windows, we provide transparent integration through
+# colorama.  This will make ANSI colors through the echo function
 # work automatically.
 if sys.platform.startswith('win'):
     try:
diff --git a/click/_termui_impl.py b/click/_termui_impl.py
index 0da79b2..743bdc9 100644
--- a/click/_termui_impl.py
+++ b/click/_termui_impl.py
@@ -3,7 +3,7 @@
     ~~~~~~~~~~~~~~~~~~
 
     This module contains implementations for the termui module.  To keep the
-    import time of click down some infrequently used functionality is placed
+    import time of click down, some infrequently used functionality is placed
     in this module and only imported as needed.
 
     :copyright: (c) 2014 by Armin Ronacher.
diff --git a/click/core.py b/click/core.py
index 67d3d4d..af2cfc6 100644
--- a/click/core.py
+++ b/click/core.py
@@ -38,12 +38,12 @@ def invoke_param_callback(callback, ctx, param, value):
     args = getattr(code, 'co_argcount', 3)
 
     if args < 3:
-        # This will become a warning in Click 3.0
-        ##from warnings import warn
-        ##warn(Warning('Invoked legacy parameter callback "%s".  The new '
-        ##             'signature for such callbacks starting with '
-        ##             'Click 2.0 is (ctx, param, value).'
-        ##             % callback), stacklevel=3)
+        # This will become a warning in click 3.0:
+        ## from warnings import warn
+        ## warn(Warning('Invoked legacy parameter callback "%s".  The new '
+        ##              'signature for such callbacks starting with '
+        ##              'click 2.0 is (ctx, param, value).'
+        ##              % callback), stacklevel=3)
         return callback(ctx, value)
     return callback(ctx, param, value)
 
@@ -136,14 +136,14 @@ class Context(object):
         #: this flag indicates if a subcommand is going to be executed.
         #: a group callback can use this information to figure out if it's
         #: being executed directly or because the execution flow passes
-        #: onwards to a subcommand.  By default it's `None` but it can be
+        #: onwards to a subcommand.  By default it's `None`, but it can be
         #: the name of the subcommand to execute.
         self.invoked_subcommand = None
         if obj is None and parent is not None:
             obj = parent.obj
         #: the user object stored.
         self.obj = obj
-        #: A dictionary (like object) with defaults for parameters.
+        #: A dictionary (-like object) with defaults for parameters.
         self.default_map = default_map
 
         if terminal_width is None and parent is not None:
@@ -183,7 +183,7 @@ class Context(object):
     def call_on_close(self, f):
         """This decorator remembers a function as callback that should be
         executed when the context tears down.  This is most useful to bind
-        resource handling to the script execution.  For instance file objects
+        resource handling to the script execution.  For instance, file objects
         opened by the :class:`File` type will register their close callbacks
         here.
 
@@ -318,12 +318,12 @@ class BaseCommand(object):
     functionality but it can act as the direct subclass of alternative
     parsing methods that do not depend on the click parser.
 
-    For instance this can be used to bridge click and other systems like
+    For instance, this can be used to bridge click and other systems like
     argparse or docopt.
 
     Because base commands do not implement a lot of the API that other
-    parts of click take for granted they are not supported for all
-    operations.  For instance they cannot be used with the decorators
+    parts of click take for granted, they are not supported for all
+    operations.  For instance, they cannot be used with the decorators
     usually and they have no built-in callback system.
 
     :param name: the name of the command to use unless a group overrides it.
@@ -426,7 +426,7 @@ class BaseCommand(object):
             prog_name = make_str(os.path.basename(
                 sys.argv and sys.argv[0] or __file__))
 
-        # Hook for the bash completion.  This only activates if the bash
+        # Hook for the Bash completion.  This only activates if the Bash
         # completion is actually enabled, otherwise this is quite a fast
         # noop.
         _bashcomplete(self, prog_name, complete_var)
@@ -668,7 +668,7 @@ class MultiCommand(Command):
         cmd = self.get_command(ctx, cmd_name)
 
         # If we don't find the command we want to show an error message
-        # to the user that it was not provided.  However there is
+        # to the user that it was not provided.  However, there is
         # something else we should do: if the first argument looks like
         # an option we want to kick off parsing again for arguments to
         # resolve things like --help which now should go to the main
@@ -793,7 +793,7 @@ class Parameter(object):
 
     .. versionchanged:: 2.0
        Changed signature for parameter callback to also be passed the
-       parameter.  In click 2.0 the old callback format will still work
+       parameter.  In click 2.0, the old callback format will still work,
        but it will raise a warning to give you change to migrate the
        code easier.
 
@@ -801,16 +801,16 @@ class Parameter(object):
                         argument.  This is a list of flags or argument
                         names.
     :param type: the type that should be used.  Either a :class:`ParamType`
-                 or a python type.  The later is converted into the former
+                 or a Python type.  The later is converted into the former
                  automatically if supported.
     :param required: controls if this is optional or not.
-    :param default: the default value if omitted.  This can also be a callable
+    :param default: the default value if omitted.  This can also be a callable,
                     in which case it's invoked when the default is needed
                     without any arguments.
     :param callback: a callback that should be executed after the parameter
                      was matched.  This is called as ``fn(ctx, param,
                      value)`` and needs to return the value.  Before click
-                     2.0 the signature was ``(ctx, value)``.
+                     2.0, the signature was ``(ctx, value)``.
     :param nargs: the number of arguments to match.  If not ``1`` the return
                   value is a tuple instead of single value.
     :param metavar: how the value is represented in the help page.
@@ -952,13 +952,13 @@ class Parameter(object):
 
 
 class Option(Parameter):
-    """Options are usually optionaly values on the command line and
+    """Options are usually optional values on the command line and
     have some extra features that arguments don't have.
 
     All other parameters are passed onwards to the parameter constructor.
 
     :param show_default: controls if the default value should be shown on the
-                         help page.  Normally defaults are not shown.
+                         help page.  Normally, defaults are not shown.
     :param prompt: if set to `True` or a non empty string then the user will
                    be prompted for input if not set.  If set to `True` the
                    prompt will be the option name capitalized.
diff --git a/click/decorators.py b/click/decorators.py
index 7dac27e..4b81ac5 100644
--- a/click/decorators.py
+++ b/click/decorators.py
@@ -8,7 +8,7 @@ from .utils import echo
 
 
 def pass_context(f):
-    """Marks a callback that it wants to receive the current context
+    """Marks a callback as wanting to receive the current context
     object as first argument.
     """
     f.__click_pass_context__ = True
@@ -16,7 +16,7 @@ def pass_context(f):
 
 
 def pass_obj(f):
-    """Similar to :func:`pass_context` but only pass the object on the
+    """Similar to :func:`pass_context`, but only pass the object on the
     context onwards (:attr:`Context.obj`).  This is useful if that object
     represents the state of a nested system.
     """
@@ -131,7 +131,7 @@ def _param_memo(f, param):
 
 def argument(*param_decls, **attrs):
     """Attaches an option to the command.  All positional arguments are
-    passed as parameter declarations to :class:`Argument`, all keyword
+    passed as parameter declarations to :class:`Argument`; all keyword
     arguments are forwarded unchanged.  This is equivalent to creating an
     :class:`Option` instance manually and attaching it to the
     :attr:`Command.params` list.
@@ -144,7 +144,7 @@ def argument(*param_decls, **attrs):
 
 def option(*param_decls, **attrs):
     """Attaches an option to the command.  All positional arguments are
-    passed as parameter declarations to :class:`Option`, all keyword
+    passed as parameter declarations to :class:`Option`; all keyword
     arguments are forwarded unchanged.  This is equivalent to creating an
     :class:`Option` instance manually and attaching it to the
     :attr:`Command.params` list.
@@ -156,7 +156,7 @@ def option(*param_decls, **attrs):
 
 
 def confirmation_option(*param_decls, **attrs):
-    """Shortcut for confirmation prompts that can be ignored by bypassed
+    """Shortcut for confirmation prompts that can be ignored by passing
     ``--yes`` as parameter.
 
     This is equivalent to decorating a function with :func:`option` with
@@ -262,9 +262,9 @@ def version_option(version=None, *param_decls, **attrs):
 def help_option(*param_decls, **attrs):
     """Adds a ``--help`` option which immediately ends the program
     printing out the help page.  This is usually unnecessary to add as
-    this is added by default to all commands unless supressed.
+    this is added by default to all commands unless suppressed.
 
-    Like :func:`version_option` this is implemented as eager option that
+    Like :func:`version_option`, this is implemented as eager option that
     prints in the callback and exits.
 
     All arguments are forwarded to :func:`option`.
diff --git a/click/exceptions.py b/click/exceptions.py
index 5106b33..058a9ae 100644
--- a/click/exceptions.py
+++ b/click/exceptions.py
@@ -4,7 +4,7 @@ from .utils import echo
 
 
 class ClickException(Exception):
-    """An exception that click can handle and show to the user.."""
+    """An exception that click can handle and show to the user."""
 
     #: The exit code for this exception
     exit_code = 1
@@ -50,14 +50,14 @@ class UsageError(ClickException):
 class BadParameter(UsageError):
     """An exception that formats out a standardized error message for a
     bad parameter.  This is useful when thrown from a callback or type as
-    click will attach contextual information to it (for instance like
-    which parameter it is).
+    click will attach contextual information to it (for instance, which
+    parameter it is).
 
     .. versionadded:: 2.0
 
     :param param: the parameter object that caused this error.  This can
-                  be left and click if possible will attach this info
-                  itself.
+                  be left out, and click will attach this info itself
+                  if possible.
     :param param_hint: a string that shows up as parameter name.  This
                        can be used as alternative to `param` in cases
                        where custom validation should happen.  If it is
diff --git a/click/formatting.py b/click/formatting.py
index 299e3e6..8264201 100644
--- a/click/formatting.py
+++ b/click/formatting.py
@@ -19,12 +19,12 @@ def iter_rows(rows, col_count):
 
 def wrap_text(text, width=78, initial_indent='', subsequent_indent='',
               preserve_paragraphs=False):
-    """A helper function that intelligently wraps text.  By default it
+    """A helper function that intelligently wraps text.  By default, it
     assumes that it operates on a single paragraph of text but if the
     `preserve_paragraphs` parameter is provided it will intelligently
     handle paragraphs (defined by two empty lines).
 
-    If paragraphs are handled a paragraph can be prefixed with an empty
+    If paragraphs are handled, a paragraph can be prefixed with an empty
     line containing the ``\\b`` character (``\\x08``) to indicate that
     no rewrapping should happen in that block.
 
@@ -82,11 +82,11 @@ def wrap_text(text, width=78, initial_indent='', subsequent_indent='',
 
 
 class HelpFormatter(object):
-    """This class helps with formatting text based help pages.  It's
-    usually just needed for very special internal cases but it's also
+    """This class helps with formatting text-based help pages.  It's
+    usually just needed for very special internal cases, but it's also
     exposed so that developers can write their own fancy outputs.
 
-    At present it always writes into memory.
+    At present, it always writes into memory.
 
     :param indent_increment: the additional increment for each level.
     :param width: the width for the text.  This defaults to the terminal
@@ -191,7 +191,7 @@ class HelpFormatter(object):
 
     @contextmanager
     def section(self, name):
-        """Helpful context manager that writes a paragraph, a heading
+        """Helpful context manager that writes a paragraph, a heading,
         and the indents.
 
         :param name: the section name that is written as heading.
diff --git a/click/parser.py b/click/parser.py
index 09b9491..17b73c8 100644
--- a/click/parser.py
+++ b/click/parser.py
@@ -147,7 +147,7 @@ class OptionParser(object):
     def add_option(self, opts, dest, action=None, nargs=1, const=None,
                    obj=None):
         """Adds a new option named `dest` to the parser.  The destination
-        is not inferred unlike with optparse and needs to be explicitly
+        is not inferred (unlike with optparse) and needs to be explicitly
         provided.  Action can be any of ``store``, ``store_const``,
         ``append``, ``appnd_const`` or ``count``.
 
@@ -204,7 +204,7 @@ class OptionParser(object):
         while state.rargs:
             arg = state.rargs.pop(0)
             arglen = len(arg)
-            # Double dash es always handled explicitly regardless of what
+            # Double dashes always handled explicitly regardless of what
             # prefixes are valid.
             if arg == '--':
                 return
@@ -259,8 +259,7 @@ class OptionParser(object):
                         % (opt, ', '.join(possibilities)))
 
     def _process_long_opt(self, arg, state):
-        # Value explicitly attached to arg?  Pretend it's the next
-        # argument.
+        # Value explicitly attached to arg?  Pretend it's the next argument.
         if '=' in arg:
             opt, next_arg = arg.split('=', 1)
             state.rargs.insert(0, next_arg)
diff --git a/click/termui.py b/click/termui.py
index 53dc87c..433ac85 100644
--- a/click/termui.py
+++ b/click/termui.py
@@ -36,7 +36,7 @@ def prompt(text, default=None, hide_input=False,
     """Prompts a user for input.  This is a convenience function that can
     be used to prompt a user for input later.
 
-    If the user aborts the input by sending a interrupt signal this
+    If the user aborts the input by sending a interrupt signal, this
     function will catch it and raise a :exc:`Abort` exception.
 
     :param text: the text to show for the prompt.
@@ -192,15 +192,15 @@ def progressbar(iterable=None, length=None, label=None, show_eta=True,
     """This function creates an iterable context manager that can be used
     to iterate over something while showing a progress bar.  It will
     either iterate over the `iterable` or `length` items (that are counted
-    up).  While iteration happens this function will print a rendered
+    up).  While iteration happens, this function will print a rendered
     progress bar to the given `file` (defaults to stdout) and will attempt
-    to calculate remaining time and more.  By default this progress bar
+    to calculate remaining time and more.  By default, this progress bar
     will not be rendered if the file is not a terminal.
 
     The context manager creates the progress bar.  When the context
     manager is entered the progress bar is already displayed.  With every
-    iteration over the progress bar the iterable passed to the bar is
-    advanced and the bar is updated.  When the context manager exits
+    iteration over the progress bar, the iterable passed to the bar is
+    advanced and the bar is updated.  When the context manager exits,
     a newline is printed and the progress bar is finalized on screen.
 
     No printing must happen or the progress bar will be unintentionally
@@ -378,16 +378,16 @@ def edit(text=None, editor=None, env=None, require_save=True,
     r"""Edits the given text in the defined editor.  If an editor is given
     (should be the full path to the executable but the regular operating
     system search path is used for finding the executable) it overrides
-    the detected editor.  Optionally some environment variables can be
-    used.  If the editor is closed without changes `None` is returned.  In
+    the detected editor.  Optionally, some environment variables can be
+    used.  If the editor is closed without changes, `None` is returned.  In
     case a file is edited directly the return value is always `None` and
     `require_save` and `extension` are ignored.
 
     If the editor cannot be opened a :exc:`UsageError` is raised.
 
-    Note for Windows: to simplify cross platform usage the newlines are
-    automatically converted from POSIX to Windows and reverse.  As such the
-    message here will have ``\n`` as newline markers.
+    Note for Windows: to simplify cross-platform usage, the newlines are
+    automatically converted from POSIX to Windows and vice versa.  As such,
+    the message here will have ``\n`` as newline markers.
 
     :param text: the text to edit.
     :param editor: optionally the editor to use.  Defaults to automatic
@@ -412,9 +412,9 @@ def edit(text=None, editor=None, env=None, require_save=True,
 
 def launch(url, wait=False, locate=False):
     """This function launches the given URL (or filename) in the default
-    viewer application for this file type.  If this is an executable it
+    viewer application for this file type.  If this is an executable, it
     might launch the executable in a new session.  The return value is
-    the exit code of the launched application.  Usually ``0`` indicates
+    the exit code of the launched application.  Usually, ``0`` indicates
     success.
 
     Examples::
@@ -424,12 +424,12 @@ def launch(url, wait=False, locate=False):
 
     .. versionadded:: 2.0
 
-    :param url: url or filename of the thing to launch.
+    :param url: URL or filename of the thing to launch.
     :param wait: waits for the program to stop.
     :param locate: if this is set to `True` then instead of launching the
                    application associated with the URL it will attempt to
                    launch a file manager with the file located.  This
-                   might have weird effects if the url does not point to
+                   might have weird effects if the URL does not point to
                    the filesystem.
     """
     from ._termui_impl import open_url
@@ -454,8 +454,8 @@ def getchar(echo=False):
 
     .. versionadded:: 2.0
 
-    :param echo: if set to `True` the character read will also show up on
-                 the terminal.  The default is not not show it.
+    :param echo: if set to `True`, the character read will also show up on
+                 the terminal.  The default is to not show it.
     """
     f = _getchar
     if f is None:
@@ -466,8 +466,8 @@ def getchar(echo=False):
 def pause(info='Press any key to continue ...'):
     """This command stops execution and waits for the user to press any
     key to continue.  This is similar to the Windows batch "pause"
-    command.  If the program is not run through a terminal this command
-    will do nothing instead.
+    command.  If the program is not run through a terminal, this command
+    will instead do nothing.
 
     .. versionadded:: 2.0
 
diff --git a/click/testing.py b/click/testing.py
index 7a4e2f9..bf39761 100644
--- a/click/testing.py
+++ b/click/testing.py
@@ -89,13 +89,13 @@ class Result(object):
 
 
 class CliRunner(object):
-    """The CLI runner provides functionality to invoke a Click command line
+    """The CLI runner provides functionality to invoke a click command line
     script for unittesting purposes in a isolated environment.  This only
-    works in single-threaded systems without any concurrency as it changes
+    works in single-threaded systems without any concurrency as it changes the
     global interpreter state.
 
     :param charset: the character set for the input and output data.  This is
-                    utf-8 by default and should not be changed currently as
+                    UTF-8 by default and should not be changed currently as
                     the reporting to click only works in Python 2 properly.
     :param env: a dictionary with environment variables for overriding.
     :param echo_stdin: if this is set to `True`, then reading from stdin writes
@@ -127,10 +127,10 @@ class CliRunner(object):
 
     @contextlib.contextmanager
     def isolation(self, input=None, env=None):
-        """A context manager that set up the isolation for invoking of a
-        command line tool.  This sets up stdin with the given input data,
+        """A context manager that sets up the isolation for invoking of a
+        command line tool.  This sets up stdin with the given input data
         and `os.environ` with the overrides from the given dictionary.
-        This also rebinds some internals in Click to be mocked (like the
+        This also rebinds some internals in click to be mocked (like the
         prompt functionality).
 
         This is automatically done in the :meth:`invoke` method.
diff --git a/click/types.py b/click/types.py
index abbe199..0f5ca15 100644
--- a/click/types.py
+++ b/click/types.py
@@ -16,7 +16,7 @@ class ParamType(object):
     *   it needs to convert from a string
     *   it needs to convert its result type through unchanged
         (eg: needs to be idempotent)
-    *   it needs to be able to deal with param and context being none.
+    *   it needs to be able to deal with param and context being `None`.
         This can be the case when the object is used with prompt
         inputs.
     """
@@ -49,8 +49,8 @@ class ParamType(object):
         """Given a value from an environment variable this splits it up
         into small chunks depending on the defined envvar list splitter.
 
-        If the splitter is set to `None` which means that whitespace splits,
-        then leading and trailing whitespace is ignored.  Otherwise leading
+        If the splitter is set to `None`, which means that whitespace splits,
+        then leading and trailing whitespace is ignored.  Otherwise, leading
         and trailing splitters usually lead to empty items being included.
         """
         return (rv or '').split(self.envvar_list_splitter)
@@ -227,7 +227,7 @@ class File(ParamType):
     Files can be opened for reading or writing.  The special value ``-``
     indicates stdin or stdout depending on the mode.
 
-    By default the file is opened for reading text data but it can also be
+    By default, the file is opened for reading text data, but it can also be
     opened in binary mode or for writing.  The encoding parameter can be used
     to force a specific encoding.
 
@@ -235,7 +235,7 @@ class File(ParamType):
     upon first IO.  The default is to be non lazy for standard input and
     output streams as well as files opened for reading, lazy otherwise.
 
-    Starting with click 2.0 files can also be opened atomically in which
+    Starting with click 2.0, files can also be opened atomically in which
     case all writes go into a separate file in the same folder and upon
     completion the file will be moved over to the original location.  This
     is useful if a file regularly read by other users is modified.
@@ -279,9 +279,9 @@ class File(ParamType):
             f, should_close = open_stream(value, self.mode,
                                           self.encoding, self.errors,
                                           atomic=self.atomic)
-            # If a context is provided we automatically close the file
+            # If a context is provided, we automatically close the file
             # at the end of the context execution (or flush out).  If a
-            # context does not exist it's the caller's responsibility to
+            # context does not exist, it's the caller's responsibility to
             # properly close the file.  This for instance happens when the
             # type is used with prompts.
             if ctx is not None:
@@ -300,7 +300,7 @@ class File(ParamType):
 class Path(ParamType):
     """The path type is similar to the :class:`File` type but it performs
     different checks.  First of all, instead of returning a open file
-    handle it returns just the filename.  Secondly it can perform various
+    handle it returns just the filename.  Secondly, it can perform various
     basic checks about what the file or directory should be.
 
     :param exists: if set to true, the file or directory needs to exist for
diff --git a/click/utils.py b/click/utils.py
index 0a7dd4b..bc3068b 100644
--- a/click/utils.py
+++ b/click/utils.py
@@ -19,7 +19,7 @@ def _posixify(name):
 
 
 def unpack_args(args, nargs_spec):
-    """Given an iterable of arguments and an iterable of nargs specifications
+    """Given an iterable of arguments and an iterable of nargs specifications,
     it returns a tuple with all the unpacked arguments at the first index
     and all remaining arguments as the second.
 
@@ -56,7 +56,7 @@ def unpack_args(args, nargs_spec):
             rv.append(_fetch(args))
         elif nargs > 1:
             x = [_fetch(args) for _ in range(nargs)]
-            # If we're reversed we're pulling in the arguments in reverse
+            # If we're reversed, we're pulling in the arguments in reverse,
             # so we need to turn them around.
             if spos is not None:
                 x.reverse()
@@ -67,7 +67,7 @@ def unpack_args(args, nargs_spec):
             spos = len(rv)
             rv.append(None)
 
-    # spos is the position of the wildcard (star).  If it's not None
+    # spos is the position of the wildcard (star).  If it's not `None`,
     # we fill it with the remainder.
     if spos is not None:
         rv[spos] = tuple(args)
@@ -195,16 +195,16 @@ class LazyFile(object):
 
 def echo(message=None, file=None, nl=True):
     """Prints a message plus a newline to the given file or stdout.  On
-    first sight this looks like the print function but it has improved
-    support for handling unicode and binary data that does not fail no
+    first sight, this looks like the print function, but it has improved
+    support for handling Unicode and binary data that does not fail no
     matter how badly configured the system is.
 
-    Primarily it means that you can print binary data as well as unicode
+    Primarily it means that you can print binary data as well as Unicode
     data on both 2.x and 3.x to the given file in the most appropriate way
     possible.  This is a very carefree function as in that it will try its
     best to not fail.
 
-    In addition to that if `colorama`_ is installed the echo function will
+    In addition to that, if `colorama`_ is installed, the echo function will
     also support clever handling of ANSI codes.  Essentially it will then
     do the following:
 
@@ -244,7 +244,7 @@ def echo(message=None, file=None, nl=True):
             binary_file.flush()
             return
 
-    # ANSI style support.  If there is no message or we are dealing with
+    # ANSI-style support.  If there is no message or we are dealing with
     # bytes nothing is happening.  If we are connected to a file we want
     # to strip colors.  If we have support for wrapping streams (windows
     # through colorama) we want to do that.
@@ -298,7 +298,7 @@ def format_filename(filename, shorten=False):
     """Formats a filename for user display.  The main purpose of this
     function is to ensure that the filename can be displayed at all.  This
     will decode the filename to unicode if necessary in a way that it will
-    not fail.  Optionally it can shorten the filename to not include the
+    not fail.  Optionally, it can shorten the filename to not include the
     full path to the filename.
 
     :param filename: formats a filename for UI display.  This will also convert
@@ -315,7 +315,7 @@ def get_app_dir(app_name, roaming=True, force_posix=False):
     r"""Returns the config folder for the application.  The default behavior
     is to return whatever is most appropriate for the operating system.
 
-    To give you an idea, for an app called ``"Foo Bar"`` something like
+    To give you an idea, for an app called ``"Foo Bar"``, something like
     the following folders could be returned:
 
     Mac OS X:
@@ -339,9 +339,9 @@ def get_app_dir(app_name, roaming=True, force_posix=False):
 
     :param app_name: the application name.  This should be properly capitalized
                      and can contain whitespace.
-    :param roaming: controls if the folder should be roaming or not on windows.
+    :param roaming: controls if the folder should be roaming or not on Windows.
                     Has no affect otherwise.
-    :param force_posix: if this is set to `True` then on any posix system the
+    :param force_posix: if this is set to `True` then on any POSIX system the
                         folder will be stored in the home folder with a leading
                         dot instead of the XDG config home or darwin's
                         application support folder.