orml-xtokens transfer docs (#569)

* orml-xtokens transfer only guarantees sending, but not receiving.

* Explain .

* More docstring.

Author: shaunxw

xtokens/README.md

@@ -2,8 +2,7 @@
 
 ## Overview
 
-The xtokens module provides cross-chain token transfer functionality, by cross-consensus
-messages(XCM).
+The xtokens module provides cross-chain token transfer functionality, by cross-consensus messages(XCM).
 
 The xtokens module provides functions for
 - Token transfer from parachains to relay chain.
@@ -14,7 +13,7 @@ The xtokens module provides functions for
 
 #### 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:
+Integration tests could be done manually after integrating orml-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.
 - Transfer tokens issued by parachain A, from parachain A to parachain B.

xtokens/src/lib.rs

@@ -140,6 +140,17 @@ pub mod module {
 	#[pallet::call]
 	impl<T: Config> Pallet<T> {
 		/// Transfer native currencies.
+		///
+		/// `dest_weight` is the weight for XCM execution on the dest chain, and
+		/// it would be charged from the transferred assets. If set below
+		/// requirements, the execution may fail and assets wouldn't be
+		/// received.
+		///
+		/// It's a no-op if any error on local XCM execution or message sending.
+		/// Note sending assets out per se doesn't guarantee they would be
+		/// received. Receiving depends on if the XCM message could be delivered
+		/// by the network, and if the receiving chain would handle
+		/// messages correctly.
 		#[pallet::weight(Pallet::<T>::weight_of_transfer(currency_id.clone(), *amount, &dest))]
 		pub fn transfer(
 			origin: OriginFor<T>,
@@ -174,6 +185,17 @@ pub mod module {
 		}
 
 		/// Transfer `MultiAsset`.
+		///
+		/// `dest_weight` is the weight for XCM execution on the dest chain, and
+		/// it would be charged from the transferred assets. If set below
+		/// requirements, the execution may fail and assets wouldn't be
+		/// received.
+		///
+		/// It's a no-op if any error on local XCM execution or message sending.
+		/// Note sending assets out per se doesn't guarantee they would be
+		/// received. Receiving depends on if the XCM message could be delivered
+		/// by the network, and if the receiving chain would handle
+		/// messages correctly.
 		#[pallet::weight(Pallet::<T>::weight_of_transfer_multiasset(&asset, &dest))]
 		pub fn transfer_multiasset(
 			origin: OriginFor<T>,