Fully update documentation for 0.5

[jebrosen]

Rocket 0.5 is nearing completion, but several docs are lagging behind the actual code. This meta-issue tracks progress in getting documentation fully up-to-date.

• Async I/O Guidance

  Async is a big change that goes beyond function names and signatures. Accordingly, it will need additional documentation especially in the guide and the CHANGELOG and migration guide. The following topics and more should be considered:

  • Blocking operations in route handlers / cooperative multitasking
    • Rough guidelines of "acceptable" blocking, e.g. low-contention, short-held mutexes, and "unacceptable" blocking, e.g. filesystem and network I/O.
    • Examples of asynchronous alternatives or wrappers for synchronous libraries
    • † Workarounds for blocking APIs along with suggested usage and examples: spawn_blocking, block_in_place, dedicated worker tasks and channels, etc.
  • † Ergonomics of lifetimes, borrowing, async move, and non-Send data
  • Commonly experienced papercuts or limitations in the compiler.
    • Values unnecessarily or surprisingly held across await points (often problematic for borrows and for Send) - e.g. Tracking issue for more precise coroutine captures rust-lang/rust#69663
    • (and more)
    • NB: Many of these issues will be solved "magically" (from the user perspective) by upgrading rustc after they have been fixed, so we should consider whether they are important/common enough to also be in Rocket's documentation
  • TODO: More ideas? Make suggestions!

  † Based on questions seen in IRC and my own experiences while working with async, I have marked these details as especially problematic for migrations. These errors are relatively common, and also difficult to diagnose or understand without experience.

  Some of this documentation is not specific to Rocket, and can be supplemented by links to other resources such as:

  • The https://rust-lang.github.io/async-book/. Note that as of 2020-06-06, several chapters are still TODO.
  • Specific parts of the API documentation for supporting or utility crates such as futures and tokio.

• Entry Attributes

  #[rocket::main], #[rocket::launch], and #[rocket::async_test] need detailed docs.

• Forms Revamp

  The way forms work has been entirely revamped. The following items require updated or checked documentation.

  • FromForm and FromFormField derive codegen specs.
  • FromForm and FromFormField trait method docs.

• Routing Changes

  The effect of changing <path..> is signifcant and should be called out especially.

  UTF-8 is now supported everywhere. One example mentions this, but we should likely call this out.

• Broken Links (help!)

  Are all doc links valid and pointing somewhere? We need to run a link-checker on both the guide and rustdocs as well as handle all warnings issues by rustdoc.

CC #1242 (comment)
CC #1065

[teymour-aldridge]

I'd like to help write some of this documentation! Should I just open a PR with suggested changes?

[jebrosen]

PRs including documentation are always welcome! (and sorry for the late very late response)

[jnicholls]

Is this the primary blocking issue for releasing v0.5? Would like to help how I can.

Also, I found this article interesting: https://matej.laitl.cz/bench-actix-rocket/ Particularly the potential memory-leak in v0.5. Is this a known and/or resolved issue? If not, I can create an issue for it and help chase it down.

[SergioBenitez]

Also, I found this article interesting: https://matej.laitl.cz/bench-actix-rocket/ Particularly the potential memory-leak in v0.5. Is this a known and/or resolved issue? If not, I can create an issue for it and help chase it down.

This was a memory leak in dashmap which was temporarily a dependency of cookie, resolved in 5d9035d > 6 months ago.

[t-eckert]

Great work, I am just learning Rocket and I noticed a broken link in the docs. I'm going to go try and fix it and open a PR.

The broken link is here where it says "JSON example". I'm going to change it to point to https://github.com/SergioBenitez/Rocket/blob/v0.5-rc/examples/serialization/src/json.rs.

[memoryruins]

The https://rust-lang.github.io/async-book/. Note that as of 2020-06-06, several chapters are still TODO.

Tokio's tutorial https://tokio.rs/tokio/tutorial would be great to link to directly in the guide. It's an excellent introduction to async rust in general, and it helps that tokio is re-exported by rocket. I continually see beginners confused by the async book, but after introducing tokio's tutorial, the concepts start to click for them.

[tvallotton]

The async book was indeed pretty confusing when I first decided to learn async await. I think it should either be completed or reference the tokio tutorial until it's complete.

[jblachly]

0.5-rc1 documentation problems which were major barriers for new user (me):

1. #[derive(Deserialize) as per guide (e.g. https://rocket.rs/v0.5-rc/guide/requests/ ) does not compile without #[serde(crate = "rocket::serde")]
2. The same guide page on requests as linked above describes a "JSON Example" and links to https://github.com/SergioBenitez/Rocket/tree/v0.5-rc/examples/json, however, the json example has apparently been subsumed by the serialization example, which can be found here: https://github.com/SergioBenitez/Rocket/tree/master/examples/serialization

[teymour-aldridge]

@jblachly if you import Deserialize from rocket::serde rather than serde it works without the need for the serde(crate, ...) attribute.

[jblachly]

@teymour-aldridge Thanks for your comment; I actually did not import Deserialize from serde.

models.rs

use rocket::serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
#[serde(crate = "rocket::serde")] // compilation fails without this
pub struct User<'r> {
    // id: int
    // email: str
    // name: str
    id: i32,
    email: &'r str,
    name: &'r str
}

Now, probably I should be doing something else that an experienced rustacean would know to do, but I still assert that this is a documentation error, as following the 0.5-rc1 guide strictly yields this error by the time you reach https://rocket.rs/v0.5-rc/guide/requests/#json

I only found the #[serde(crate = "rocket::serde")] fix by looking through the examples in the github repo

[teymour-aldridge]

Sorry – you are right.

I think it works for structs without lifetimes, but otherwise not (not sure, but in a few projects I have it definitely works without the crate attribute).

[jblachly]

Sorry – you are right.

I think it works for structs without lifetimes, but otherwise not (not sure, but in a few projects I have it definitely works without the crate attribute).

@teymour-aldridge Apologies for cluttering this issue with marginally related discussion, but as a Rust newbie I am not sure the origin of this limitation; could you or others suggest where I might begin to understand why this directive is required with structs polymorphic over lifetime but not monomorphic structs?

I would be happy to try to improve the documentation via PR once I understand the root cause of the issue. Alternatively, if someone else reads this and knows the answer please do update the 0.5-rc docs =)

[SergioBenitez]

The migration guide (available in master, soon in rc.2), now includes async I/O guidance. This resolves the issue. For release specific documentation improvements unrelated to async I/O, [please discuss in the related release discussion.