docs fixes

1 files changed, 19 insertions, 10 deletions

diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index 83734be9f..a24c44f29 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -303,13 +303,22 @@ The ``__resource_url__`` hook is passed two arguments: ``request`` and
 two keys:
 
 ``physical_path``
-   The "physical path" computed for the resource, as defined by
-   ``pyramid.traversal.resource_path(resource)``.
+   A string representing the "physical path" computed for the resource, as
+   defined by ``pyramid.traversal.resource_path(resource)``.  It will begin
+   and end with a slash.
 
 ``virtual_path``
-   The "virtual path" computed for the resource, as defined by
-   :ref:`virtual_root_support`.  This will be identical to the physical path
-   if virtual rooting is not enabled.
+   A string representing the "virtual path" computed for the resource, as
+   defined by :ref:`virtual_root_support`.  This will be identical to the
+   physical path if virtual rooting is not enabled.  It will begin and end
+   with a slash.
+
+``app_url``
+  A string representing the application URL generated during
+  ``request.resource_url``.  It will not end with a slash.  It represents a
+  potentially customized URL prefix, containing potentially custom scheme,
+  host and port information passed by the user to ``request.resource_url``.
+  It should be preferred over use of ``request.application_url``.
 
 The ``__resource_url__`` method of a resource should return a string
 representing a URL.  If it cannot override the default, it should return
@@ -322,16 +331,16 @@ Here's an example ``__resource_url__`` method.
 
    class Resource(object):
        def __resource_url__(self, request, info):
-           return request.application_url + info['virtual_path']
+           return info['app_url'] + info['virtual_path']
 
 The above example actually just generates and returns the default URL, which
-would have been what was returned anyway, but your code can perform arbitrary
-logic as necessary.  For example, your code may wish to override the hostname
-or port number of the generated URL.
+would have been what was generated by the default ``resource_url`` machinery,
+but your code can perform arbitrary logic as necessary.  For example, your
+code may wish to override the hostname or port number of the generated URL.
 
 Note that the URL generated by ``__resource_url__`` should be fully
 qualified, should end in a slash, and should not contain any query string or
-anchor elements (only path elements) to work best with
+anchor elements (only path elements) to work with
 :meth:`~pyramid.request.Request.resource_url`.
 
 .. index::