docs error - view_config decorators

[jvanasco]

The docs on view_config's decorators are wrong. https://github.com/Pylons/pyramid/blame/1.7-branch/docs/narr/viewconfig.rst#L241-L262 (I linked to blame, because github doesn't support linking to lines in RST otherwise)

The docs currently read:

``decorator``
  A :term:`dotted Python name` to a function (or the function itself) which
  will be used to decorate the registered :term:`view callable`.  The decorator
  function will be called with the view callable as a single argument.  The
  view callable it is passed will accept ``(context, request)``.  The decorator
  must return a replacement view callable which also accepts ``(context,
  request)``. The ``decorator`` may also be an iterable of decorators, in which
  case they will be applied one after the other to the view, in reverse order.
  For example::

    @view_config(..., decorator=(decorator2, decorator1))
    def myview(request):
      ...

  Is similar to doing::

    @view_config(...)
    @decorator2
    @decorator1
    def myview(request):
      ...

However, the current request processing logic has the decorators wrapping the view AND response adapter (http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/router.html)

The "is similar" logic of normal wrapping with @decorator2, @decorator1 will not wrap the response adapter as well.

For example:

@view_config(route_name='test_1',
             renderer='../templates/test_1.mako'
             decorator=decorator_1
)
def test_1(request):
    log.debug('test_1')
    return {'project': 'ViewTest'}

@view_config(route_name='test_2',
             renderer='../templates/test_2.mako'
)
@decorator_2
def test_2(request):
    log.debug('test_2')
    return {'project': 'ViewTest'}

decorator_1 will receive the response with rendered output of test_1.mako
decorator_2 will only wrap the test_2 function, receives the dict {'project': 'ViewTest'} and it's return value will be passed onto test_2.mako

I don't have a suggestion for better docs, but they are not similar and different hooks.

[mmerickel]

Feel free to submit some language that clarifies the difference in the return values of the different functions. The decorator argument itself is almost completely obsoleted by view derivers in pyramid 1.7.