Xcm-Simulator Docs (#6178)

* Xcm-Simulator Docs

* spelling

* examples

* better docs

Co-authored-by: parity-processbot <>

polkadot/xcm/xcm-simulator/src/lib.rs

@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Test kit to simulate cross-chain message passing and XCM execution
+//! Test kit to simulate cross-chain message passing and XCM execution.
 
 pub use codec::Encode;
 pub use paste;
@@ -62,6 +62,7 @@ pub enum MessageKind {
 	Xcmp,
 }
 
+/// Encodes the provided XCM message based on the `message_kind`.
 pub fn encode_xcm(message: Xcm<()>, message_kind: MessageKind) -> Vec<u8> {
 	match message_kind {
 		MessageKind::Ump | MessageKind::Dmp => VersionedXcm::<()>::from(message).encode(),
@@ -76,6 +77,19 @@ pub fn encode_xcm(message: Xcm<()>, message_kind: MessageKind) -> Vec<u8> {
 	}
 }
 
+/// The macro is implementing upward message passing(UMP) for the provided relay
+/// chain struct. The struct has to provide the XCM configuration for the relay
+/// chain.
+///
+/// ```ignore
+/// decl_test_relay_chain! {
+///	    pub struct Relay {
+///	        Runtime = relay_chain::Runtime,
+///	        XcmConfig = relay_chain::XcmConfig,
+///	        new_ext = relay_ext(),
+///	    }
+///	}
+/// ```
 #[macro_export]
 #[rustfmt::skip]
 macro_rules! decl_test_relay_chain {
@@ -108,6 +122,21 @@ macro_rules! decl_test_relay_chain {
 	};
 }
 
+/// The macro is implementing the `XcmMessageHandlerT` and `DmpMessageHandlerT`
+/// traits for the provided parachain struct. Expects the provided parachain
+/// struct to define the XcmpMessageHandler and DmpMessageHandler pallets that
+/// contain the message handling logic.
+///
+/// ```ignore
+/// decl_test_parachain! {
+///	    pub struct ParaA {
+///	        Runtime = parachain::Runtime,
+///	        XcmpMessageHandler = parachain::MsgQueue,
+///	        DmpMessageHandler = parachain::MsgQueue,
+///	        new_ext = para_ext(),
+///	    }
+/// }
+/// ```
 #[macro_export]
 macro_rules! decl_test_parachain {
 	(
@@ -153,6 +182,7 @@ macro_rules! decl_test_parachain {
 	};
 }
 
+/// Implements the `TestExt` trait for a specified struct.
 #[macro_export]
 macro_rules! __impl_ext {
 	// entry point: generate ext name
@@ -202,6 +232,23 @@ thread_local! {
 		= RefCell::new(VecDeque::new());
 }
 
+/// Declares a test network that consists of a relay chain and multiple
+/// parachains. Expects a network struct as an argument and implements testing
+/// functionality, `ParachainXcmRouter` and the `RelayChainXcmRouter`. The
+/// struct needs to contain the relay chain struct and an indexed list of
+/// parachains that are going to be in the network.
+///
+/// ```ignore
+/// decl_test_network! {
+///	    pub struct ExampleNet {
+///	        relay_chain = Relay,
+///	        parachains = vec![
+///	            (1, ParaA),
+///	            (2, ParaB),
+///	        ],
+///	    }
+/// }
+/// ```
 #[macro_export]
 macro_rules! decl_test_network {
 	(
@@ -215,16 +262,16 @@ macro_rules! decl_test_network {
 		impl $name {
 			pub fn reset() {
 				use $crate::{TestExt, VecDeque};
-				// Reset relay chain message bus
+				// Reset relay chain message bus.
 				$crate::RELAY_MESSAGE_BUS.with(|b| b.replace(VecDeque::new()));
-				// Reset parachain message bus
+				// Reset parachain message bus.
 				$crate::PARA_MESSAGE_BUS.with(|b| b.replace(VecDeque::new()));
 				<$relay_chain>::reset_ext();
 				$( <$parachain>::reset_ext(); )*
 			}
 		}
 
-		/// Check if any messages exist in either message bus
+		/// Check if any messages exist in either message bus.
 		fn exists_messages_in_any_bus() -> bool {
 			use $crate::{RELAY_MESSAGE_BUS, PARA_MESSAGE_BUS};
 			let no_relay_messages_left = RELAY_MESSAGE_BUS.with(|b| b.borrow().is_empty());