okay maybe provide some info in the docstrings

src/flask_allows/allows.py

@@ -42,8 +42,7 @@ def requires(self, *requirements, **opts):
         """
         Decorator to enforce requirements on routes
 
-        :param requirements iterable: Collection of requirements
-            to impose on view
+        :param requirements: Collection of requirements to impose on view
         :param throws optional: Exception to throw for this route, if provided
             it takes precedence over the exception stored on the instance
         :param on_fail optional: Value or function to use as the on_fail for this route, takes
@@ -100,8 +99,7 @@ def fulfill(self, requirements, identity=None):
         Checks that the provided or current identity meets each requirement
         passed to this method.
 
-        :param requirements: A collection of requirements to check the identity
-            against.
+        :param requirements: The requirements to check the identity against.
         :param identity: Optional. Identity to use in place of the current
             identity.
         """

src/flask_allows/permission.py

@@ -4,9 +4,12 @@
 
 class Permission(object):
     """
-    Used to check requirements as a boolean or context manager.
+    Used to check requirements as a boolean or context manager. When used as a
+    boolean, it only runs the requirements and returns the raw boolean result.
+    When used as a context manager, it runs both the check and the failure
+    handlers if the requirements are not met.
 
-    :param requirements iterable: Collection of requirements to check against
+    :param requirements: The requirements to check against
     :param throws optional: Exception to throw when used as a context manager,
         if provided it takes precedence over the exception stored on the current
         application's registered :class:`~flask_allows.allows.Allows` instance

src/flask_allows/requirements.py

@@ -38,6 +38,24 @@ class ConditionalRequirement(Requirement):
     Combinations may also nested::
 
         Or(user_is_admin, And(user_is_moderator, HasPermission('view_admin')))
+
+    Custom combinators may be built by creating an instance of ConditionalRequirement
+    and supplying any combination of its keyword parameters
+
+    This class is also exported under the ``C`` alias.
+
+
+    :param requirements: Collection of requirements to combine into
+        one logical requirement
+    :param op: Optional, Keyword only. A binary operator that accepts two
+        booleans and returns a boolean.
+    :param until: Optional, Keyword only. A boolean to short circuit on (e.g.
+        if provided with True, then the first True evaluation to return from a
+        requirement ends verification)
+    :param negated: Optional, Keyword only. If true, then the
+        ConditionalRequirement will return the opposite of what it actually
+        evaluated to (e.g. ``ConditionalRequirement(user_logged_in, negated=True)``
+        returns False if the user is logged in)
     """
 
     def __init__(self, *requirements, **kwargs):
@@ -48,14 +66,33 @@ def __init__(self, *requirements, **kwargs):
 
     @classmethod
     def And(cls, *requirements):
+        """
+        Short cut helper to construct a combinator that uses
+        :meth:`operator.and_` to reduce requirement results and stops
+        evaluating on the first False.
+
+        This is also exported at the module level as ``And``
+        """
         return cls(*requirements, op=operator.and_, until=False)
 
     @classmethod
     def Or(cls, *requirements):
+        """
+        Short cut helper to construct a combinator that uses
+        :meth:`operator.or_` to reduce requirement results and stops evaluating
+        on the first True.
+
+        This is also exported at the module level as ``Or``
+        """
         return cls(*requirements, op=operator.or_, until=True)
 
     @classmethod
     def Not(cls, *requirements):
+        """
+        Shortcut helper to negate a requirement or requirements.
+
+        This is also exported at the module as ``Not``
+        """
         return cls(*requirements, negated=True)
 
     def fulfill(self, user, request):

src/flask_allows/views.py

@@ -18,7 +18,7 @@ def a_view():
         class AView(View):
             decorators = [requires(MyRequirement())]
 
-    :param requirements: A collection of requirements to apply to this route
+    :param requirements: The requirements to apply to this route
     :param throws: Optional. Exception or exception instance to throw if
         authorization fails.
     :param on_fail: Optional. Value or function to use when authorization