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

[MetaflameDragon]

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).

reference/src/items/implementations.md

Lines 125 to 159 in 6288200

	r[items.impl.trait.safety]
	[Unsafe traits] require the trait implementation to begin with the `unsafe`
	keyword.
	```rust
	# #[derive(Copy, Clone)]
	# struct Point {x: f64, y: f64};
	# type Surface = i32;
	# struct BoundingBox {x: f64, y: f64, width: f64, height: f64};
	# trait Shape { fn draw(&self, s: Surface); fn bounding_box(&self) -> BoundingBox; }
	# fn do_draw_circle(s: Surface, c: Circle) { }
	struct Circle {
	radius: f64,
	center: Point,
	}
	impl Copy for Circle {}
	impl Clone for Circle {
	fn clone(&self) -> Circle { *self }
	}
	impl Shape for Circle {
	fn draw(&self, s: Surface) { do_draw_circle(s, *self); }
	fn bounding_box(&self) -> BoundingBox {
	let r = self.radius;
	BoundingBox {
	x: self.center.x - r,
	y: self.center.y - r,
	width: 2.0 * r,
	height: 2.0 * r,
	}
	}
	}
	```

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.

reference/src/items/implementations.md

Lines 63 to 99 in 6288200

	r[items.impl.inherent.coherence]
	A type can also have multiple inherent implementations. An implementing type
	must be defined within the same crate as the original type definition.
	``` rust
	pub mod color {
	pub struct Color(pub u8, pub u8, pub u8);
	impl Color {
	pub const WHITE: Color = Color(255, 255, 255);
	}
	}
	mod values {
	use super::color::Color;
	impl Color {
	pub fn red() -> Color {
	Color(255, 0, 0)
	}
	}
	}
	pub use self::color::Color;
	fn main() {
	// Actual path to the implementing type and impl in the same module.
	color::Color::WHITE;
	// Impl blocks in different modules are still accessed through a path to the type.
	color::Color::red();
	// Re-exported paths to the implementing type also work.
	Color::red();
	// Does not work, because use in `values` is not pub.
	// values::Color::red();
	}
	```

(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.

[ehuss]

I think both of those examples are associated with their respective sections ("Trait implementations" and "Inherent implementations"), not the rule that immediately precedes that. They kinda show a culmination of multiple rules.

I suppose the question is, if moved to the intro, does it make sense to show an example before the rules that describe it?

I'm thinking of maybe shrinking the examples a little, move them to their respective "intro", and then create new examples for specialized rules like items.impl.inherent.coherence that narrowly illustrate that one rule.