rust-lang / rust-lang/rust-by-example

Ambiguous explanation of explicit annotated lifetimes in chapter 15.4.1

Open
#1,945 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Handlebars
Stars
8.1k
Forks
1.6k
PR merge metrics
No merged PRs in 30d

Description

In this example function (failed_borrow) provided by Rust By Example (15.4.1):

// snip refs for example

// A function which takes no arguments, but has a lifetime parameter `'a`.
fn failed_borrow<'a>() {
    let _x = 12;

    // ERROR: `_x` does not live long enough
    let _y: &'a i32 = &_x;
    // Attempting to use the lifetime `'a` as an explicit type annotation 
    // inside the function will fail because the lifetime of `&_x` is shorter
    // than that of `_y`. A short lifetime cannot be coerced into a longer one.
}

// snip main for example

The explanation of why declaring _y as 'a is wrong and causes an error is ambiguous and has three issues I want to comment on:

  1. At this point in the tutorial, it's important to clarify that 'a is some arbitrary lifetime that might (and usually) is longer than the function scope/lifetime itself. This would clarify that any value of 'a has to abide by that arbitrary lifetime which might be longer and can therefore not use local variables as output or as a 'a reference.

  2. The explanation states that it is wrong to use 'a as a explicit type annotation for a variable inside function bounds. It's not inherently bad to use 'a for a explicit type within the function scope, but anything stored in it has to abide by that arbitrary lifetime and therefore must be some parameter of that arbitrary lifetime from the function stored in it. In this case it might be wrong but generalizing the explanation in that way could make learners get the wrong understanding of why this won't work.

  3. Learners should be able to understand that when we write let _y: &'a i32 we mean that the reference _y is storing a value which has to live as long as the arbitrary lifetime 'a, and therefore why &_x is "shorter" than _y is because &_x is a local lifetime of the scope and may not be long enough to fulfill the arbitrary lifetime. This should be explained in a manner that doesn't have uncertainty and ambiguity, and be quick to understand and not as compact as possible.

I think these could be implemented and edit the parts to fit it, or another option is just to explain explicit lifetimes in a simpler way.

This might be nitpicky or not needed but I believe it could bring a better understanding and learning experience to new rust users which wants to learn the language.

I'd be glad to open a PR on this if it is needed.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open Rust By Example chapter 15.4.1 and read the failed_borrow example alongside its explanation of explicit annotated lifetimes. Revise the wording to clarify the arbitrary lifetime and why the local reference is too short, while avoiding a general claim that using 'a inside a function is inherently wrong; done when the example is unambiguous for new Rust users.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.