Documentation cleanups per review.

4 files changed, 66 insertions, 28 deletions

diff --git a/src/zope/traversing/api.py b/src/zope/traversing/api.py
index c9b0cb3..b457e33 100644
--- a/src/zope/traversing/api.py
+++ b/src/zope/traversing/api.py
@@ -21,7 +21,9 @@ from zope.interface import moduleProvides
 from zope.location.interfaces import ILocationInfo, IRoot
 from zope.traversing.interfaces import ITraversalAPI, ITraverser
 
-
+# The authoritative documentation for these functions
+# is in this interface. Later, we replace all our docstrings
+# with those defined in the interface.
 moduleProvides(ITraversalAPI)
 __all__ = tuple(ITraversalAPI)
 
@@ -31,6 +33,8 @@ _marker = object()
 def joinPath(path, *args):
     """
     Join the given relative paths to the given path.
+
+    See `ITraversalAPI` for details.
     """
 
     if not args:
@@ -49,6 +53,8 @@ def joinPath(path, *args):
 def getPath(obj):
     """
     Returns a string representing the physical path to the object.
+
+    See `ITraversalAPI` for details.
     """
     return ILocationInfo(obj).getPath()
 
@@ -56,12 +62,17 @@ def getPath(obj):
 def getRoot(obj):
     """
     Returns the root of the traversal for the given object.
+
+    See `ITraversalAPI` for details.
     """
     return ILocationInfo(obj).getRoot()
 
 
 def traverse(object, path, default=_marker, request=None):
     """
+    Traverse *path* relative to the given object.
+
+    See `ITraversalAPI` for details.
     """
     traverser = ITraverser(object)
     if default is _marker:
@@ -72,6 +83,8 @@ def traverse(object, path, default=_marker, request=None):
 def traverseName(obj, name, default=_marker, traversable=None, request=None):
     """
     Traverse a single step 'name' relative to the given object.
+
+    See `ITraversalAPI` for details.
     """
     further_path = []
     if default is _marker:
@@ -88,7 +101,9 @@ def traverseName(obj, name, default=_marker, traversable=None, request=None):
 
 def getName(obj):
     """
-    Get the name an object was traversed via
+    Get the name an object was traversed via.
+
+    See `ITraversalAPI` for details.
     """
     return ILocationInfo(obj).getName()
 
@@ -96,6 +111,8 @@ def getName(obj):
 def getParent(obj):
     """
     Returns the container the object was traversed via.
+
+    See `ITraversalAPI` for details.
     """
     try:
         location_info = ILocationInfo(obj)
@@ -123,6 +140,8 @@ def getParents(obj):
     """
     Returns a list starting with the given object's parent followed by
     each of its parents.
+
+    See `ITraversalAPI` for details.
     """
     return ILocationInfo(obj).getParents()
 
@@ -158,6 +177,8 @@ def canonicalPath(path_or_object):
     """
     Returns a canonical absolute unicode path for the given path or
     object.
+
+    See `ITraversalAPI` for details.
     """
     if isinstance(path_or_object, six.string_types):
         path = path_or_object
diff --git a/src/zope/traversing/browser/interfaces.py b/src/zope/traversing/browser/interfaces.py
index df468ce..21a6a24 100644
--- a/src/zope/traversing/browser/interfaces.py
+++ b/src/zope/traversing/browser/interfaces.py
@@ -46,7 +46,7 @@ class IAbsoluteURL(Interface):
 
 class IAbsoluteURLAPI(Interface):
     """
-    The api to compute absolute URLs of objects.
+    The API to compute absolute URLs of objects.
 
     Provided by :mod:`zope.traversing.browser.absoluteurl`
     """
diff --git a/src/zope/traversing/interfaces.py b/src/zope/traversing/interfaces.py
index ad3b410..e707282 100644
--- a/src/zope/traversing/interfaces.py
+++ b/src/zope/traversing/interfaces.py
@@ -102,7 +102,8 @@ class ITraversalAPI(Interface):
         """
 
     def traverse(object, path, default=None, request=None):
-        """Traverse *path* relative to the given object.
+        """
+        Traverse *path* relative to the given object.
 
         :param str path: a string with path segments separated by '/'.
         :keyword request: Passed in when traversing from
@@ -118,7 +119,8 @@ class ITraversalAPI(Interface):
 
     def traverseName(obj, name, default=None, traversable=None,
                      request=None):
-        """Traverse a single step *name* relative to the given object.
+        """
+        Traverse a single step *name* relative to the given object.
 
         *name* must be a string.  '.' and '..' are treated specially,
         as well as names starting with '@' or '+'.  Otherwise *name*
@@ -136,11 +138,13 @@ class ITraversalAPI(Interface):
         """
 
     def getName(obj):
