XCM docs and tests (#2948)

* WIP

* add tests and docs for DoubleEncoded

* reformat parent_count

* add test for match_and_split

* fix append_with docs and add tests

* move Parachain enum variant to tuple

* Fix stuff

* add to append test

* simplify match

* formatting

* format and extend doc comments (including examples)

* fix typo

* add some doc comments

* add test for location inverter

* Add more tests/docs

* Fix build

* matches fungibles

* currency adapter.

* add more tests for location inverter

* extract max length magic number into constant

* adapters.

* Apply suggestions from code review

* Final touches.

* Repot and fixes

* Remove last todo

* Apply suggestions from code review

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

* Update xcm/xcm-builder/src/barriers.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

* Update xcm/xcm-builder/src/barriers.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

* Update xcm/xcm-builder/src/currency_adapter.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

* Update xcm/xcm-builder/src/filter_asset_location.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

* Update xcm/xcm-builder/src/matches_fungible.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

* Update xcm/xcm-executor/src/traits/conversion.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

* Update xcm/xcm-executor/src/traits/conversion.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

* Update xcm/xcm-executor/src/traits/transact_asset.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

* Update xcm/xcm-executor/src/traits/should_execute.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

Co-authored-by: kianenigma <kian@parity.io>
Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Co-authored-by: Shawn Tabrizi <shawntabrizi@gmail.com>

polkadot/xcm/xcm-executor/src/traits/should_execute.rs

@@ -19,18 +19,21 @@ use xcm::v0::{Xcm, MultiLocation};
 use frame_support::weights::Weight;
 
 /// Trait to determine whether the execution engine should actually execute a given XCM.
+///
+/// Can be amalgamated into a tuple to have multiple trials. If any of the tuple elements returns `Ok()`, the
+/// execution stops. Else, `Err(_)` is returned if all elements reject the message.
 pub trait ShouldExecute {
 	/// Returns `true` if the given `message` may be executed.
 	///
 	/// - `origin`: The origin (sender) of the message.
-	/// - `top_level`: `true`` indicates the initial XCM coming from the `origin`, `false` indicates an embedded
-	///   XCM executed internally as part of another message or an `Order`.
+	/// - `top_level`: `true` indicates the initial XCM coming from the `origin`, `false` indicates an embedded XCM
+	///   executed internally as part of another message or an `Order`.
 	/// - `message`: The message itself.
 	/// - `shallow_weight`: The weight of the non-negotiable execution of the message. This does not include any
 	///   embedded XCMs sat behind mechanisms like `BuyExecution` which would need to answer for their own weight.
-	/// - `weight_credit`: The pre-established amount of weight that the system has determined this message
-	///   may utilise in its execution. Typically non-zero only because of prior fee payment, but could
-	///   in principle be due to other factors.
+	/// - `weight_credit`: The pre-established amount of weight that the system has determined this message may utilise
+	///   in its execution. Typically non-zero only because of prior fee payment, but could in principle be due to other
+	///   factors.
 	fn should_execute<Call>(
 		origin: &MultiLocation,
 		top_level: bool,
@@ -51,7 +54,7 @@ impl ShouldExecute for Tuple {
 	) -> Result<(), ()> {
 		for_tuples!( #(
 			match Tuple::should_execute(origin, top_level, message, shallow_weight, weight_credit) {
-				o @ Ok(()) => return o,
+				Ok(()) => return Ok(()),
 				_ => (),
 			}
 		)* );