Update doc about allowed return value types of decorated functions

flask_rest_api/etag.py

@@ -51,6 +51,10 @@ def view_func(...):
                 def view_func(...):
                     ...
 
+        The ``etag`` decorator expects the decorated view function to return a
+        ``Response`` object. It is the case if it is decorated with the
+        ``response`` decorator.
+
         See :doc:`ETag <etag>`.
         """
         if etag_schema is None or isinstance(etag_schema, (type, Schema)):
@@ -177,11 +181,12 @@ def set_etag(self, etag_data, etag_schema=None):
 
         Raise 304 if ETag identical to If-None-Match header
 
-        Can be called from resource code. If not called, ETag will be computed
-        by default from response data before sending response.
+        Must be called from resource code, unless the view function is
+        decorated with the ``response`` decorator, in which case the ETag is
+        computed by default from response data if ``set_etag`` is not called.
 
         Logs a warning if called in a method other than one of
-        GET, HEAD, POST, PUT, PATCH
+        GET, HEAD, POST, PUT, PATCH.
         """
         if request.method not in self.METHODS_ALLOWING_SET_ETAG:
             current_app.logger.warning(

flask_rest_api/pagination.py

@@ -135,6 +135,10 @@ def paginate(self, pager=None, *,
 
         Otherwise, pagination is handled in the view function.
 
+        The decorated function may return a tuple including status and/or
+        headers, like a typical flask view function. It may not return a
+        ``Response`` object.
+
         See :doc:`Pagination <pagination>`.
         """
         if page is None:

flask_rest_api/response.py

@@ -24,6 +24,14 @@ def response(self, schema=None, *, code=200, description=''):
             returned from the view function.
         :param str descripton: Description of the response.
 
+        The decorated function is expected to return the same types of value
+        than a typical flask view function, except the body part may be an
+        object or a list of objects to serialize with the schema, rather than
+        a ``string``.
+
+        If the decorated function returns a ``Response`` object, the ``schema``
+        and ``code`` parameters are only used to document the resource.
+
         See :doc:`Response <response>`.
         """
         if isinstance(schema, type):