Missing documentation of use bounds

[CGamesPlay]

Location

Concerns rustc --explain E0700, the Rust Book, and the Reference.

Summary

I originally asked this StackOverflow question and was advised to file a bug.

The new use keyword, apparently introduced in 1.82, is poorly documented. There are at least 3 documentation issues:

1. The rust error E0700 tells you to add a use<...> bound to explicitly capture '_... For more information about this error, try rustc --explain E0700. But running this command only talks about the older syntax and doesn't mention use at all.
2. The Rust Book doesn't mention this syntax at all, in stable or nightly, as far as I can tell.
3. The Reference nightly edition mentions it in 10.1.16 and 10.6, but neither of these sections are included in the stable edition.

My specific questions about the syntax were answered by the announcement blog post, I just didn't know how to find it, because "rust use lifetime" is a pretty terrible set of keywords to google for.

[ehuss]

Thanks for the report! I agree it can be pretty challenging to search for certain things in Rust. Some notes:

• The documentation often lags the stable releases. This is the case with the reference, and should roll out in the next release.
• The Rust Book also lags the stable releases (sometimes significantly). Currently it looks to be about two releases behind.
• The Rust Book usually intentionally does not cover advanced topics, and is not intended to cover the entirety of the language. I don't know what their intentions are, but I suspect they probably won't cover it.
• The standard library documentation has been updated in nightly (1.84) here: https://doc.rust-lang.org/nightly/std/keyword.use.html#precise-capturing. That will hit stable in January.
• I similarly suggested for E0657 that it link to the use documentation, since it is somewhat of an obscure thing. I would agree that it would be good for E0700 to also mention something.

[CGamesPlay]

I don't have an opinion on whether the Rust Book should have a section on the topic, but the keyword glossary (stable, nightly) is incomplete with the expansion of the use keyword: link

• use - bring symbols into scope

I'm assuming that the standard library documentation in 1.82 not including the precise capture section is an oversight rather than a deliberate decision, but in case it isn't, I hope the maintainers will tally one vote for the "ship some documentation with the feature, even if it is incomplete" 🙂

[hkBst]

I've created a PR for fixing the issue of the book not mentioning this new use of use. The only other issue seems to be what to do about E0700.

With edition 2024 its erroneous code will start working (due to capturing all lifetimes by default) and erroneous code examples would need to use a use that erroneously leaves out some lifetimes. That would seem to change the character of this error a lot.

So, not sure what to do about that. anyone have any suggestions?

[chriskrycho]

On the book side, we’re definitely happy to land the PR that @hkBst opened for the appendix, and I am also planning to incorporate a small change once 1.85 is stable (which I may also try to land on the beta so it’s present with the version that goes out with the edition) that addresses use<..> bounds in the one place it’s relevant in the book.

---

I will add a meta note: In general, folks do try to make sure that there is sufficient documentation to go out with a release, not least because it’s part of the project’s commitment that documentation is part of stabilization, but different folks understand “sufficient” in different ways. There are also mechanical issues—stuff that changes across an edition is particularly tricky for documentation, given it needs to be able to use the edition value, e.g. "edition" = "2024", and cannot do that till it is off nightly, but we don’t want documentation samples depending on nightly builds. Finally, we also just have a gap for “how do we document every feature in an accessible way?”—the Book and the Reference are both great, but neither is actually exactly what people are often looking for in cases like this. No idea how to solve that—it’s just a hard problem I’ve seen in every ecosystem I have worked in!