From 99e44d8680f91e908c39ab3d5f0be2c11558af01 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Mon, 7 Aug 2017 23:07:34 +0200 Subject: 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 --- src/libcore/ops/mod.rs | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'src/libcore') diff --git a/src/libcore/ops/mod.rs b/src/libcore/ops/mod.rs index a78f4fe28a6..b5e6912b10d 100644 --- a/src/libcore/ops/mod.rs +++ b/src/libcore/ops/mod.rs @@ -21,6 +21,12 @@ //! custom operators are required, you should look toward macros or compiler //! plugins to extend Rust's syntax. //! +//! Implementations of operator traits should be unsurprising in their +//! respective contexts, keeping in mind their usual meanings and +//! [operator precedence]. For example, when implementing [`Mul`], the operation +//! should have some resemblance to multiplication (and share expected +//! properties like associativity). +//! //! Note that the `&&` and `||` operators short-circuit, i.e. they only //! evaluate their second operand if it contributes to the result. Since this //! behavior is not enforceable by traits, `&&` and `||` are not supported as @@ -46,7 +52,7 @@ //! ```rust //! use std::ops::{Add, Sub}; //! -//! #[derive(Debug)] +//! #[derive(Debug, PartialEq)] //! struct Point { //! x: i32, //! y: i32, @@ -67,10 +73,9 @@ //! Point {x: self.x - other.x, y: self.y - other.y} //! } //! } -//! fn main() { -//! println!("{:?}", Point {x: 1, y: 0} + Point {x: 2, y: 3}); -//! println!("{:?}", Point {x: 1, y: 0} - Point {x: 2, y: 3}); -//! } +//! +//! assert_eq!(Point {x: 3, y: 3}, Point {x: 1, y: 0} + Point {x: 2, y: 3}); +//! assert_eq!(Point {x: -1, y: -3}, Point {x: 1, y: 0} - Point {x: 2, y: 3}); //! ``` //! //! See the documentation for each trait for an example implementation. @@ -143,7 +148,9 @@ //! [`FnOnce`]: trait.FnOnce.html //! [`Add`]: trait.Add.html //! [`Sub`]: trait.Sub.html +//! [`Mul`]: trait.Mul.html //! [`clone`]: ../clone/trait.Clone.html#tymethod.clone +//! [operator precedence]: ../../reference/expressions.html#operator-precedence #![stable(feature = "rust1", since = "1.0.0")] -- cgit 1.4.1-3-g733a5