1 files changed, 45 insertions, 14 deletions
diff --git a/src/zope/browser/README.txt b/src/zope/browser/README.txt
index 4db3d51..d6ae4d2 100644
--- a/src/zope/browser/README.txt
+++ b/src/zope/browser/README.txt
@@ -1,23 +1,54 @@
-======
-README
-======
+IView
+-----
 
-This package provides shared browser components for Zope 3.
+Views adapt both a context and a request.
 
+There is not much we can test except that ``IView`` is importable
+and an interface:
+
+.. doctest::
+
+  >>> from zope.interface import Interface
+  >>> from zope.browser.interfaces import IView
+  >>> Interface.providedBy(IView)
+  True
+
+IBrowserView
+-------------
+
+Browser views are views specialized for requests from a browser (e.g.,
+as distinct from WebDAV, FTP, XML-RPC, etc.).
+
+There is not much we can test except that ``IBrowserView`` is importable
+and an interface derived from ``IView``:
+
+.. doctest::
+
+  >>> from zope.interface import Interface
+  >>> from zope.browser.interfaces import IBrowserView
+  >>> Interface.providedBy(IBrowserView)
+  True
+  >>> IBrowserView.extends(IView)
+  True
 
 ITerms
 ------
 
-The ITerms interface is used as a base for ISource widget implementations. This
-interfaces get used by zope.app.form and was initially defined in
-zope.app.form.browser.interfaces.py. This makes it impossible to use for other
-packages like z3c.form wihtout to depend on zope.app.form. Moving such base
-components or interfaces to zope.browser will make it possible to share such
-base components.
+The ``ITerms`` interface is used as a base for ``ISource`` widget
+implementations.  This interfaces get used by ``zope.app.form`` and was
+initially defined in ``zope.app.form.browser.interfaces``, which made it
+impossible to use for other packages like ``z3c.form`` wihtout depending on
+``zope.app.form``.
+
+Moving such base components / interfaces to ``zope.browser`` makes it
+possible to share them without undesirable dependencies.
+
+There is not much we can test except that ITerms is importable
+and an interface:
 
-There is not much we can test except that ITerms is importable and an interface:
+.. doctest::
 
-  >>> import zope.interface
-  >>> from zope.browser import interfaces
-  >>> zope.interface.Interface.providedBy(interfaces.ITerms)
+  >>> from zope.interface import Interface
+  >>> from zope.browser.interfaces import ITerms
+  >>> Interface.providedBy(ITerms)
   True