From dcee93a8030c3a62c5a05b45b050f90251d93af8 Mon Sep 17 00:00:00 2001
From: Matthew Piziak <matthew.piziak@gmail.com>
Date: Tue, 16 Aug 2016 04:11:48 -0400
Subject: [PATCH] replace Add example with something more evocative of addition

Currently most of the operator traits use trivial implementation
examples that only perform side effects. Honestly, that might not be too
bad for the sake of documentation; but anyway, here's a proposal to move
a slightly modified version of the module-level point-addition example
into the `Add` documentation, since it's more evocative of addition
semantics.

Part of #29365

wrap identifiers in backticks

minor rephrasing

fix module-level documentation to be more truthful

This branch changes the example for `Add` to no longer be a "minimum implementation that prints something to the screen".
---
 src/libcore/ops.rs | 34 +++++++++++++++++++++++-----------
 1 file changed, 23 insertions(+), 11 deletions(-)

diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs
index 9347ac2a8c8..9e6310ed460 100644
--- a/src/libcore/ops.rs
+++ b/src/libcore/ops.rs
@@ -62,8 +62,7 @@
 //! }
 //! ```
 //!
-//! See the documentation for each trait for a minimum implementation that
-//! prints something to the screen.
+//! See the documentation for each trait for an example implementation.
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
@@ -166,25 +165,38 @@ fn $method(self, other: &'a $u) -> <$t as $imp<$u>>::Output {
 ///
 /// # Examples
 ///
-/// A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up
-/// calling `add`, and therefore, `main` prints `Adding!`.
+/// This example creates a `Point` struct that implements the `Add` trait, and
+/// then demonstrates adding two `Point`s.
 ///
 /// ```
 /// use std::ops::Add;
 ///
-/// struct Foo;
+/// #[derive(Debug)]
+/// struct Point {
+///     x: i32,
+///     y: i32,
+/// }
 ///
-/// impl Add for Foo {
-///     type Output = Foo;
+/// impl Add for Point {
+///     type Output = Point;
 ///
-///     fn add(self, _rhs: Foo) -> Foo {
-///         println!("Adding!");
-///         self
+///     fn add(self, other: Point) -> Point {
+///         Point {
+///             x: self.x + other.x,
+///             y: self.y + other.y,
+///         }
+///     }
+/// }
+///
+/// impl PartialEq for Point {
+///     fn eq(&self, other: &Self) -> bool {
+///         self.x == other.x && self.y == other.y
 ///     }
 /// }
 ///
 /// fn main() {
-///     Foo + Foo;
+///     assert_eq!(Point { x: 1, y: 0 } + Point { x: 2, y: 3 },
+///                Point { x: 3, y: 3 });
 /// }
 /// ```
 #[lang = "add"]
-- 
2.44.0