Cross-refs and cleanups for permission.py/rst

zopefoundation · Sep 14, 2017 · b38c6b4 · b38c6b4
1 parent e504906
commit b38c6b4
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 11 deletions.
diff --git a/docs/api/permission.rst b/docs/api/permission.rst
@@ -1,5 +1,8 @@
-:mod:`zope.security.permission`
-===============================
+==========================
+ zope.security.permission
+==========================
+
+.. currentmodule:: zope.security.permission
 
 .. testsetup::
 
@@ -105,7 +108,7 @@ The non-public permissions 'x' and 'y' are string values:
    >>> print(vocab.getTermByToken('y').value)
    y
 
-However, the public permission value is CheckerPublic:
+However, the public permission value is :data:`~.CheckerPublic`:
 
 .. doctest::
 

diff --git a/src/zope/security/permission.py b/src/zope/security/permission.py
@@ -31,29 +31,36 @@
 
 @implementer(IPermission)
 class Permission(object):
+    """
+    Default implementation of :class:`zope.security.interfaces.IPermission`.
+    """
 
     def __init__(self, id, title="", description=""):
         self.id = id
         self.title = title
         self.description = description
 
 def checkPermission(context, permission_id):
-    """Check whether a given permission exists in the provided context.
+    """
+    Check whether a given permission object exists in the provided
+    context as a utility.
     """
     if permission_id is CheckerPublic:
         return
     if not queryUtility(IPermission, permission_id, context=context):
         raise ValueError("Undefined permission id", permission_id)
 
 def allPermissions(context=None):
-    """Get the ids of all defined permissions
+    """
+    Get the ids of all defined permission object utilities.
     """
     for name, _permission in getUtilitiesFor(IPermission, context):
         if name != zope_Public:
             yield name
 
 def PermissionsVocabulary(context=None):
-    """A vocabulary of permission IDs.
+    """
+    A vocabulary of permission IDs.
 
     Term values are permissions, while term tokens are permission IDs.
     """
@@ -65,13 +72,18 @@ def PermissionsVocabulary(context=None):
 directlyProvides(PermissionsVocabulary, IVocabularyFactory)
 
 def PermissionIdsVocabulary(context=None):
-    """A vocabulary of permission IDs.
+    """
+    A vocabulary of permission IDs.
 
-    Term values are the permission ID strings except for 'zope.Public', which
-    is the global permission CheckerPublic.
+    Term values are the permission ID strings except for
+    :data:`zope.Public
+    <zope.security.interfaces.PUBLIC_PERMISSION_NAME>`, which is the
+    global permission :data:`zope.security.checker.CheckerPublic`.
 
-    Term titles are the permission ID strings except for 'zope.Public', which
-    is shortened to 'Public'.
+    Term titles are the permission ID strings except for
+    :data:`zope.Public
+    <zope.security.interfaces.PUBLIC_PERMISSION_NAME>`, which is
+    shortened to 'Public'.
 
     Terms are sorted by title except for 'Public', which always appears as
     the first term.