Middleware composition docs

[devon-whil]

I think the middleware composition docs are somewhat confusing/misleading.
https://http4s.org/v0.23/middleware/#composing-services-with-middleware

val aggregateService = apiService <+> MyMiddle(service, "SomeKey" -> "SomeValue")

Note that goodRequest ran through the MyMiddle middleware and the Result had our header added to it. But, apiRequest did not go through the middleware and did not have the header added to it’s Result.

It's not obvious that if I reverse those then apiRequest would get the header added.

I don't use the Authentication middleware, but I stumbled my way to here to figure out how a request flows through a composition of routes and middlewares.

val service: HttpRoutes[IO] = middleware(spanishRoutes) <+> frenchRoutes

Call to the french routes will always return 401 (Unauthorized) as they are caught by the spanish routes.

I think information about how a request flows through a composition of routes and middlewares and how to apply middleware to specific routes would be helpful on the middleware page.