Cross references and formatting for z.i.common.mapping

1 files changed, 42 insertions, 17 deletions

diff --git a/src/zope/interface/common/mapping.py b/src/zope/interface/common/mapping.py
index 139715f..1c5661a 100644
--- a/src/zope/interface/common/mapping.py
+++ b/src/zope/interface/common/mapping.py
@@ -11,7 +11,10 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""Mapping Interfaces
+"""Mapping Interfaces.
+
+Importing this module does *not* mark any standard classes
+as implementing any of these interfaces.
 """
 from zope.interface import Interface
 
@@ -22,7 +25,7 @@ class IItemMapping(Interface):
     def __getitem__(key):
         """Get a value for a key
 
-        A KeyError is raised if there is no value for the key.
+        A `KeyError` is raised if there is no value for the key.
         """
 
 
@@ -42,13 +45,13 @@ class IReadMapping(IItemMapping):
 
 class IWriteMapping(Interface):
     """Mapping methods for changing data"""
-    
+
     def __delitem__(key):
         """Delete a value from the mapping using the key."""
 
     def __setitem__(key, value):
         """Set a new item in the mapping."""
-        
+
 
 class IEnumerableMapping(IReadMapping):
     """Mapping objects whose items can be enumerated.
@@ -78,9 +81,16 @@ class IMapping(IWriteMapping, IEnumerableMapping):
     ''' Simple mapping interface '''
 
 class IIterableMapping(IEnumerableMapping):
+    """A mapping that has distinct methods for iterating
+    without copying.
+
+    On Python 2, a `dict` has these methods, but on Python 3
+    the methods defined in `IEnumerableMapping` already iterate
+    without copying.
+    """
 
     def iterkeys():
-        "iterate over keys; equivalent to __iter__"
+        "iterate over keys; equivalent to ``__iter__``"
 
     def itervalues():
         "iterate over values"
@@ -89,32 +99,47 @@ class IIterableMapping(IEnumerableMapping):
         "iterate over items"
 
 class IClonableMapping(Interface):
-    
+    """Something that can produce a copy of itself.
+
+    This is available in `dict`.
+    """
+
     def copy():
         "return copy of dict"
 
 class IExtendedReadMapping(IIterableMapping):
-    
+    """
+    Something with a particular method equivalent to ``__contains__``.
+
+    On Python 2, `dict` provides this method, but it was removed
+    in Python 3.
+    """
+
     def has_key(key):
-        """Tell if a key exists in the mapping; equivalent to __contains__"""
+        """Tell if a key exists in the mapping; equivalent to ``__contains__``"""
 
 class IExtendedWriteMapping(IWriteMapping):
-    
+    """Additional mutation methods.
+
+    These are all provided by `dict`.
+    """
+
     def clear():
         "delete all items"
-    
+
     def update(d):
         " Update D from E: for k in E.keys(): D[k] = E[k]"
-    
+
     def setdefault(key, default=None):
         "D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D"
-    
+
     def pop(k, *args):
-        """remove specified key and return the corresponding value
-        *args may contain a single default value, or may not be supplied.
-        If key is not found, default is returned if given, otherwise 
-        KeyError is raised"""
-    
+        """Remove specified key and return the corresponding value.
+
+        ``*args`` may contain a single default value, or may not be supplied.
+        If key is not found, default is returned if given, otherwise
+        `KeyError` is raised"""
+
     def popitem():
         """remove and return some (key, value) pair as a
         2-tuple; but raise KeyError if mapping is empty"""