Update xtokens docs. (#438)

* Update xtokens docs.

* Fix typo.

* Update imbalances impl.

Author: shaunxw

tokens/src/imbalances.rs

@@ -1,7 +1,7 @@
 // wrapping these imbalances in a private module is necessary to ensure absolute
 // privacy of the inner member.
 use crate::{Config, TotalIssuance};
-use frame_support::traits::{Get, Imbalance, TryDrop};
+use frame_support::traits::{Get, Imbalance, SameOrOther, TryDrop};
 use sp_runtime::traits::{Saturating, Zero};
 use sp_std::{marker, mem, result};
 
@@ -21,6 +21,12 @@ impl<T: Config, GetCurrencyId: Get<T::CurrencyId>> PositiveImbalance<T, GetCurre
 	}
 }
 
+impl<T: Config, GetCurrencyId: Get<T::CurrencyId>> Default for PositiveImbalance<T, GetCurrencyId> {
+	fn default() -> Self {
+		Self::zero()
+	}
+}
+
 /// Opaque, move-only struct with private fields that serves as a token
 /// denoting that funds have been destroyed without any equal and opposite
 /// accounting.
@@ -37,6 +43,12 @@ impl<T: Config, GetCurrencyId: Get<T::CurrencyId>> NegativeImbalance<T, GetCurre
 	}
 }
 
+impl<T: Config, GetCurrencyId: Get<T::CurrencyId>> Default for NegativeImbalance<T, GetCurrencyId> {
+	fn default() -> Self {
+		Self::zero()
+	}
+}
+
 impl<T: Config, GetCurrencyId: Get<T::CurrencyId>> TryDrop for PositiveImbalance<T, GetCurrencyId> {
 	fn try_drop(self) -> result::Result<(), Self> {
 		self.drop_zero()
@@ -73,14 +85,18 @@ impl<T: Config, GetCurrencyId: Get<T::CurrencyId>> Imbalance<T::Balance> for Pos
 		self.0 = self.0.saturating_add(other.0);
 		mem::forget(other);
 	}
-	fn offset(self, other: Self::Opposite) -> result::Result<Self, Self::Opposite> {
+	// allow to make the impl same with `pallet-balances`
+	#[allow(clippy::comparison_chain)]
+	fn offset(self, other: Self::Opposite) -> SameOrOther<Self, Self::Opposite> {
 		let (a, b) = (self.0, other.0);
 		mem::forget((self, other));
 
-		if a >= b {
-			Ok(Self::new(a - b))
+		if a > b {
+			SameOrOther::Same(Self::new(a - b))
+		} else if b > a {
+			SameOrOther::Other(NegativeImbalance::new(b - a))
 		} else {
-			Err(NegativeImbalance::new(b - a))
+			SameOrOther::None
 		}
 	}
 	fn peek(&self) -> T::Balance {
@@ -124,14 +140,18 @@ impl<T: Config, GetCurrencyId: Get<T::CurrencyId>> Imbalance<T::Balance> for Neg
 		self.0 = self.0.saturating_add(other.0);
 		mem::forget(other);
 	}
-	fn offset(self, other: Self::Opposite) -> result::Result<Self, Self::Opposite> {
+	// allow to make the impl same with `pallet-balances`
+	#[allow(clippy::comparison_chain)]
+	fn offset(self, other: Self::Opposite) -> SameOrOther<Self, Self::Opposite> {
 		let (a, b) = (self.0, other.0);
 		mem::forget((self, other));
 
-		if a >= b {
-			Ok(Self::new(a - b))
+		if a > b {
+			SameOrOther::Same(Self::new(a - b))
+		} else if b > a {
+			SameOrOther::Other(PositiveImbalance::new(b - a))
 		} else {
-			Err(PositiveImbalance::new(b - a))
+			SameOrOther::None
 		}
 	}
 	fn peek(&self) -> T::Balance {

xtokens/README.md

@@ -12,28 +12,20 @@ The xtokens module provides functions for
 
 ## Notes
 
-#### Unit tests
-
-Unit tests could be added once Polkadot has XCM simulator. https://github.com/paritytech/polkadot/issues/2544
-
 #### Integration tests
 
 Integration tests could be done manually after integrating xtokens into runtime. To cover the full features, set up at least 4 relay chain validators and 3 collators of different parachains, and use dispatchable calls to include all these scenarios:
 
 - Transfer relay chain tokens to relay chain.
-  - Use dispatchable call `transfer_to_relay_chain`.
 - Transfer tokens issued by parachain A, from parachain A to parachain B.
-  - Use dispatchable call `transfer_to_parachain`.
   - Sending the tx from parachain A.
   - Set the destination as Parachain B.
   - Set the currency ID as parachain A token.
 - Transfer tokens issued by parachain B, from parachain A to parachain B.
-  - Use dispatchable call `transfer_to_parachain`.
   - Sending the tx from parachain A.
   - Set the destination as Parachain B.
   - Set the currency ID as parachain B token.
 - Transfer tokens issued by parachain C, from parachain A to parachain B.
-  - Use dispatchable call `transfer_to_parachain`.
   - Sending the tx from parachain A.
   - Set the destination as Parachain B.
   - Set the currency ID as parachain C token.

xtokens/src/lib.rs

@@ -14,8 +14,8 @@
 //!
 //! ### Dispatchable functions
 //!
-//! - `transfer_to_relay_chain`: Transfer relay chain tokens to relay chain.
-//! - `transfer_to_parachain`: Transfer tokens to a sibling parachain.
+//! - `transfer`: Transfer local assets with given `CurrencyId` and `Amount`.
+//! - `transfer_multiasset`: Transfer `MultiAsset` assets.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(clippy::from_over_into)]