Improve documentation on `BaseHTTPMiddleware` (#1655)

Co-authored-by: Adrian Garcia Badaracco <1755071+adriangb@users.noreply.github.com>

diff --git a/docs/middleware.md b/docs/middleware.md
index 817f63662be11b21e245d3ec1de0a4585647d155..cecdafaaf119540b2682557e7c4398c48110bd79 100644 (file)
--- a/docs/middleware.md
+++ b/docs/middleware.md
@@ -229,9 +229,8 @@ around explicitly, rather than mutating the middleware instance.
 !!! bug
     Currently, the `BaseHTTPMiddleware` has some known issues:
 
-    - It's not possible to use multiple `BaseHTTPMiddleware` based middlewares.
-    - It's not possible to use `BackgroundTasks` with `BaseHTTPMiddleware`.
-    - Using `BaseHTTPMiddleware` will prevent changes to `contextlib.ContextVar`s from propagating upwards. That is, if you set a value for a `ContextVar` in your endpoint and try to read it from a middleware you will find that the value is not the same value you set in your endpoint (see [this test](https://github.com/encode/starlette/blob/621abc747a6604825190b93467918a0ec6456a24/tests/middleware/test_base.py#L192-L223) for an example of this behavior).
+    - It's not possible to use `BackgroundTasks` with `BaseHTTPMiddleware`. Check [#1438](https://github.com/encode/starlette/issues/1438) for more details.
+    - Using `BaseHTTPMiddleware` will prevent changes to [`contextlib.ContextVar`](https://docs.python.org/3/library/contextvars.html#contextvars.ContextVar)s from propagating upwards. That is, if you set a value for a `ContextVar` in your endpoint and try to read it from a middleware you will find that the value is not the same value you set in your endpoint (see [this test](https://github.com/encode/starlette/blob/621abc747a6604825190b93467918a0ec6456a24/tests/middleware/test_base.py#L192-L223) for an example of this behavior).
 
 ## Using middleware in other frameworks