rust-lang / rust-lang/reference

Confusing unrelated code example in Implementations after items.impl.trait.safety

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

Nobody has claimed this yet.

Language Cleanup
Dominant language
Rust
Stars
1.6k
Forks
607
PR merge metrics
PR metrics pending

Description

Immediately after the section about unsafe trait impls, there's a seemingly unrelated code example showing what appears to be an implementation of standard and custom traits (none of which are unsafe).

https://github.com/rust-lang/reference/blob/62882004d22f64eef6b4c45a4a534eee948cf664/src/items/implementations.md?plain=1#L125-L159

I found it fairly confusing, because I was expecting that a code example immediately after an important remark like that would show an example of it, but it appears to be a simple demonstration of the common syntax.

Every other code block in this file follows my expectations of the code example elaborating on the previous rule, just this one code block appears completely unrelated to the rule before it.

https://github.com/rust-lang/reference/blob/62882004d22f64eef6b4c45a4a534eee948cf664/src/items/implementations.md?plain=1#L63-L99
(The code example here shows multiple impl blocks)

I would have expected the example code (the one with Circle) to be placed after the items.impl.trait.intro paragraph - would that make more sense? Otherwise, I think that the code block should at least be more clearly detached from the unsafe rule, because it's not an example of an unsafe trait impl.

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

Read src/items/implementations.md around items.impl.trait.safety and items.impl.trait.intro, then compare the surrounding impl examples and their headings. Confirm the intended relationship between the unsafe-trait rule and the Circle example. Done means the example is positioned or separated so its purpose and relationship to the preceding rule are unambiguous.

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
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.