adding additional flask example descriptions

mattmakai · mattmakai · commit 4c2da72e30c9 · 2020-07-09T08:22:31.000-04:00
diff --git a/content/pages/examples/flask/flask-globals-current-app.markdown b/content/pages/examples/flask/flask-globals-current-app.markdown
@@ -15,6 +15,10 @@ from the Werkzeug framework. `current_app` can be used to access data about the
 running application, including the configuration. This is useful for both
 developers using the framework and ones building extensions for Flask.
 
+You will often see `current_app` imported directly from `flask` instead
+of `flask.globals`. These imports are equivalent because `flask` is simply
+importing `current_app` from `flask.globals`.
+
 
 ## Example 1 from Flask AppBuilder
 [Flask-AppBuilder](https://github.com/dpgaspar/Flask-AppBuilder)
diff --git a/content/pages/examples/flask/flask-globals-g.markdown b/content/pages/examples/flask/flask-globals-g.markdown
@@ -12,6 +12,9 @@ an object for storing data during the
 [application context](https://flask.palletsprojects.com/en/1.1.x/appcontext/)
 of a running [Flask](/flask.html) web app.
 
+`g` can also be imported directly from the `flask` module instead
+of `flask.globals`, so you will often see that shortcut in example code.
+
 
 ## Example 1 from Flask AppBuilder
 [Flask-AppBuilder](https://github.com/dpgaspar/Flask-AppBuilder)
diff --git a/content/pages/examples/flask/flask-helpers-get-root-path.markdown b/content/pages/examples/flask/flask-helpers-get-root-path.markdown
@@ -7,7 +7,10 @@ sidebartitle: flask.helpers get_root_path
 meta: Python example code that shows how to use the get_root_path callable from the flask.helpers module of the Flask project.
 
 
-get_root_path is a callable within the flask.helpers module of the Flask project.
+[get_root_path](https://github.com/pallets/flask/blob/master/src/flask/helpers.py)
+is a function within the `flask.helpers` module of the [Flask](/flask.html)
+framework. `get_root_path` returns the filesystem path to a package
+or the current working directly if the path cannot be found.
 
 
 ## Example 1 from indico
diff --git a/content/pages/examples/flask/flask-helpers-make-response.markdown b/content/pages/examples/flask/flask-helpers-make-response.markdown
@@ -7,7 +7,17 @@ sidebartitle: flask.helpers make_response
 meta: Python example code that shows how to use the make_response callable from the flask.helpers module of the Flask project.
 
 
-make_response is a callable within the flask.helpers module of the Flask project.
+[make_response](https://github.com/pallets/flask/blob/master/src/flask/helpers.py)
+is a function in the `flask.helpers` module of the [Flask](/flask.html)
+[web framework](/web-framework.html). `make_response` is for adding additional
+HTTP headers to a response within a view's code. Sometimes views do not return
+a response object so it's unclear how to add headers to the response, which
+is where `make_response` is particularly useful in solving that specific
+problem.
+
+`make_response` can also be imported directly from the `flask` module
+instead of `flask.helpers` so you will typically see that shortcut
+in example code.
 
 
 ## Example 1 from Flask AppBuilder
diff --git a/content/pages/examples/flask/flask-helpers-send-file.markdown b/content/pages/examples/flask/flask-helpers-send-file.markdown
@@ -7,7 +7,17 @@ sidebartitle: flask.helpers send_file
 meta: Python example code that shows how to use the send_file callable from the flask.helpers module of the Flask project.
 
 
-send_file is a callable within the flask.helpers module of the Flask project.
+[send_file](https://github.com/pallets/flask/blob/master/src/flask/helpers.py)
+is function in the [Flask](/flask.html) `flask.helpers` module.
+`send_file` transfers the contents of a file to the client using the most
+efficient method available and configured in the Flask settings. It
+attempts to guess the correct mimetype to use but it can also be
+explicitly configured.
+
+Note that `send_file` is usually imported directly from `flask` instead of
+from `flask.helpers`, even though it is defined within the `helpers` module.
+It's the same function that is imported, but it's less characters to type
+when you leave off the `.helpers` part.
 
 
 ## Example 1 from Flask-VueJs-Template
diff --git a/content/pages/examples/flask/flask-helpers-url-for.markdown b/content/pages/examples/flask/flask-helpers-url-for.markdown
@@ -7,7 +7,15 @@ sidebartitle: flask.helpers url_for
 meta: Python example code that shows how to use the url_for callable from the flask.helpers module of the Flask project.
 
 
-url_for is a callable within the flask.helpers module of the Flask project.
+[url_for](https://github.com/pallets/flask/blob/master/src/flask/helpers.py)
+is function in the [Flask](/flask.html) `flask.helpers` module.
+`url_for` generates a URL to an endpoint using the method passed in
+as an argument.
+
+Note that `url_for` is typically imported directly from `flask` instead of
+from `flask.helpers`, even though it is defined within the `helpers` module.
+It is the same function that is imported, but it's less characters to type
+when you leave off the `.helpers` part.
 
 
 ## Example 1 from Flask AppBuilder
