Zero in on making docs render properly.

2 files changed, 19 insertions, 17 deletions

diff --git a/repoze/bfg/router.py b/repoze/bfg/router.py
index e9e0f175a..9dd590fc0 100644
--- a/repoze/bfg/router.py
+++ b/repoze/bfg/router.py
@@ -58,7 +58,8 @@ def make_app(root_policy, package=None, filename='configure.zcml'):
     application.  'root_policy' must be a callable that accepts an
     environ and returns a graph root object.  'package' is the
     dotted-Python-path packagename of the application, 'filename' is
-    the ZCML file that should be parsed to create the view registry."""
+    the ZCML file (relative to the package path) that should be parsed
+    to create the view registry."""
     from repoze.bfg.registry import makeRegistry
     registry = makeRegistry(filename, package)
     return Router(root_policy, registry)
diff --git a/repoze/bfg/security.py b/repoze/bfg/security.py
index 6ee2d7d95..9ed3db538 100644
--- a/repoze/bfg/security.py
+++ b/repoze/bfg/security.py
@@ -15,12 +15,13 @@ Deny = 'Deny'
 
 def has_permission(permission, context, request):
     """ Provided a permission (a string or unicode object), a context
-    (a model instance) and a request object, return ``Allowed`` if the
-    permission is granted in this context to the user implied by the
-    request. Return ``Denied`` if this permission is not granted in
-    this context to this user.  This delegates to the current security
-    policy.  Return True unconditionally if no security policy has
-    been configured in this application."""
+    (a model instance) and a request object, return an instance of
+    ``Allowed`` if the permission is granted in this context to the
+    user implied by the request. Return an instance of ``Denied`` if
+    this permission is not granted in this context to this user.  This
+    delegates to the current security policy.  Return True
+    unconditionally if no security policy has been configured in this
+    application."""
     policy = queryUtility(ISecurityPolicy)
     if policy is None:
         return True
@@ -120,11 +121,11 @@ class PermitsResult:
         return msg
 
 class Denied(PermitsResult):
-    """ The value type returned by an ACL denial.  It evaluates equal
-    to all boolean false types.  It also has attributes which indicate
-    which acl, ace, permission, principals, and context were involved
-    in the request.  Its __str__ method prints a summary of these
-    attributes for debugging purposes. """
+    """ An instance of ``Denied`` is returned by an ACL denial.  It
+    evaluates equal to all boolean false types.  It also has
+    attributes which indicate which acl, ace, permission, principals,
+    and context were involved in the request.  Its __str__ method
+    prints a summary of these attributes for debugging purposes."""
     def __nonzero__(self):
         return False
 
@@ -133,11 +134,11 @@ class Denied(PermitsResult):
             return True
 
 class Allowed(PermitsResult):
-    """ The value type returned by an ACL denial.  It evaluates equal
-    to all boolean true types.  It also has attributes which indicate
-    which acl, ace, permission, principals, and context were involved
-    in the request.  Its __str__ method prints a summary of these
-    attributes for debugging purposes. """
+    """ An instance of ``Allowed`` is returned by an ACL allow.  It
+    evaluates equal to all boolean true types.  It also has attributes
+    which indicate which acl, ace, permission, principals, and context
+    were involved in the request.  Its __str__ method prints a summary
+    of these attributes for debugging purposes."""
     def __nonzero__(self):
         return True