Cross-refs and cleanups for proxy.py/rst

3 files changed, 27 insertions, 9 deletions

diff --git a/docs/api/protectclass.rst b/docs/api/protectclass.rst
index fdc266b..d5cd12d 100644
--- a/docs/api/protectclass.rst
+++ b/docs/api/protectclass.rst
@@ -1,6 +1,5 @@
-:mod:`zope.security.protectclass`
-=================================
+============================
+ zope.security.protectclass
+============================
 
 .. automodule:: zope.security.protectclass
-   :members:
-   :member-order: bysource
diff --git a/docs/api/proxy.rst b/docs/api/proxy.rst
index 665912a..733d5df 100644
--- a/docs/api/proxy.rst
+++ b/docs/api/proxy.rst
@@ -1,14 +1,21 @@
-:mod:`zope.security.proxy`
-===============================
+=====================
+ zope.security.proxy
+=====================
+
+.. currentmodule:: zope.security.proxy
 
 .. testsetup::
 
    from zope.component.testing import setUp
    setUp()
 
-.. autofunction:: zope.security.proxy.getTestProxyItems
+.. autofunction:: getChecker
+
+.. autofunction:: removeSecurityProxy
+
+.. autofunction:: getTestProxyItems
 
-.. autofunction:: zope.security.proxy.isinstance
+.. autofunction:: isinstance
 
 .. doctest::
 
@@ -35,7 +42,9 @@
    >>> isinstance(ProxyFactory(c), C1)
    True
 
+.. autoclass:: Proxy
 
+.. autoclass:: ProxyPy
 
 .. testcleanup::
 
diff --git a/src/zope/security/proxy.py b/src/zope/security/proxy.py
index 8f6d7c3..55f54f6 100644
--- a/src/zope/security/proxy.py
+++ b/src/zope/security/proxy.py
@@ -60,6 +60,16 @@ def _fmt_address(obj):
 
 
 class ProxyPy(PyProxyBase):
+    """
+    The pure-Python reference implementation of a security proxy.
+
+    This should normally not be created directly, instead use the
+    :func:`~.ProxyFactory`.
+
+    You can choose to use this implementation instead of the C implementation
+    by default by setting the ``PURE_PYTHON`` environment variable before
+    :mod:`zope.security` is imported.
+    """
     __slots__ = ('_wrapped', '_checker')
 
     def __new__(cls, value, checker):
@@ -394,7 +404,7 @@ def getTestProxyItems(proxy):
 
 
 def isinstance(object, cls):
-    """Test whether an object is an instance of a type.
+    """Test whether an *object* is an instance of a type.
 
     This works even if the object is security proxied.
     """