-        """Get the name an object was traversed via
+        """
+        Get the name an object was traversed via.
         """
 
     def getParent(obj):
-        """Returns the container the object was traversed via.
+        """
+        Returns the container the object was traversed via.
 
         Returns `None` if the object is a containment root.
 
@@ -168,17 +172,25 @@ class ITraversalAPI(Interface):
 
 
 class IPathAdapter(Interface):
-    """Marker interface for adapters to be used in paths
+    """
+    Marker interface for adapters to be used in paths.
+
+    .. seealso:: :class:`.namespace.adapter`.
     """
 
 
 class IEtcNamespace(Interface):
-    """Marker for utility registrations in the ++etc++ namespace
+    """
+    Marker for utility registrations in the ``++etc++`` namespace.
+
+    .. seealso:: :class:`.namespace.etc`
     """
 
 
 class IBeforeTraverseEvent(IObjectEvent):
-    """An event which gets sent on publication traverse"""
+    """
+    An event which gets sent on publication traverse.
+    """
 
     request = Attribute("The current request")
 
diff --git a/src/zope/traversing/namespace.py b/src/zope/traversing/namespace.py
index ef296e3..8cb2527 100644
--- a/src/zope/traversing/namespace.py
+++ b/src/zope/traversing/namespace.py
@@ -14,9 +14,14 @@
 """
 URL Namespace Implementations
 
-A URL Namespace is usually a path segment that looks like ``++ns++name``.
-(It can also look like ``@@name``, which is a
-shortcut for ``++view++name``. See :func:`nsParse` for details.)
+URL namespaces are an extensible mechanism to provide additional
+control over traversal (for example, disambiguating :class:`item
+<item>` versus :class:`attribute <attr>` access) or access to an
+additional set of traversable names (such as :class:`registered views
+<view>` or :class:`path adapters <adapter>`).  This mechanism is used
+for path segments that look like ``++ns++name``.  (It is also used for
+segments like ``@@name``, which is a shortcut for ``++view++name``.
+See :func:`nsParse` for details.)
 
 ``ns`` is the name of the namespace (a named, registered adapter that
 implements `ITraversable`) and ``name`` is the name to traverse to in
@@ -25,34 +30,34 @@ that namespace.
 The function :func:`namespaceLookup` handles this process.
 
 If you configure this package by loading its ``configure.zcml`` using
-:mod:`zope.configuration.xmlconfig`, several namespaces are registered.  They
-are registered both as single adapters for any object, and as
-multi-adapters (views) for any object together with a
+:mod:`zope.configuration.xmlconfig`, several namespaces are
+registered.  They are registered both as single adapters for any
+object, and as multi-adapters (views) for any object together with a
 `zope.publisher.interfaces.IRequest`.  Those namespaces are:
 
 etc
-  Implemented in `etc`
+    Implemented in `etc`
 attribute
-  Implemented in `attr`
+    Implemented in `attr`
 adapter
-  Implemented in `adapter`
+    Implemented in `adapter`
 item
-  Implemented in `item`
+    Implemented in `item`
 acquire
-  Implemented in `acquire`
+    Implemented in `acquire`
 view
-  Implemented in `view`
+    Implemented in `view`
 resource
-  Implemented in `resource`
+    Implemented in `resource`
 lang
-  Implemented in `lang`
+    Implemented in `lang`
 skin
-  Implemented in `skin`
+    Implemented in `skin`
 vh
-  Implemented in `vh`
+    Implemented in `vh`
 debug
-  Implemented in `debug` (only if the ZCML feature ``devmode`` is enabled)
-  and only registered as a multi-adapter.
+    Implemented in `debug` (only if the ZCML feature ``devmode`` is enabled)
+    and only registered as a multi-adapter.
 """
 __docformat__ = 'restructuredtext'