Merge pull request #2258 from davidism/preprocess_request-docs

Clean up preprocess_request docs

flask/app.py

@@ -415,17 +415,16 @@ class Flask(_PackageBoundObject):
         #: .. versionadded:: 0.9
         self.url_build_error_handlers = []
 
-        #: A dictionary with lists of functions that should be called at the
+        #: A dictionary with lists of functions that will be called at the
-        #: beginning of the request.  The key of the dictionary is the name of
+        #: beginning of each request. The key of the dictionary is the name of
-        #: the blueprint this function is active for, ``None`` for all requests.
+        #: the blueprint this function is active for, or ``None`` for all
-        #: This can for example be used to open database connections or
+        #: requests. To register a function, use the :meth:`before_request`
-        #: getting hold of the currently logged in user.  To register a
+        #: decorator.
-        #: function here, use the :meth:`before_request` decorator.
         self.before_request_funcs = {}
 
-        #: A lists of functions that should be called at the beginning of the
+        #: A list of functions that will be called at the beginning of the
-        #: first request to this instance.  To register a function here, use
+        #: first request to this instance. To register a function, use the
-        #: the :meth:`before_first_request` decorator.
+        #: :meth:`before_first_request` decorator.
         #:
         #: .. versionadded:: 0.8
         self.before_first_request_funcs = []
@@ -457,12 +456,11 @@ class Flask(_PackageBoundObject):
         #: .. versionadded:: 0.9
         self.teardown_appcontext_funcs = []
 
-        #: A dictionary with lists of functions that can be used as URL
+        #: A dictionary with lists of functions that are called before the
-        #: value processor functions.  Whenever a URL is built these functions
+        #: :attr:`before_request_funcs` functions. The key of the dictionary is
-        #: are called to modify the dictionary of values in place.  The key
+        #: the name of the blueprint this function is active for, or ``None``
-        #: ``None`` here is used for application wide
+        #: for all requests. To register a function, use
-        #: callbacks, otherwise the key is the name of the blueprint.
+        #: :meth:`url_value_preprocessor`.
-        #: Each of these functions has the chance to modify the dictionary
         #:
         #: .. versionadded:: 0.7
         self.url_value_preprocessors = {}
@@ -1314,11 +1312,13 @@ class Flask(_PackageBoundObject):
     @setupmethod
     def before_request(self, f):
         """Registers a function to run before each request.
+        
+        For example, this can be used to open a database connection, or to load
+        the logged in user from the session.
 
-        The function will be called without any arguments.
+        The function will be called without any arguments. If it returns a
-        If the function returns a non-None value, it's handled as
+        non-None value, the value is handled as if it was the return value from
-        if it was the return value from the view and further
+        the view, and further request handling is stopped.
-        request handling is stopped.
         """
         self.before_request_funcs.setdefault(None, []).append(f)
         return f
@@ -1437,9 +1437,17 @@ class Flask(_PackageBoundObject):
 
     @setupmethod
     def url_value_preprocessor(self, f):
-        """Registers a function as URL value preprocessor for all view
+        """Register a URL value preprocessor function for all view
-        functions of the application.  It's called before the view functions
+        functions in the application. These functions will be called before the
-        are called and can modify the url values provided.
+        :meth:`before_request` functions.
+        
+        The function can modify the values captured from the matched url before
+        they are passed to the view. For example, this can be used to pop a
+        common language code value and place it in ``g`` rather than pass it to
+        every view.
+        
+        The function is passed the endpoint name and values dict. The return
+        value is ignored.
         """
         self.url_value_preprocessors.setdefault(None, []).append(f)
         return f
@@ -1877,16 +1885,16 @@ class Flask(_PackageBoundObject):
         raise error
 
     def preprocess_request(self):
-        """Called before the actual request dispatching and will
+        """Called before the request is dispatched. Calls
-        call each :meth:`before_request` decorated function, passing no
+        :attr:`url_value_preprocessors` registered with the app and the
-        arguments.
+        current blueprint (if any). Then calls :attr:`before_request_funcs`
-        If any of these functions returns a value, it's handled as
+        registered with the app and the blueprint.
-        if it was the return value from the view and further
+        
-        request handling is stopped.
+        If any :meth:`before_request` handler returns a non-None value, the
-
+        value is handled as if it was the return value from the view, and
-        This also triggers the :meth:`url_value_preprocessor` functions before
+        further request handling is stopped.
-        the actual :meth:`before_request` functions are called.
         """
+
         bp = _request_ctx_stack.top.request.blueprint
 
         funcs = self.url_value_preprocessors.get(None, ())