Clarify some stuff

Ironically, this commit message isn't very clear

docs/failure.rst

@@ -14,7 +14,7 @@ Flask-Allows provides several measures to deal with this failure.
 Throwing an exception
 *********************
 
-The first measure is the ability to configure Requirement runners to throw an
+The first measure is the ability to configure requirements runners to throw an
 exception. By default this will be werkzeug's Forbidden exception. However,
 this can be set to be any exception type or specific instance. The easiest
 way to set this is through the :class:`~flask_allows.allows.Allows` constructor::
@@ -31,7 +31,7 @@ way to set this is through the :class:`~flask_allows.allows.Allows` constructor:
 
 
 If a particular exception is desirable most of but not all of the time, an
-exception type or instance can be provided each Requirement runner::
+exception type or instance can be provided each requirements runner::
 
     # to Permission helper
     Permission(SomeRequirement(), throws=PermissionError)
@@ -41,6 +41,12 @@ exception type or instance can be provided each Requirement runner::
     @requires(SomeRequirement(), throws=PermissionError)
 
 
+When an exception type or instance is provided to a requirements runner, it
+takes precedence over the type or instance registered on the extension object.
+If one is not supplied to a requirement runner, it uses the type or instance
+registered on the extension object.
+
+
 ****************
 Failure Callback
 ****************
@@ -96,3 +102,7 @@ runner::
     # to decorators
     @allow.requires(SomeRequirement(), on_fail=redirect_to_home)
     @requires(SomeRequirement(), on_fail=redirect_to_home)
+
+When ``on_fail`` is passed to a requirements runner, it takes precedence over
+the ``on_fail`` registered on the extension object. If an ``on_fail`` isn't
+provided then the one registered on the extension object is used.

docs/helpers.rst

@@ -77,7 +77,7 @@ is invoked::
 
 .. danger::
 
-    If you're using ``requires`` to guard route handlers, the :func:``route``
+    If you're using ``requires`` to guard route handlers, the ``route``
     decorator must be applied at the top of the decorator stack (visually first,
     logically last)::
 
@@ -104,10 +104,16 @@ adding it to the ``decorators`` property::
     class SomeView(View):
         decorators = [requires(SomeRequirement())]
 
-Or by decorating individual methods::
+When passed into the decorators property, it will guard the entire view and in
+the case of ``MethodView`` apply to every action handler on the view.
+
+You may also apply the decorator to individual methods::
 
     class SomeView(MethodView):
 
         @requires(SomeRequirement())
         def get(self):
-            ...
+            return render_template('a_template.html')
+
+In this instance, only the the ``get`` method of the view will be guarded but
+all other action handlers will not be.

docs/index.rst

@@ -4,10 +4,8 @@ Flask-Allows
 
 
 Flask-Allows gives you the ability to impose identity requirements on routes
-in your Flask application: Initialize it, create some requirements
-and begin decoratoring your routes.
+in your Flask application::
 
-.. code-block:: python
 
     from flask import Flask
     from flask_allows import Allows, Requirement

docs/quickstart.rst

@@ -77,6 +77,8 @@ imported from. We'll use the standalone decorator in this tutorial.
 Applying a requirement is done by passing the desired requirements into the
 decorator::
 
+    from flask_allows import requires
+
     @app.route('/admin')
     @requires(is_admin)
     def admin_section():

docs/requirements.rst

@@ -44,10 +44,10 @@ Class Based Requirements
 
 Class based requirements are good if you have something to represent that is
 too complicated for a function. While it is possible to implement class based
-requirements by adding a :meth:`__call__` however there is the
+requirements by adding a :meth:`__call__`, there is the
 :class:`~flask_allows.requirements.Requirement` that provides the ``fulfill``
-hook to implement instead, it also provides future proofing if new hooks are
-also implemented. For example::
+hook to implement. It also provides future proofing if new hooks are also
+implemented. For example::
 
     class Has(Requirement):
         def __init__(self, permission):
@@ -93,7 +93,7 @@ In addition to the :class:`~flask_allows.requirements.Requirement` base class,
 Flask-Allows also provides a way to combine requirements.
 
 All requirement runners provided by Flask-Allows accept multiple requirements
-and all must be truthy in order for the verification to pass::
+and all must pass for the verification to pass::
 
 
     @app.route('/admin')
@@ -104,7 +104,8 @@ and all must be truthy in order for the verification to pass::
 If either requirement returns False, then the user will not be allowed to access
 that route. However, if you have a more complicated requirement, such as a
 user must be logged in AND a user must be an admin OR a user must have the
-``'view_admin_panel'`` permission.
+``'view_admin_panel'`` permission, these can be difficult to express in an
+all-or-nothing evaluation strategy.
 
 To handle these situations, Flask-Allows exposes several helper requirements::
 
@@ -119,7 +120,10 @@ To handle these situations, Flask-Allows exposes several helper requirements::
 
 
 Strictly speaking, the outer ``And`` isn't necessary as the requirements will
-already be combined in an ``and`` fashion.
+already be combined in an ``and`` fashion but is presented for example sake.
+The ``And`` help is most useful when nested inside of an ``Or`` such as::
+
+    Or(user_is_admin, And(Has('view_admin_panel'), user_is_moderator))
 
 Flask-Allows also exposes a helper to invert the result of a requirement::