Update handlers section to not reference __exposed__, and mention

resource spec.

1 files changed, 19 insertions, 8 deletions

diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst
index f9b073dae..dcb199bbc 100644
--- a/docs/narr/handlers.rst
+++ b/docs/narr/handlers.rst
@@ -28,7 +28,7 @@ handler configuration.
 
 The :meth:`pyramid.configuration.Configurator.add_handler` method will scan
 the handler class and automatically set up views for methods that are
-auto-exposed or have an ``__exposed__`` attribute. The
+auto-exposed or were decorated with :class:`~pyramid.view.action`. The
 :class:`~pyramid.view.action` decorator is used to setup additional view
 configuration information for individual class methods, and can be used
 repeatedly for a single method to register multiple view configurations that
@@ -89,9 +89,22 @@ Using :meth:`~pyramid.configuration.Configurator.add_handler`
 
 When calling :meth:`~pyramid.configuration.Configurator.add_handler`, an
 ``action`` is required in either the route pattern or as a keyword argument,
-but **cannot appear in both places**. Additional keyword arguments are passed
+but **cannot appear in both places**. A ``handler`` argument must also be
+supplied, which can be either a :term:`resource specification` or a Python
+reference to the handler class. Additional keyword arguments are passed
 directly through to :meth:`pyramid.configuration.Configurator.add_route`.
 
+For example:
+
+.. code-block:: python
+    
+    config.add_handler('hello', '/hello/:action',
+                       handler='mypackage.handlers:MyHandler')
+
+In larger applications, it is advised to use a :term:`resource specification`
+with :meth:`~pyramid.configuration.Configurator.add_handler` to avoid having
+to import every handler class.
+
 Multiple :meth:`~pyramid.configuration.Configurator.add_handler` calls can
 specify the same handler, to register specific route names for different
 handler/action combinations. For example:
@@ -115,9 +128,7 @@ view configurations being registered.
 When :meth:`~pyramid.configuration.Configurator.add_handler` runs, every
 method in the handler class will be searched and a view registered if the
 method name matches the ``__autoexpose__`` regular expression, or if the
-method has a ``__exposed__`` attribute. The ``__exposed__`` attribute for a
-function should never be set manually, the :class:`~pyramid.view.action`
-decorator will configure it.
+method was decorated with :class:`~pyramid.view.action`.
 
 Auto-exposed Views
 ------------------
@@ -152,13 +163,13 @@ Action Decorator
 ----------------
 
 The :class:`~pyramid.view.action` decorator registers view configuration
-information on the method's ``__exposed__`` attribute, which is used by
+information on the handler method which is used by
 :meth:`~pyramid.configuration.Configurator.add_handler` to setup the view
 configuration.
 
 All keyword arguments are recorded, and passed to
-:meth:`pyramid.configuration.Configurator.add_view`. Any valid keyword
-arguments for :meth:`pyramid.configuration.Configurator.add_view` can thus be
+:meth:`!pyramid.configuration.Configurator.add_view`. Any valid keyword
+arguments for :meth:`!pyramid.configuration.Configurator.add_view` can thus be
 used with the :class:`~pyramid.view.action` decorator to further restrict when
 the view will be called.