Document how state works with merge and nest

[davidpdrsn]

Gotten a few questions about how states work with merge and nest. Things like whether the state needs to be passed to each router and whether the state of the inner routers is dropped. This is something we should document.

[genusistimelord]

Yeah I noticed this when using AxumFlash and passing the config as the State. I had to change my Routing functions to take in the State to set them individually.

Router::with_state(flash_config.clone())
        .route("/", get(root))
       .merge(main_routes(flash_config.clone()))

which results in

pub fn main_routes(config: axum_flash::Config) -> Router<axum_flash::Config> {
    Router::with_state(config)
        .route("/main", get(main_page))
}

[davidpdrsn]

#1368 is making things more flexible. When that is in I'll write some docs for it.

[davidpdrsn]

I think we're in a good place in terms for docs. We can expand things when people ask questions but for now I'll close this.

[jimmycuadra]

I think the docs could still be improved for this. I looked in these three places to try to figure this out (none of which explain it) before I found the API docs for Router::inherit_state:

• The "Sharing state with handlers" section of the root API documentation page
• API docs for axum::extract::State
• The "Routing" section of the root API documentation page

I think it's worth explaining directly in the documentation for State or at the very least linking to Router::inherit_state from there.

[davidpdrsn]

Good idea. Do you wanna make a pr?