Improve State and Router docs

[jimmycuadra]

Per my comment in #1313, this improves discoverability of how State works with nested/merged Routers.

I made a few other minor documentation fixes while I was reading:

• Corrected the docs for Router::nest to say that it nests another Router rather than a Service. There is a separate function (Router::nest_service) for the latter.
• Changed one of the headings in nest.md to use more idiomatic English.
• Changed awkward phrasing under the "Sharing state with handlers" heading of the root documentation page.
• Removed a trailing period from one of three list items for consistency.

[davidpdrsn]

Thanks!

[jimmycuadra]

Before merging this I want to make sure what I wrote is actually correct and clear. After reading #1532 more closely I noticed:

Nesting (and merging) is only possible with a Router which doesn't have the state so it becomes more type safe.

After experimenting with nested routers, that statement seems more accurate, and this current sentence from the docs of Router::nest is misleading:

By default nest requires a Router with the same state type as the outer Router.

This doesn't really make sense, because you can't construct a Router with a non-unit state type to pass to Router::nest. For the nested router to have a non-unit state type, it must be constructed by calling with_state on a Router, which turns it into a RouterService, and hence must be nested with Router::nest_service, even if it happens to have the same state type as the outer router.

Am I understanding this correctly? If so, I'll need to revise the sentence I added and would also like to change the sentence from Router::nest's docs quoted above.

[jimmycuadra]

In fact, it seems that once you have a Router with a non-unit state type, you can't use Router::nest at all, because by definition a Router has () as its state type if it's not converted to a RouterService by calling with_state, no?

For example:

#[derive(Clone)]
struct AppState {
    count: u64,
}

pub fn api() -> RouterService {
    Router::<AppState>::new()
        .nest("/api/v1", api_v1())
        //               ^^^^^^^^ expected struct `AppState`, found `()`
        .fallback(fallback)
        .with_state(AppState { count: 0 })
}

fn api_v1() -> Router {
    Router::new()
        .route("/teams", get(get_teams))
        .route("/teams/:slug", get(get_team))
}

How can you possibly use Router::nest on a Router that you ultimately call with_state on with a non-unit state type?

[davidpdrsn]

In fact, it seems that once you have a Router with a non-unit state type, you can't use Router::nest at all, because by definition a Router has () as its state type if it's not converted to a RouterService by calling with_state, no?

Sure you can. Router::new doesn't always give a router whose state is (). The state type param only defaults to (). So unless specified it becomes ().

Just do:

fn api_v1() -> Router<AppState> {
    Router::new()
        .route("/teams", get(get_teams))
        .route("/teams/:slug", get(get_team))
}

[davidpdrsn]

Nesting routers with different state is possible by calling with_state to get a RouterService then using nest_service. Like shown here

[jimmycuadra]

Ah, I see. So the state type of a router is inferred if with_state is called on it, but it can also be specified with an explicit annotation, even if the router doesn't actually (or yet) contain state of that type.

I'm going to revise my changes tomorrow now that I understand it better. I suspect I won't be the last person to be confused by this without better docs. Thanks for the example!

[davidpdrsn]

Ah, I see. So the state type of a router is inferred if with_state is called on it, but it can also be specified with an explicit annotation, even if the router doesn't actually (or yet) contain state of that type.

Yes exactly.

I'm going to revise my changes tomorrow now that I understand it better. I suspect I won't be the last person to be confused by this without better docs. Thanks for the example!

Thanks!

[jimmycuadra]

Okay, I pushed up another commit which expands the docs on combining stateful routers. I added a section to the State docs that talks about it in detail, with links to the relevant methods. I moved the example of combining routers with different state types from Router::nest to Router::nest_service, because that's the function that actually makes that possible. I added relevant links between State, Router::nest, Router::nest_service, and Router::merge so it's easier to find all the information about how these types and methods differ and interact, regardless of which one you navigate to first. Ready for another review!

[davidpdrsn]

By the way you might be interested in #1552