Skip to content

Commit 99e44d8

Browse files
author
lukaramu
committed
Added to core::ops module docs
Part of #29365. * Added paragraph adapted from API guidelines that operator implementations should be unsurprising * Modified Point example to be more clear when just reading it
1 parent f1cc7d6 commit 99e44d8

File tree

1 file changed

+12
-5
lines changed

1 file changed

+12
-5
lines changed

src/libcore/ops/mod.rs

+12-5
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,12 @@
2121
//! custom operators are required, you should look toward macros or compiler
2222
//! plugins to extend Rust's syntax.
2323
//!
24+
//! Implementations of operator traits should be unsurprising in their
25+
//! respective contexts, keeping in mind their usual meanings and
26+
//! [operator precedence]. For example, when implementing [`Mul`], the operation
27+
//! should have some resemblance to multiplication (and share expected
28+
//! properties like associativity).
29+
//!
2430
//! Note that the `&&` and `||` operators short-circuit, i.e. they only
2531
//! evaluate their second operand if it contributes to the result. Since this
2632
//! behavior is not enforceable by traits, `&&` and `||` are not supported as
@@ -46,7 +52,7 @@
4652
//! ```rust
4753
//! use std::ops::{Add, Sub};
4854
//!
49-
//! #[derive(Debug)]
55+
//! #[derive(Debug, PartialEq)]
5056
//! struct Point {
5157
//! x: i32,
5258
//! y: i32,
@@ -67,10 +73,9 @@
6773
//! Point {x: self.x - other.x, y: self.y - other.y}
6874
//! }
6975
//! }
70-
//! fn main() {
71-
//! println!("{:?}", Point {x: 1, y: 0} + Point {x: 2, y: 3});
72-
//! println!("{:?}", Point {x: 1, y: 0} - Point {x: 2, y: 3});
73-
//! }
76+
//!
77+
//! assert_eq!(Point {x: 3, y: 3}, Point {x: 1, y: 0} + Point {x: 2, y: 3});
78+
//! assert_eq!(Point {x: -1, y: -3}, Point {x: 1, y: 0} - Point {x: 2, y: 3});
7479
//! ```
7580
//!
7681
//! See the documentation for each trait for an example implementation.
@@ -143,7 +148,9 @@
143148
//! [`FnOnce`]: trait.FnOnce.html
144149
//! [`Add`]: trait.Add.html
145150
//! [`Sub`]: trait.Sub.html
151+
//! [`Mul`]: trait.Mul.html
146152
//! [`clone`]: ../clone/trait.Clone.html#tymethod.clone
153+
//! [operator precedence]: ../../reference/expressions.html#operator-precedence
147154
148155
#![stable(feature = "rust1", since = "1.0.0")]
149156

0 commit comments

Comments
 (0)