From 5ae0a848c73b64ac3251a52a2fdcaade75114102 Mon Sep 17 00:00:00 2001
From: Dave Belvedere <90095005+dbelv@users.noreply.github.com>
Date: Wed, 16 Nov 2022 05:33:54 +1000
Subject: [PATCH] I256 asr doc (#1860)

* Update I256 documentation to call out diversions from standard numeric types on the right shift operator

* Update changelog

* Address review comment. Link changelog notes to PR

Co-authored-by: Dave Belvedere <dave@protonmail.com>
---
 CHANGELOG.md                  | 4 +++-
 ethers-core/src/types/i256.rs | 6 ++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9de5209d..f7f4547a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -93,7 +93,9 @@
 -   [#1632](https://github.com/gakonst/ethers-rs/pull/1632) Re-export `H32` from `ethabi`.
 -   [#1634](https://github.com/gakonst/ethers-rs/pull/1634) Derive missing `Clone`, `Copy` and `Debug` impls in ethers-etherscan.
 -   Bytes debug format now displays hex literals [#1658](https://github.com/gakonst/ethers-rs/pull/1658)
-- [#1451](https://github.com/gakonst/ethers-rs/issues/1451) Add Arithemtic Shift Left operation for I256 
+-   [#1451](https://github.com/gakonst/ethers-rs/issues/1451) Add Arithemtic Shift Left operation for I256
+-   [#1860](https://github.com/gakonst/ethers-rs/pull/1860)Update I256 type documentation calling out the inconsistency 
+    between its right shift operator and standard library numeric types.
 
 ## ethers-contract-abigen
 
diff --git a/ethers-core/src/types/i256.rs b/ethers-core/src/types/i256.rs
index d6eec01a..b3bc4ae5 100644
--- a/ethers-core/src/types/i256.rs
+++ b/ethers-core/src/types/i256.rs
@@ -89,6 +89,12 @@ impl Sign {
 }
 
 /// Little-endian 256-bit signed integer.
+///
+/// ## Diversion from standard numeric types
+/// The right shift operator on I256 doesn't act in the same manner as standard numeric types
+/// (e.g. `i8`, `i16` etc). On standard types if the number is negative right shift will perform
+/// an arithmetic shift, whereas on I256 this will perform a bit-wise shift.
+/// Arithmetic shift on I256 is done via the [asr](I256::asr) and [asl](I256::asl) functions.
 #[derive(Clone, Copy, Default, Deserialize, Eq, Hash, PartialEq, Serialize)]
 #[serde(transparent)]
 pub struct I256(U256);