rust-lang / rust-lang/rust-by-example
"borrowing" is used extensively before any explanation, especially in Capturing
Nobody has claimed this yet.
- Dominant language
- Handlebars
- Stars
- 8.1k
- Forks
- 1.6k
- PR merge metrics
- No merged PRs in 30d
Description
The page on Capturing (fn/closures/capture.md) makes many references to borrowing to explain the semantics. But borrowing won't be explained for another six full sections.
(There are earlier references to borrowing as well, in primitives/array.md, custom_types/enum/testcase_linked_list.md, flow_control/for.md, and flow_control/match/destructuring/destructure_pointers.md. But those are fairly incidental, and easy to skim past while still getting the general gist of things. Not so with Capturing.)
I certainly don't think it would be a good idea to move the section on Scopes to someplace before Capturing. But I don't think it would hurt to add a short, basic explanation at an earlier point — maybe in Primitives? — noting that a full treatment will come later.
Alternatively, it might be a good idea to include at the very start a short discussion of what kind of language Rust is (or maybe why someone would want to learn Rust) … the goal of having both efficiency and safety, what safety means, and Rust's approach is to make the notion of ownership of data a first-class concept in the language. The term "borrowing" fits very naturally in such a discussion. That would also be a good place to actually explain & and *, which as far as I can tell are never explained at all.
(If that alternative suggestion is appealing, I'm happy to file a different issue just for that.)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with fn/closures/capture.md, then compare the earlier references in primitives/array.md, custom_types/enum/testcase_linked_list.md, flow_control/for.md, and flow_control/match/destructuring/destructure_pointers.md. Determine where an introductory explanation belongs and confirm that the chosen location gives readers enough context; done means the early borrowing references are understandable without prematurely moving the Scopes section.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100