Repository: CosmWasm/cw-multi-test
Pull request #114 (2023-12-13 12:03:09)

Code docs updates


Patch:
diff --git a/Cargo.lock b/Cargo.lock
index f6031bd..3b15d77 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -129,9 +129,9 @@ checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
 
 [[package]]
 name = "const-oid"
-version = "0.9.5"
+version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "28c122c3980598d243d63d9a704629a2d748d101f278052ff068be5a4423ab6f"
+checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
 
 [[package]]
 name = "cosmwasm-crypto"
@@ -255,6 +255,7 @@ dependencies = [
  "cosmwasm-std",
  "cw-storage-plus",
  "cw-utils",
+ "cw1-whitelist",
  "derivative",
  "hex",
  "hex-literal",
@@ -293,6 +294,35 @@ dependencies = [
  "thiserror",
 ]
 
+[[package]]
+name = "cw1"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1605722190afd93bfea6384b88224d1cfe50ebf70d2e10641535da79fa70e83"
+dependencies = [
+ "cosmwasm-schema",
+ "cosmwasm-std",
+ "schemars",
+ "serde",
+]
+
+[[package]]
+name = "cw1-whitelist"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "81bb3e9dc87f4ff26547f4e27e0ba3c82034372f21b2f55527fb52b542637d8d"
+dependencies = [
+ "cosmwasm-schema",
+ "cosmwasm-std",
+ "cw-storage-plus",
+ "cw-utils",
+ "cw1",
+ "cw2",
+ "schemars",
+ "serde",
+ "thiserror",
+]
+
 [[package]]
 name = "cw2"
 version = "1.1.2"
@@ -515,9 +545,9 @@ dependencies = [
 
 [[package]]
 name = "itoa"
-version = "1.0.9"
+version = "1.0.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "af150ab688ff2122fcef229be89cb50dd66af9e01a4ff320cc137eecc9bacc38"
+checksum = "b1a46d1a171d865aa5f83f92695765caa047a9b4cbae2cbf37dbd613a793fd4c"
 
 [[package]]
 name = "k256"
@@ -535,9 +565,9 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.150"
+version = "0.2.151"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "89d92a4743f9a61002fae18374ed11e7973f530cb3a3255fb354818118b2203c"
+checksum = "302d7ab3130588088d277783b1e2d2e10c9e9e4a16dd9050e6ec93fb3e7048f4"
 
 [[package]]
 name = "memchr"
@@ -565,9 +595,9 @@ dependencies = [
 
 [[package]]
 name = "once_cell"
-version = "1.18.0"
+version = "1.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dd8b5dd2ae5ed71462c540258bedcb51965123ad7e7ccf4b9a8cafaa4a63576d"
+checksum = "3fdb12b2476b595f9358c5161aa467c2438859caa136dec86c26fdd2efe17b92"
 
 [[package]]
 name = "opaque-debug"
@@ -614,7 +644,7 @@ dependencies = [
  "itertools 0.11.0",
  "proc-macro2",
  "quote",
- "syn 2.0.39",
+ "syn 2.0.41",
 ]
 
 [[package]]
@@ -659,9 +689,9 @@ checksum = "d626bb9dae77e28219937af045c257c28bfd3f69333c512553507f5f9798cb76"
 
 [[package]]
 name = "ryu"
-version = "1.0.15"
+version = "1.0.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ad4cc8da4ef723ed60bced201181d83791ad433213d8c24efffda1eec85d741"
+checksum = "f98d2aa92eebf49b69786be48e4477826b256916e84a57ff2a4f21923b48eb4c"
 
 [[package]]
 name = "schemars"
@@ -733,7 +763,7 @@ checksum = "43576ca501357b9b071ac53cdc7da8ef0cbd9493d8df094cd821777ea6e894d3"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.39",
+ "syn 2.0.41",
 ]
 
 [[package]]
@@ -827,9 +857,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "2.0.39"
+version = "2.0.41"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "23e78b90f2fcf45d3e842032ce32e3f2d1545ba6636271dcbf24fa306d87be7a"
+checksum = "44c8b28c477cc3bf0e7966561e3460130e1255f7a1cf71931075f1c5e7a7e269"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -853,7 +883,7 @@ checksum = "266b2e40bc00e5a6c09c3584011e08b06f123c00362c92b975ba9843aaaa14b8"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.39",
+ "syn 2.0.41",
 ]
 
 [[package]]
diff --git a/Cargo.toml b/Cargo.toml
index 018812c..8e3391f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -33,4 +33,5 @@ thiserror = "1.0.50"
 [dev-dependencies]
 hex = "0.4.3"
 hex-literal = "0.4.1"
-once_cell = "1.18.0"
+once_cell = "1.19.0"
+cw1-whitelist = "1.1.2"
diff --git a/src/addons/addresses/mock.rs b/src/addons/addresses/mock.rs
index 081199c..ab166f9 100644
--- a/src/addons/addresses/mock.rs
+++ b/src/addons/addresses/mock.rs
@@ -4,7 +4,7 @@ use cosmwasm_std::{instantiate2_address, Addr, Api, CanonicalAddr, Storage};
 use sha2::digest::Update;
 use sha2::{Digest, Sha256};
 
-/// Address generator that mimics the original `wasmd` behavior.
+/// Address generator that mimics the [wasmd](https://github.com/CosmWasm/wasmd) behavior.
 ///
 /// [MockAddressGenerator] implements [AddressGenerator] trait in terms of
 /// [`contract_address`](AddressGenerator::contract_address) and
diff --git a/src/addons/api/bech32.rs b/src/addons/api/bech32.rs
index f2fd739..923b396 100644
--- a/src/addons/api/bech32.rs
+++ b/src/addons/api/bech32.rs
@@ -5,10 +5,10 @@ use cosmwasm_std::{
 };
 use sha2::{Digest, Sha256};
 
-/// Implementation of the `Api` trait that uses [`Bech32`] format
+/// Implementation of the [Api](cosmwasm_std::Api) trait that uses [Bech32] format
 /// for humanizing canonical addresses.
 ///
-/// [`Bech32`]:https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
+/// [Bech32]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
 pub struct MockApiBech32 {
     api: MockApi,
     prefix: &'static str,
diff --git a/src/addons/api/bech32m.rs b/src/addons/api/bech32m.rs
index d630f2b..40311cd 100644
--- a/src/addons/api/bech32m.rs
+++ b/src/addons/api/bech32m.rs
@@ -2,10 +2,10 @@ use crate::addons::MockApiBech32;
 use bech32::Variant;
 use cosmwasm_std::{Addr, Api, CanonicalAddr, RecoverPubkeyError, StdResult, VerificationError};
 
-/// Implementation of the `Api` trait that uses [`Bech32m`] format
+/// Implementation of the [Api](cosmwasm_std::Api) trait that uses [Bech32m] format
 /// for humanizing canonical addresses.
 ///
-/// [`Bech32m`]:https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki
+/// [Bech32m]: https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki
 pub struct MockApiBech32m(MockApiBech32);
 
 impl MockApiBech32m {
diff --git a/src/addons/mod.rs b/src/addons/mod.rs
index be056c1..5dd4401 100644
--- a/src/addons/mod.rs
+++ b/src/addons/mod.rs
@@ -1,4 +1,6 @@
-//! MultiTest addons provide additional tools for testing smart contracts,
+//! # Additional testing tools (extensions)
+//!
+//! **CosmWasm MultiTest** addons provide additional tools for testing smart contracts,
 //! simulating complex blockchain scenarios that developers might encounter.
 //! They enhance the CosmWasm environment, enabling more advanced and nuanced testing.
 
diff --git a/src/addresses.rs b/src/addresses.rs
index 3a0b166..bf91831 100644
--- a/src/addresses.rs
+++ b/src/addresses.rs
@@ -16,6 +16,10 @@ pub trait AddressGenerator {
         since = "0.18.0",
         note = "use `contract_address` or `predictable_contract_address` instead; will be removed in version 1.0.0"
     )]
+    /// Generates a _non-predictable_ contract address based on the number of contract's instances.
+    /// This is a simplified version of simulating contract addresses that is deprecated in favour of
+    /// [contract_address](Self::contract_address) and
+    /// [predictable_contract_address](Self::predictable_contract_address) functions.
     fn next_address(&self, storage: &mut dyn Storage) -> Addr {
         //TODO After removing this function in version 1.0, make `CONTRACTS` and `NAMESPACE_WASM` private in `wasm.rs`.
         let count = CONTRACTS
diff --git a/src/app.rs b/src/app.rs
index 17ef8fb..29c9718 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -20,6 +20,7 @@ use schemars::JsonSchema;
 use serde::{de::DeserializeOwned, Serialize};
 use std::fmt::Debug;
 use std::marker::PhantomData;
+
 /// Advances the blockchain environment to the next block in tests, enabling developers to simulate
 /// time-dependent contract behaviors and block-related triggers efficiently.
 pub fn next_block(block: &mut BlockInfo) {
@@ -42,13 +43,9 @@ pub type BasicApp<ExecC = Empty, QueryC = Empty> = App<
     StargateFailing,
 >;
 
-/// The App struct in cw-multi-test serves as a router with persisted state
-/// for querying the blockchain's current status. It primarily uses RouterCache for
-/// executing transactions, which allows for preliminary testing of operations before
-/// they are permanently applied. The provided .execute() method streamlines this process,
-/// handling the execution, review, and finalization (commit or rollback) of these operations,
-/// simplifying state management and transaction testing in the CosmWasm framework.
-
+/// # Blockchain application simulator
+///
+/// This structure is the main component of the real-life blockchain simulator.
 #[derive(Clone)]
 pub struct App<
     Bank = BankKeeper,
@@ -198,7 +195,7 @@ where
         &self.router
     }
 
-    /// Returns a shared reference to application's api.
+    /// Returns a shared reference to application's API.
     pub fn api(&self) -> &ApiT {
         &self.api
     }
@@ -213,6 +210,7 @@ where
         &mut self.storage
     }
 
+    /// Initializes modules.
     pub fn init_modules<F, T>(&mut self, init_fn: F) -> T
     where
         F: FnOnce(
@@ -224,6 +222,7 @@ where
         init_fn(&mut self.router, &self.api, &mut self.storage)
     }
 
+    /// Queries a module.
     pub fn read_module<F, T>(&self, query_fn: F) -> T
     where
         F: FnOnce(
@@ -354,6 +353,7 @@ where
     GovT: Gov,
     StargateT: Stargate,
 {
+    /// Sets the initial block properties.
     pub fn set_block(&mut self, block: BlockInfo) {
         self.router
             .staking
@@ -362,7 +362,7 @@ where
         self.block = block;
     }
 
-    // this let's use use "next block" steps that add eg. one height and 5 seconds
+    /// Updates the current block applying the specified closure, usually [next_block].
     pub fn update_block<F: Fn(&mut BlockInfo)>(&mut self, action: F) {
         self.router
             .staking
@@ -455,16 +455,21 @@ where
 /// transactions within the Cosmos blockchain.
 #[derive(Clone)]
 pub struct Router<Bank, Custom, Wasm, Staking, Distr, Ibc, Gov, Stargate> {
-    // this can remain crate-only as all special functions are wired up to app currently
-    // we need to figure out another format for wasm, as some like sudo need to be called after init
+    /// Wasm module instance to be used in this [Router].
     pub(crate) wasm: Wasm,
-    // these must be pub so we can initialize them (super user) on build
+    /// Bank module instance to be used in this [Router].
     pub bank: Bank,
+    /// Custom module instance to be used in this [Router].
     pub custom: Custom,
+    /// Staking module instance to be used in this [Router].
     pub staking: Staking,
+    /// Distribution module instance to be used in this [Router].
     pub distribution: Distr,
+    /// IBC module instance to be used in this [Router].
     pub ibc: Ibc,
+    /// Governance module instance to be used in this [Router].
     pub gov: Gov,
+    /// Stargate module instance to be used in this [Router].
     pub stargate: Stargate,
 }
 
@@ -482,6 +487,7 @@ where
     GovT: Gov,
     StargateT: Stargate,
 {
+    /// Returns a querier populated with the instance of this [Router].
     pub fn querier<'a>(
         &'a self,
         api: &'a dyn Api,
@@ -500,9 +506,13 @@ where
 /// We use it to allow calling into modules from another module in sudo mode.
 /// Things like gov proposals belong here.
 pub enum SudoMsg {
+    /// Bank privileged actions.
     Bank(BankSudo),
+    /// Custom privileged actions.
     Custom(Empty),
+    /// Staking privileged actions.
     Staking(StakingSudo),
+    /// Wasm privileged actions.
     Wasm(WasmSudo),
 }
 
@@ -523,13 +533,18 @@ impl From<StakingSudo> for SudoMsg {
         SudoMsg::Staking(staking)
     }
 }
-///This trait is designed for routing messages within the Cosmos ecosystem.
-/// It's key to ensuring that transactions and contract calls are directed to the
+/// A trait representing the Cosmos based chain's router.
+///
+/// This trait is designed for routing messages within the Cosmos ecosystem.
+/// It is key to ensuring that transactions and contract calls are directed to the
 /// correct destinations during testing, simulating real-world blockchain operations.
 pub trait CosmosRouter {
+    /// Type of the executed custom message.
     type ExecC;
+    /// Type of the query custom message.
     type QueryC: CustomQuery;
 
+    /// Executes messages.
     fn execute(
         &self,
         api: &dyn Api,
@@ -539,6 +554,7 @@ pub trait CosmosRouter {
         msg: CosmosMsg<Self::ExecC>,
     ) -> AnyResult<AppResponse>;
 
+    /// Evaluates queries.
     fn query(
         &self,
         api: &dyn Api,
@@ -547,6 +563,7 @@ pub trait CosmosRouter {
         request: QueryRequest<Self::QueryC>,
     ) -> AnyResult<Binary>;
 
+    /// Evaluates privileged actions.
     fn sudo(
         &self,
         api: &dyn Api,
diff --git a/src/bank.rs b/src/bank.rs
index 6bd9d26..d198e43 100644
--- a/src/bank.rs
+++ b/src/bank.rs
@@ -14,34 +14,46 @@ use cw_utils::NativeBalance;
 use itertools::Itertools;
 use schemars::JsonSchema;
 
+/// Collection of bank balances.
 const BALANCES: Map<&Addr, NativeBalance> = Map::new("balances");
 
+/// Default namespace for bank module.
 pub const NAMESPACE_BANK: &[u8] = b"bank";
 
-#[derive(Clone, std::fmt::Debug, PartialEq, Eq, JsonSchema)]
+/// A message representing privileged actions in bank module.
+#[derive(Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub enum BankSudo {
+    /// Minting privileged action.
     Mint {
+        /// Destination address the tokens will be minted for.
         to_address: String,
+        /// Amount of the minted tokens.
         amount: Vec<Coin>,
     },
 }
-/// This trait defines the interface for simulating banking operations in the test
-/// environment. It's essential for testing financial transactions, like transfers
-/// and balance checks, within your smart contracts.
+
+/// This trait defines the interface for simulating banking operations.
+///
+/// In the test environment, it is essential for testing financial transactions,
+/// like transfers and balance checks, within your smart contracts.
+/// This trait implements all of these functionalities.
 pub trait Bank: Module<ExecT = BankMsg, QueryT = BankQuery, SudoT = BankSudo> {}
 
-#[derive(Default)]
+/// A structure representing a default bank keeper.
+///
 /// Manages financial interactions in CosmWasm tests, such as simulating token transactions
 /// and account balances. This is particularly important for contracts that deal with financial
 /// operations in the Cosmos ecosystem.
+#[derive(Default)]
 pub struct BankKeeper {}
 
 impl BankKeeper {
+    /// Creates a new instance of a bank keeper with default settings.
     pub fn new() -> Self {
-        BankKeeper {}
+        Self::default()
     }
 
-    // this is an "admin" function to let us adjust bank accounts in genesis
+    /// _Admin_ function for adjusting bank accounts in genesis.
     pub fn init_balance(
         &self,
         storage: &mut dyn Storage,
@@ -52,7 +64,7 @@ impl BankKeeper {
         self.set_balance(&mut bank_storage, account, amount)
     }
 
-    // this is an "admin" function to let us adjust bank accounts
+    /// _Admin_ function for adjusting bank accounts.
     fn set_balance(
         &self,
         bank_storage: &mut dyn Storage,
@@ -125,7 +137,7 @@ impl BankKeeper {
         self.set_balance(bank_storage, &from_address, a.into_vec())
     }
 
-    /// Filters out all 0 value coins and returns an error if the resulting Vec is empty
+    /// Filters out all `0` value coins and returns an error if the resulting vector is empty.
     fn normalize_amount(&self, amount: Vec<Coin>) -> AnyResult<Vec<Coin>> {
         let res: Vec<_> = amount.into_iter().filter(|x| !x.amount.is_zero()).collect();
         if res.is_empty() {
diff --git a/src/contracts.rs b/src/contracts.rs
index 4484293..954f49c 100644
--- a/src/contracts.rs
+++ b/src/contracts.rs
@@ -1,3 +1,5 @@
+#![allow(clippy::type_complexity)]
+
 use crate::error::{anyhow, bail, AnyError, AnyResult};
 use cosmwasm_std::{
     from_json, Binary, CosmosMsg, CustomQuery, Deps, DepsMut, Empty, Env, MessageInfo,
@@ -10,13 +12,15 @@ use std::fmt::{Debug, Display};
 use std::ops::Deref;
 
 /// Serves as the primary interface for interacting with contracts.
+///
 /// It includes methods for executing, querying, and managing contract states,
-/// making it a fundamental trait for testing contract functionalities.
+/// making it a fundamental trait for testing contracts.
 pub trait Contract<T, Q = Empty>
 where
     T: Clone + Debug + PartialEq + JsonSchema,
     Q: CustomQuery,
 {
+    /// Evaluates contract's `execute` entry-point.
     fn execute(
         &self,
         deps: DepsMut<Q>,
@@ -25,6 +29,7 @@ where
         msg: Vec<u8>,
     ) -> AnyResult<Response<T>>;
 
+    /// Evaluates contract's `instantiate` entry-point.
     fn instantiate(
         &self,
         deps: DepsMut<Q>,
@@ -33,12 +38,16 @@ where
         msg: Vec<u8>,
     ) -> AnyResult<Response<T>>;
 
+    /// Evaluates contract's `query` entry-point.
     fn query(&self, deps: Deps<Q>, env: Env, msg: Vec<u8>) -> AnyResult<Binary>;
 
+    /// Evaluates contract's `sudo` entry-point.
     fn sudo(&self, deps: DepsMut<Q>, env: Env, msg: Vec<u8>) -> AnyResult<Response<T>>;
 
+    /// Evaluates contract's `reply` entry-point.
     fn reply(&self, deps: DepsMut<Q>, env: Env, msg: Reply) -> AnyResult<Response<T>>;
 
+    /// Evaluates contract's `migrate` entry-point.
     fn migrate(&self, deps: DepsMut<Q>, env: Env, msg: Vec<u8>) -> AnyResult<Response<T>>;
 }
 
@@ -105,6 +114,7 @@ where
     C: Clone + Debug + PartialEq + JsonSchema + 'static,
     Q: CustomQuery + DeserializeOwned + 'static,
 {
+    /// Creates a new contract wrapper with default settings.
     pub fn new(
         execute_fn: ContractFn<T1, C, E1, Q>,
         instantiate_fn: ContractFn<T2, C, E2, Q>,
@@ -155,6 +165,7 @@ where
     C: Clone + Debug + PartialEq + JsonSchema + 'static,
     Q: CustomQuery + DeserializeOwned + 'static,
 {
+    /// Populates [ContractWrapper] with contract's `sudo` entry-point and custom message type.
     pub fn with_sudo<T4A, E4A>(
         self,
         sudo_fn: PermissionedFn<T4A, C, E4A, Q>,
@@ -173,6 +184,7 @@ where
         }
     }
 
+    /// Populates [ContractWrapper] with contract's `sudo` entry-point and `Empty` as a custom message.
     pub fn with_sudo_empty<T4A, E4A>(
         self,
         sudo_fn: PermissionedFn<T4A, Empty, E4A, Q>,
@@ -191,6 +203,7 @@ where
         }
     }
 
+    /// Populates [ContractWrapper] with contract's `reply` entry-point and custom message type.
     pub fn with_reply<E5A>(
         self,
         reply_fn: ReplyFn<C, E5A, Q>,
@@ -208,7 +221,7 @@ where
         }
     }
 
-    /// A correlate of new_with_empty
+    /// Populates [ContractWrapper] with contract's `reply` entry-point and `Empty` as a custom message.
     pub fn with_reply_empty<E5A>(
         self,
         reply_fn: ReplyFn<Empty, E5A, Q>,
@@ -226,6 +239,7 @@ where
         }
     }
 
+    /// Populates [ContractWrapper] with contract's `migrate` entry-point and custom message type.
     pub fn with_migrate<T6A, E6A>(
         self,
         migrate_fn: PermissionedFn<T6A, C, E6A, Q>,
@@ -244,6 +258,7 @@ where
         }
     }
 
+    /// Populates [ContractWrapper] with contract's `migrate` entry-point and `Empty` as a custom message.
     pub fn with_migrate_empty<T6A, E6A>(
         self,
         migrate_fn: PermissionedFn<T6A, Empty, E6A, Q>,
diff --git a/src/custom_handler.rs b/src/custom_handler.rs
index 02552a8..a29f30d 100644
--- a/src/custom_handler.rs
+++ b/src/custom_handler.rs
@@ -1,3 +1,5 @@
+//! # Custom message and query handler
+
 use crate::app::CosmosRouter;
 use crate::error::{bail, AnyResult};
 use crate::{AppResponse, Module};
@@ -7,44 +9,46 @@ use std::cell::{Ref, RefCell};
 use std::ops::Deref;
 use std::rc::Rc;
 
-/// This struct serves as the internal state of CachingCustomHandler, carefully managing
-/// internal mutability to keep it hidden from users. It's essential for maintaining a shared
-/// internal state, especially since accessing mock internals becomes impossible once the
-/// mock is passed to the app and not exposed by the API.
+/// A cache for messages and queries processes by the custom module.
 #[derive(Derivative)]
 #[derivative(Default(bound = "", new = "true"), Clone(bound = ""))]
 pub struct CachingCustomHandlerState<ExecC, QueryC> {
+    /// Cache for processes custom messages.
     execs: Rc<RefCell<Vec<ExecC>>>,
+    /// Cache for processed custom queries.
     queries: Rc<RefCell<Vec<QueryC>>>,
 }
 
 impl<ExecC, QueryC> CachingCustomHandlerState<ExecC, QueryC> {
+    /// Returns a slice of processed custom messages.
     pub fn execs(&self) -> impl Deref<Target = [ExecC]> + '_ {
         Ref::map(self.execs.borrow(), Vec::as_slice)
     }
 
+    /// Returns a slice of processed custom queries.
     pub fn queries(&self) -> impl Deref<Target = [QueryC]> + '_ {
         Ref::map(self.queries.borrow(), Vec::as_slice)
     }
 
+    /// Clears the cache.
     pub fn reset(&self) {
         self.execs.borrow_mut().clear();
         self.queries.borrow_mut().clear();
     }
 }
 
-/// Custom handler storing all the messages it received, so they can be later verified.
-/// State is thin shared state, so it can be hold after mock is passed to App to read state.
+/// Custom handler that stores all received messages and queries.
 ///
-/// Manages the internal state of a custom handler, recording execution and query messages.
-/// Useful for tracking contract interactions during tests.
+/// State is thin shared state, so it can be hold after mock is passed to [App](crate::App) to read state.
 #[derive(Clone, Derivative)]
 #[derivative(Default(bound = "", new = "true"))]
 pub struct CachingCustomHandler<ExecC, QueryC> {
+    /// Cached state.
     state: CachingCustomHandlerState<ExecC, QueryC>,
 }
 
 impl<ExecC, QueryC> CachingCustomHandler<ExecC, QueryC> {
+    /// Returns the cached state.
     pub fn state(&self) -> CachingCustomHandlerState<ExecC, QueryC> {
         self.state.clone()
     }
@@ -55,8 +59,7 @@ impl<Exec, Query> Module for CachingCustomHandler<Exec, Query> {
     type QueryT = Query;
     type SudoT = Empty;
 
-    // TODO: how to assert
-    // where ExecC: Exec, QueryC: Query
+    // TODO: how to assert like `where ExecC: Exec, QueryC: Query`
     fn execute<ExecC, QueryC>(
         &self,
         _api: &dyn Api,
@@ -70,17 +73,6 @@ impl<Exec, Query> Module for CachingCustomHandler<Exec, Query> {
         Ok(AppResponse::default())
     }
 
-    fn sudo<ExecC, QueryC>(
-        &self,
-        _api: &dyn Api,
-        _storage: &mut dyn Storage,
-        _router: &dyn CosmosRouter<ExecC = ExecC, QueryC = QueryC>,
-        _block: &BlockInfo,
-        msg: Self::SudoT,
-    ) -> AnyResult<AppResponse> {
-        bail!("Unexpected sudo msg {:?}", msg)
-    }
-
     fn query(
         &self,
         _api: &dyn Api,
@@ -92,4 +84,15 @@ impl<Exec, Query> Module for CachingCustomHandler<Exec, Query> {
         self.state.queries.borrow_mut().push(request);
         Ok(Binary::default())
     }
+
+    fn sudo<ExecC, QueryC>(
+        &self,
+        _api: &dyn Api,
+        _storage: &mut dyn Storage,
+        _router: &dyn CosmosRouter<ExecC = ExecC, QueryC = QueryC>,
+        _block: &BlockInfo,
+        msg: Self::SudoT,
+    ) -> AnyResult<AppResponse> {
+        bail!("Unexpected custom sudo message {:?}", msg)
+    }
 }
diff --git a/src/error.rs b/src/error.rs
index 7dc5925..bd2576e 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,60 +1,71 @@
+//! # Error definitions
+
 pub use anyhow::{anyhow, bail, Context as AnyContext, Error as AnyError, Result as AnyResult};
 use cosmwasm_std::{WasmMsg, WasmQuery};
 use thiserror::Error;
-///The error module deals with identifying and reporting problems that occur during testing.
-///It's like a diagnostic tool that helps you understand what went wrong and where, so you can fix issues
-/// more effectively.
+
+/// An enumeration of errors reported across the **CosmWasm MultiTest** library.
 #[derive(Debug, Error, PartialEq, Eq)]
-///This module handles error definitions and management within `cw_multi_test``, ensuring that issues
-///and exceptions encountered during the testing process are effectively identified and reported.
 pub enum Error {
-    #[error("Empty attribute key. Value: {value}")]
-    EmptyAttributeKey { value: String },
+    /// Error variant for reporting an empty attribute key.
+    #[error("Empty attribute key. Value: {0}")]
+    EmptyAttributeKey(String),
 
-    #[error("Empty attribute value. Key: {key}")]
-    EmptyAttributeValue { key: String },
+    /// Error variant for reporting an empty attribute value.
+    #[error("Empty attribute value. Key: {0}")]
+    EmptyAttributeValue(String),
 
+    /// Error variant for reporting a usage of reserved key prefix.
     #[error("Attribute key starts with reserved prefix _: {0}")]
     ReservedAttributeKey(String),
 
+    /// Error variant for reporting too short event types.
     #[error("Event type too short: {0}")]
     EventTypeTooShort(String),
 
+    /// Error variant for reporting that unsupported wasm query was encountered during processing.
     #[error("Unsupported wasm query: {0:?}")]
     UnsupportedWasmQuery(WasmQuery),
 
+    /// Error variant for reporting that unsupported wasm message was encountered during processing.
     #[error("Unsupported wasm message: {0:?}")]
     UnsupportedWasmMsg(WasmMsg),
 
+    /// Error variant for reporting invalid contract code.
     #[error("code id: invalid")]
     InvalidCodeId,
 
+    /// Error variant for reporting unregistered contract code.
     #[error("code id {0}: no such code")]
     UnregisteredCodeId(u64),
 
+    /// Error variant for reporting duplicated contract addresses.
     #[error("Contract with this address already exists: {0}")]
     DuplicatedContractAddress(String),
 }
 
 impl Error {
+    /// Creates an instance of the [Error](Self) for empty attribute key.
     pub fn empty_attribute_key(value: impl Into<String>) -> Self {
-        Self::EmptyAttributeKey {
-            value: value.into(),
-        }
+        Self::EmptyAttributeKey(value.into())
     }
 
+    /// Creates an instance of the [Error](Self) for empty attribute value.
     pub fn empty_attribute_value(key: impl Into<String>) -> Self {
-        Self::EmptyAttributeValue { key: key.into() }
+        Self::EmptyAttributeValue(key.into())
     }
 
+    /// Creates an instance of the [Error](Self) when reserved attribute key was used.
     pub fn reserved_attribute_key(key: impl Into<String>) -> Self {
         Self::ReservedAttributeKey(key.into())
     }
 
+    /// Creates an instance of the [Error](Self) for too short event types.
     pub fn event_type_too_short(ty: impl Into<String>) -> Self {
         Self::EventTypeTooShort(ty.into())
     }
 
+    /// Creates an instance of the [Error](Self) for duplicated contract addresses.
     pub fn duplicated_contract_address(address: impl Into<String>) -> Self {
         Self::DuplicatedContractAddress(address.into())
     }
diff --git a/src/executor.rs b/src/executor.rs
index ec1672d..d5932ca 100644
--- a/src/executor.rs
+++ b/src/executor.rs
@@ -7,25 +7,29 @@ use cw_utils::{parse_execute_response_data, parse_instantiate_response_data};
 use schemars::JsonSchema;
 use serde::Serialize;
 use std::fmt::Debug;
-/// AppResponse likely refers to a standardized response format from the App.
-/// It's mentioned in the cw-multi-test-main package, which suggests it's used for returning
-/// information about the processing of transactions or queries.
+
+/// A subset of data returned as a response of a contract entry point,
+/// such as `instantiate`, `execute` or `migrate`.
 #[derive(Default, Clone, Debug)]
 pub struct AppResponse {
+    /// Response events.
     pub events: Vec<Event>,
+    /// Response data.
     pub data: Option<Binary>,
 }
 
 impl AppResponse {
-    // Return all custom attributes returned by the contract in the `idx` event.
-    // We assert the type is wasm, and skip the contract_address attribute.
+    /// Returns all custom attributes returned by the contract in the `idx` event.
+    ///
+    /// We assert the type is wasm, and skip the contract_address attribute.
     #[track_caller]
     pub fn custom_attrs(&self, idx: usize) -> &[Attribute] {
         assert_eq!(self.events[idx].ty.as_str(), "wasm");
         &self.events[idx].attributes[1..]
     }
 
-    /// Check if there is an Event that is a super-set of this.
+    /// Checks if there is an Event that is a super-set of this.
+    ///
     /// It has the same type, and all compare.attributes are included in it as well.
     /// You don't need to specify them all.
     pub fn has_event(&self, expected: &Event) -> bool {
@@ -38,7 +42,7 @@ impl AppResponse {
         })
     }
 
-    /// Like has_event but panics if no match
+    /// Like [has_event](Self::has_event) but panics if there is no match.
     #[track_caller]
     pub fn assert_event(&self, expected: &Event) {
         assert!(
@@ -60,16 +64,19 @@ impl From<SubMsgResponse> for AppResponse {
         }
     }
 }
-///Defines the interface for executing transactions and contract interactions.
-/// It's a central component in the testing framework, managing the operational flow and
-/// ensuring that contract calls are processed correctly.
+/// A trait defining a default behavior of the message executor.
+///
+/// Defines the interface for executing transactions and contract interactions.
+/// It is a central component in the testing framework, managing the operational
+/// flow and ensuring that contract _calls_ are processed correctly.
 pub trait Executor<C>
 where
     C: Clone + Debug + PartialEq + JsonSchema + 'static,
 {
-    /// Runs arbitrary CosmosMsg.
-    /// This will create a cache before the execution, so no state changes are persisted if this
-    /// returns an error, but all are persisted on success.
+    /// Processes (executes) an arbitrary `CosmosMsg`.
+    /// This will create a cache before the execution,
+    /// so no state changes are persisted if this returns an error,
+    /// but all are persisted on success.
     fn execute(&mut self, sender: Addr, msg: CosmosMsg<C>) -> AnyResult<AppResponse>;
 
     /// Create a contract and get the new address.
@@ -132,8 +139,9 @@ where
     }
 
     /// Execute a contract and process all returned messages.
-    /// This is just a helper around execute(),
-    /// but we parse out the data field to that what is returned by the contract (not the protobuf wrapper)
+    /// This is just a helper function around [execute()](Self::execute)
+    /// with `WasmMsg::Execute` message, but in this case we parse out the data field
+    /// to that what is returned by the contract (not the protobuf wrapper).
     fn execute_contract<T: Serialize + Debug>(
         &mut self,
         sender: Addr,
@@ -154,8 +162,10 @@ where
         Ok(res)
     }
 
-    /// Migrate a contract. Sender must be registered admin.
-    /// This is just a helper around execute()
+    /// Migrates a contract.
+    /// Sender must be registered admin.
+    /// This is just a helper function around [execute()](Self::execute)
+    /// with `WasmMsg::Migrate` message.
     fn migrate_contract<T: Serialize>(
         &mut self,
         sender: Addr,
@@ -172,6 +182,9 @@ where
         self.execute(sender, msg.into())
     }
 
+    /// Sends tokens to specified recipient.
+    /// This is just a helper function around [execute()](Self::execute)
+    /// with `BankMsg::Send` message.
     fn send_tokens(
         &mut self,
         sender: Addr,
diff --git a/src/lib.rs b/src/lib.rs
index 7f44d30..ea0bdcb 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,10 +1,128 @@
-//! Multitest is a design to simulate a blockchain environment in pure Rust.
-//! This allows us to run unit tests that involve contract -> contract,
-//! and contract -> bank interactions. This is not intended to be a full blockchain app
-//! but to simulate the Cosmos SDK x/wasm module close enough to gain confidence in
-//! multi-contract deployments before testing them on a live blockchain.
+//! # CosmWasm MultiTest
 //!
-//! To understand the design of this module, please refer to `../DESIGN.md`
+//! **CosmWasm MultiTest** is designed to simulate a blockchain environment in pure Rust.
+//! This allows to run unit tests that involve **contract 🡘 contract**,
+//! and **contract 🡘 module** interactions. **CosmWasm MultiTest** is not intended
+//! to be a full blockchain application, but to simulate the Cosmos SDK x/wasm module close enough
+//! to gain confidence in multi-contract deployments, before testing them on a live blockchain.
+//!
+//! The following sections explains some of the design for those who want to use the API,
+//! as well as those who want to take a look under the hood of **CosmWasm MultiTest**.
+//!
+//! ## Key APIs
+//!
+//! ### App
+//!
+//! The main entry point to the system is called [App], which represents a blockchain application.
+//! It maintains an idea of block height and time, which can be updated to simulate multiple
+//! blocks. You can use application's [update_block](App::update_block) method to increment
+//! the timestamp by 5 seconds and the height by 1 (simulating a new block) or you can write
+//! any other mutator of [BlockInfo](cosmwasm_std::BlockInfo) to advance more.
+//!
+//! [App] exposes an entry point [execute](App::execute) that allows to execute
+//! any [CosmosMsg](cosmwasm_std::CosmosMsg) and wraps it in an atomic transaction.
+//! That is, only if [execute](App::execute) returns a success, then the state will be committed.
+//! It returns the data and a list of [Event](cosmwasm_std::Event)s on successful execution
+//! or an **`Err(String)`** on error. There are some helper methods tied to the [Executor] trait
+//! that create the [CosmosMsg](cosmwasm_std::CosmosMsg) for you to provide a less verbose API.
+//! [App]'s methods like [instantiate_contract](App::instantiate_contract),
+//! [execute_contract](App::execute_contract), and [send_tokens](App::send_tokens) are exposed
+//! for your convenience in writing tests.
+//! Each method executes one [CosmosMsg](cosmwasm_std::CosmosMsg) atomically, as if it was submitted by a user.
+//! You can also use [execute_multi](App::execute_multi) if you wish to execute multiple messages together
+//! that revert the state as a whole in case of any failure.
+//!
+//! The other key entry point to [App] is the [Querier](cosmwasm_std::Querier) interface that it implements.
+//! In particular, you can use [wrap](App::wrap) to get a [QuerierWrapper](cosmwasm_std::QuerierWrapper),
+//! which provides all kinds of interesting APIs to query the blockchain, like
+//! [query_all_balances](cosmwasm_std::QuerierWrapper::query_all_balances) and
+//! [query_wasm_smart](cosmwasm_std::QuerierWrapper::query_wasm_smart).
+//! Putting this all together, you have one [Storage](cosmwasm_std::Storage) wrapped into an application,
+//! where you can execute contracts and bank, query them easily, and update the current
+//! [BlockInfo](cosmwasm_std::BlockInfo), in an API that is not very verbose or cumbersome.
+//! Under the hood it will process all messages returned from contracts, move _bank_ tokens
+//! and call into other contracts.
+//!
+//! You can easily create an [App] for use in your testcode like shown below.
+//! Having a single utility function for creating and configuring the [App] is the common
+//! pattern while testing contracts with **CosmWasm MultiTest**.
+//!
+//! ```
+//! use cw_multi_test::App;
+//!
+//! fn mock_app() -> App {
+//!   App::default()
+//! }
+//! ```
+//!
+//! The [App] maintains the root [Storage](cosmwasm_std::Storage), and the [BlockInfo](cosmwasm_std::BlockInfo)
+//! for the current block. It also contains a [Router] (discussed below), which can process
+//! any [CosmosMsg](cosmwasm_std::CosmosMsg) variant by passing it to the proper keeper.
+//!
+//! > **Note**: [App] properly handles submessages and reply blocks.
+//!
+//! > **Note**: While the API currently supports custom messages, we don't currently have an implementation
+//! > of the default keeper, except of experimental [CachingCustomHandler](custom_handler::CachingCustomHandler).
+//!
+//! ### Contracts
+//!
+//! Before you can call contracts, you must **instantiate** them. And to instantiate them, you need a `code_id`.
+//! In `wasmd`, this `code_id` points to some stored Wasm code that is then run. In multitest, we use it to
+//! point to a `Box<dyn Contract>` that should be run. That is, you need to implement the [Contract] trait
+//! and then add the contract to the [App] via [store_code](App::store_code) function.
+//!
+//! The [Contract] trait defines the major entry points to any CosmWasm contract:
+//! [instantiate](Contract::instantiate), [execute](Contract::execute), [query](Contract::query),
+//! [sudo](Contract::sudo), [reply](Contract::reply) (for submessages) and [migrate](Contract::migrate).
+//!
+//! In order to easily implement [Contract] from some existing contract code, we use the [ContractWrapper] struct,
+//! which takes some function pointers and combines them. You can take a look at **test_helpers** module
+//! for some examples or how to do so (and useful mocks for some test cases).
+//! Here is an example of wrapping a CosmWasm contract into a [Contract] trait to be added to an [App]:
+//!
+//! ```
+//! use cosmwasm_std::Empty;
+//! use cw1_whitelist::contract::{execute, instantiate, query};
+//! use cw_multi_test::{App, Contract, ContractWrapper};
+//!
+//! pub fn contract_whitelist() -> Box<dyn Contract<Empty>> {
+//!     Box::new(ContractWrapper::new(execute, instantiate, query))
+//! }
+//!
+//! let mut app = App::default();
+//! let code_id = app.store_code(contract_whitelist());
+//! // use this code_id to instantiate a contract
+//! ```
+//!
+//! ### Modules
+//!
+//! There is only one root [Storage](cosmwasm_std::Storage), stored inside [App].
+//! This is wrapped into a transaction, and then passed down to other functions to work with.
+//! The code that modifies the Storage is divided into _modules_ much like the CosmosSDK.
+//! Currently the message processing logic is divided into one _module_ for every [CosmosMsg](cosmwasm_std) variant.
+//! [Bank] handles [BankMsg](cosmwasm_std::BankMsg) and [BankQuery](cosmwasm_std::BankQuery),
+//! [Wasm] handles [WasmMsg](cosmwasm_std::WasmMsg) and [WasmQuery](cosmwasm_std::WasmQuery), etc.
+//!
+//! ### Router
+//!
+//! The [Router] groups all modules in the system into one "macro-module" that can handle
+//! any [CosmosMsg](cosmwasm_std::CosmosMsg). While [Bank] handles [BankMsg](cosmwasm_std::BankMsg),
+//! and [Wasm] handles [WasmMsg](cosmwasm_std::WasmMsg), we need to combine them into a larger composite
+//! to let them process messages from [App]. This is the whole concept of the [Router].
+//! If you take a look at the [execute](Router::execute) method, you will see it is quite straightforward.
+//!
+//! Note that the only way one module can call or query another module is by dispatching messages via the [Router].
+//! This allows us to implement an independent [Wasm] in a way that it can process [SubMsg](cosmwasm_std::SubMsg)
+//! that call into [Bank]. You can see an example of that in _send_ method of the [WasmKeeper],
+//! where it moves bank tokens from one account to another.
+//!
+//! ### Addons
+//!
+//! (tbd)
+
+#![deny(missing_docs)]
+#![deny(rustdoc::broken_intra_doc_links)]
+#![deny(rustdoc::missing_crate_level_docs)]
 
 pub mod addons;
 mod addresses;
@@ -12,7 +130,6 @@ mod app;
 mod app_builder;
 mod bank;
 mod checksums;
-#[allow(clippy::type_complexity)]
 mod contracts;
 pub mod custom_handler;
 pub mod error;
diff --git a/src/module.rs b/src/module.rs
index 79f7b3f..aac82ba 100644
--- a/src/module.rs
+++ b/src/module.rs
@@ -7,12 +7,18 @@ use serde::de::DeserializeOwned;
 use std::fmt::Debug;
 use std::marker::PhantomData;
 
+/// # General module
+///
 /// Provides a generic interface for modules within the test environment.
-/// It's essential for creating modular and extensible testing setups, allowing developers
-/// to integrate custom functionalities or test specific scenarios.
+/// It is essential for creating modular and extensible testing setups,
+/// allowing developers to integrate custom functionalities
+/// or test specific scenarios.
 pub trait Module {
+    /// Type of messages processed by the module instance.
     type ExecT;
+    /// Type of queries processed by the module instance.
     type QueryT;
+    /// Type of privileged messages used by the module instance.
     type SudoT;
 
     /// Runs any [ExecT](Self::ExecT) message,
@@ -58,18 +64,21 @@ pub trait Module {
         ExecC: Debug + Clone + PartialEq + JsonSchema + DeserializeOwned + 'static,
         QueryC: CustomQuery + DeserializeOwned + 'static;
 }
-/// This could be a diagnostic or testing tool within the Cosmos ecosystem, designed to
-/// intentionally fail under certain conditions to test the robustness and error-handling
-/// capabilities of the network.
+/// # Always failing module
+///
+/// This could be a diagnostic or testing tool within the Cosmos ecosystem,
+/// designed to intentionally fail during processing any message, query or privileged action.
 pub struct FailingModule<ExecT, QueryT, SudoT>(PhantomData<(ExecT, QueryT, SudoT)>);
 
 impl<ExecT, QueryT, SudoT> FailingModule<ExecT, QueryT, SudoT> {
+    /// Creates an instance of a failing module.
     pub fn new() -> Self {
         Self(PhantomData)
     }
 }
 
 impl<ExecT, QueryT, SudoT> Default for FailingModule<ExecT, QueryT, SudoT> {
+    /// Creates a default instance of a failing module.
     fn default() -> Self {
         Self::new()
     }
@@ -122,17 +131,21 @@ where
         bail!("Unexpected sudo msg {:?}", msg)
     }
 }
-///This struct might represent a module in the Cosmos ecosystem designed to accept certain types of transactions
-/// or interactions. The specific functionality would depend on the context of its use.
+/// # Always accepting module
+///
+/// This struct represents a module in the Cosmos ecosystem designed to
+/// always accept all processed messages, queries and privileged actions.
 pub struct AcceptingModule<ExecT, QueryT, SudoT>(PhantomData<(ExecT, QueryT, SudoT)>);
 
 impl<ExecT, QueryT, SudoT> AcceptingModule<ExecT, QueryT, SudoT> {
+    /// Creates an instance of an accepting module.
     pub fn new() -> Self {
         Self(PhantomData)
     }
 }
 
 impl<ExecT, QueryT, SudoT> Default for AcceptingModule<ExecT, QueryT, SudoT> {
+    /// Creates an instance of an accepting module with default settings.
     fn default() -> Self {
         Self::new()
     }
@@ -161,7 +174,7 @@ where
         Ok(AppResponse::default())
     }
 
-    /// Runs any [QueryT](Self::QueryT) message, always returns an empty binary.
+    /// Runs any [QueryT](Self::QueryT) message, always returns a default (empty) binary.
     fn query(
         &self,
         _api: &dyn Api,
diff --git a/src/staking.rs b/src/staking.rs
index 9e6fd0a..8e11e56 100644
--- a/src/staking.rs
+++ b/src/staking.rs
@@ -14,7 +14,7 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use std::collections::{BTreeSet, VecDeque};
 
-// Contains some general staking parameters
+/// A structure containing some general staking parameters.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct StakingInfo {
     /// The denominator of the staking token
@@ -26,6 +26,7 @@ pub struct StakingInfo {
 }
 
 impl Default for StakingInfo {
+    /// Creates staking info with default settings.
     fn default() -> Self {
         StakingInfo {
             bonded_denom: "TOKEN".to_string(),
@@ -101,13 +102,17 @@ pub const NAMESPACE_STAKING: &[u8] = b"staking";
 // https://github.com/cosmos/cosmos-sdk/blob/4f6f6c00021f4b5ee486bbb71ae2071a8ceb47c9/x/distribution/types/keys.go#L16
 pub const NAMESPACE_DISTRIBUTION: &[u8] = b"distribution";
 
-// We need to expand on this, but we will need this to properly test out staking
-#[derive(Clone, std::fmt::Debug, PartialEq, Eq, JsonSchema)]
+/// Staking privileged action definition.
+///
+/// We need to expand on this, but we will need this to properly test out staking
+#[derive(Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub enum StakingSudo {
     /// Slashes the given percentage of the validator's stake.
     /// For now, you cannot slash retrospectively in tests.
     Slash {
+        /// Validator's address.
         validator: String,
+        /// Percentage of the validator's stake.
         percentage: Decimal,
     },
     /// Causes the unbonding queue to be processed.
@@ -117,12 +122,13 @@ pub enum StakingSudo {
     ProcessQueue {},
 }
 
-///Manages staking operations, vital for testing contracts in proof-of-stake (PoS) blockchain environments.
-///This trait simulates staking behaviors, including delegation, validator operations, and reward mechanisms.
+/// A trait defining a behavior of the stake keeper.
+///
+/// Manages staking operations, vital for testing contracts in proof-of-stake (PoS) blockchain environments.
+/// This trait simulates staking behaviors, including delegation, validator operations, and reward mechanisms.
 pub trait Staking: Module<ExecT = StakingMsg, QueryT = StakingQuery, SudoT = StakingSudo> {
     /// This is called from the end blocker (`update_block` / `set_block`) to process the
-    /// staking queue.
-    /// Needed because unbonding has a waiting time.
+    /// staking queue. Needed because unbonding has a waiting time.
     /// If you're implementing a dummy staking module, this can be a no-op.
     fn process_queue<ExecC, QueryC: CustomQuery>(
         &self,
@@ -133,19 +139,24 @@ pub trait Staking: Module<ExecT = StakingMsg, QueryT = StakingQuery, SudoT = Sta
     ) -> AnyResult<AppResponse>;
 }
 
+/// A trait defining a behavior of the distribution keeper.
 pub trait Distribution: Module<ExecT = DistributionMsg, QueryT = Empty, SudoT = Empty> {}
-///
+
+/// A structure representing a default stake keeper.
 pub struct StakeKeeper {
+    /// Module address of a default stake keeper.
     module_addr: Addr,
 }
 
 impl Default for StakeKeeper {
+    /// Creates a new stake keeper with default settings.
     fn default() -> Self {
         Self::new()
     }
 }
 
 impl StakeKeeper {
+    /// Creates a new stake keeper with default module address.
     pub fn new() -> Self {
         StakeKeeper {
             // The address of the staking module. This holds all staked tokens.
@@ -156,7 +167,6 @@ impl StakeKeeper {
     /// Provides some general parameters to the stake keeper
     pub fn setup(&self, storage: &mut dyn Storage, staking_info: StakingInfo) -> AnyResult<()> {
         let mut storage = prefixed(storage, NAMESPACE_STAKING);
-
         STAKING_INFO.save(&mut storage, &staking_info)?;
         Ok(())
     }
@@ -867,6 +877,8 @@ impl Module for StakeKeeper {
     }
 }
 
+/// A structure representing a default distribution keeper.
+///
 /// This module likely manages the distribution of rewards and fees within the blockchain network.
 /// It could handle tasks like distributing block rewards to validators and delegators,
 /// and managing community funding mechanisms.
@@ -874,8 +886,9 @@ impl Module for StakeKeeper {
 pub struct DistributionKeeper {}
 
 impl DistributionKeeper {
+    /// Creates a new distribution keeper with default settings.
     pub fn new() -> Self {
-        DistributionKeeper {}
+        Self::default()
     }
 
     /// Removes all rewards from the given (delegator, validator) pair and returns the amount
@@ -902,6 +915,7 @@ impl DistributionKeeper {
         Ok(rewards)
     }
 
+    /// Returns the withdraw address for specified delegator.
     pub fn get_withdraw_address(storage: &dyn Storage, delegator: &Addr) -> AnyResult<Addr> {
         Ok(match WITHDRAW_ADDRESS.may_load(storage, delegator)? {
             Some(a) => a,
@@ -909,7 +923,9 @@ impl DistributionKeeper {
         })
     }
 
-    // https://docs.cosmos.network/main/modules/distribution#msgsetwithdrawaddress
+    /// Sets (changes) the [withdraw address] of the delegator.
+    ///
+    /// [withdraw address]: https://docs.cosmos.network/main/modules/distribution#msgsetwithdrawaddress
     pub fn set_withdraw_address(
         storage: &mut dyn Storage,
         delegator: &Addr,
diff --git a/src/stargate.rs b/src/stargate.rs
index 39d23aa..b8127c2 100644
--- a/src/stargate.rs
+++ b/src/stargate.rs
@@ -8,7 +8,7 @@ use std::fmt::Debug;
 
 /// Stargate interface.
 ///
-/// This trait provides the default behaviour for all functions
+/// This trait provides the default behavior for all functions
 /// that is equal to [StargateFailing] implementation.
 pub trait Stargate {
     /// Processes stargate messages.
diff --git a/src/wasm.rs b/src/wasm.rs
index 72c497b..94c3c46 100644
--- a/src/wasm.rs
+++ b/src/wasm.rs
@@ -30,13 +30,17 @@ pub(crate) const NAMESPACE_WASM: &[u8] = b"wasm";
 /// See <https://github.com/chipshort/wasmd/blob/d0e3ed19f041e65f112d8e800416b3230d0005a2/x/wasm/types/events.go#L58>
 const CONTRACT_ATTR: &str = "_contract_address";
 
+/// A structure representing a privileged message.
 #[derive(Clone, Debug, PartialEq, Eq, JsonSchema)]
 pub struct WasmSudo {
+    /// Address of a contract the privileged action will be sent to.
     pub contract_addr: Addr,
+    /// Message representing privileged action to be executed by contract `sudo` entry-point.
     pub msg: Binary,
 }
 
 impl WasmSudo {
+    /// Creates a new privileged message for specified contract address and action to be executed.
     pub fn new<T: Serialize>(contract_addr: &Addr, msg: &T) -> StdResult<WasmSudo> {
         Ok(WasmSudo {
             contract_addr: contract_addr.clone(),
@@ -121,6 +125,7 @@ pub trait Wasm<ExecC, QueryC> {
     fn dump_wasm_raw(&self, storage: &dyn Storage, address: &Addr) -> Vec<Record>;
 }
 
+/// A structure representing a default wasm keeper.
 pub struct WasmKeeper<ExecC, QueryC> {
     /// Contract codes that stand for wasm code in real-life blockchain.
     code_base: Vec<Box<dyn Contract<ExecC, QueryC>>>,
@@ -357,6 +362,19 @@ where
     ExecC: Clone + Debug + PartialEq + JsonSchema + DeserializeOwned + 'static,
     QueryC: CustomQuery + DeserializeOwned + 'static,
 {
+    /// Creates a wasm keeper with default settings.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use cw_multi_test::{AppBuilder, no_init, WasmKeeper};
+    ///
+    /// // create wasm keeper
+    /// let wasm_keeper = WasmKeeper::new();
+    ///
+    /// // create and use the application with newly created wasm keeper
+    /// let mut app = AppBuilder::default().with_wasm(wasm_keeper).build(no_init);
+    /// ```
     pub fn new() -> Self {
         Self::default()
     }
@@ -365,6 +383,9 @@ where
         since = "0.18.0",
         note = "use `WasmKeeper::new().with_address_generator` instead; will be removed in version 1.0.0"
     )]
+    /// Populates an existing [WasmKeeper] with custom contract address generator.
+    ///
+    /// See description of [with_address_generator](Self::with_address_generator) function for details.
     pub fn new_with_custom_address_generator(
         address_generator: impl AddressGenerator + 'static,
     ) -> Self {
@@ -374,6 +395,36 @@ where
         }
     }
 
+    /// Populates an existing [WasmKeeper] with custom contract address generator.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use cosmwasm_std::{Addr, Api, Storage};
+    /// use cw_multi_test::{AddressGenerator, AppBuilder, no_init, WasmKeeper};
+    /// use cw_multi_test::error::AnyResult;
+    ///
+    /// struct CustomAddressGenerator;
+    ///
+    /// impl AddressGenerator for CustomAddressGenerator {
+    ///     fn contract_address(
+    ///         &self,
+    ///         api: &dyn Api,
+    ///         storage: &mut dyn Storage,
+    ///         code_id: u64,
+    ///         instance_id: u64,
+    ///     ) -> AnyResult<Addr> {
+    ///         // here implement your address generation logic
+    /// #       Ok(Addr::unchecked("test_address"))
+    ///     }
+    /// }
+    ///
+    /// // populate wasm with your custom address generator
+    /// let wasm_keeper = WasmKeeper::new().with_address_generator(CustomAddressGenerator);
+    ///
+    /// // create and use the application with customized wasm keeper
+    /// let mut app = AppBuilder::default().with_wasm(wasm_keeper).build(no_init);
+    /// ```
     pub fn with_address_generator(
         mut self,
         address_generator: impl AddressGenerator + 'static,
@@ -382,6 +433,29 @@ where
         self
     }
 
+    /// Populates an existing [WasmKeeper] with custom checksum generator for the contract code.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use cosmwasm_std::{Addr, HexBinary};
+    /// use cw_multi_test::{AppBuilder, ChecksumGenerator, no_init, WasmKeeper};
+    ///
+    /// struct MyChecksumGenerator;
+    ///
+    /// impl ChecksumGenerator for MyChecksumGenerator {
+    ///     fn checksum(&self, creator: &Addr, code_id: u64) -> HexBinary {
+    ///         // here implement your custom checksum generator
+    /// #       HexBinary::default()
+    ///     }
+    /// }
+    ///
+    /// // populate wasm keeper with your custom checksum generator
+    /// let wasm_keeper = WasmKeeper::new().with_checksum_generator(MyChecksumGenerator);
+    ///
+    /// // create and use the application with customized wasm keeper
+    /// let mut app = AppBuilder::default().with_wasm(wasm_keeper).build(no_init);
+    /// ```
     pub fn with_checksum_generator(
         mut self,
         checksum_generator: impl ChecksumGenerator + 'static,
@@ -390,6 +464,7 @@ where
         self
     }
 
+    /// Executes contract's `query` entry-point.
     pub fn query_smart(
         &self,
         address: Addr,
@@ -409,6 +484,7 @@ where
         )
     }
 
+    /// Returns the value stored under specified key in contracts storage.
     pub fn query_raw(&self, address: Addr, storage: &dyn Storage, key: &[u8]) -> Binary {
         let storage = self.contract_storage_readonly(storage, &address);
         let data = storage.get(key).unwrap_or_default();
@@ -882,6 +958,7 @@ where
         Ok(addr)
     }
 
+    /// Executes contract's `execute` entry-point.
     pub fn call_execute(
         &self,
         api: &dyn Api,
@@ -902,6 +979,7 @@ where
         )?)
     }
 
+    /// Executes contract's `instantiate` entry-point.
     pub fn call_instantiate(
         &self,
         address: Addr,
@@ -922,6 +1000,7 @@ where
         )?)
     }
 
+    /// Executes contract's `reply` entry-point.
     pub fn call_reply(
         &self,
         address: Addr,
@@ -941,6 +1020,7 @@ where
         )?)
     }
 
+    /// Executes contract's `sudo` entry-point.
     pub fn call_sudo(
         &self,
         address: Addr,
@@ -960,6 +1040,7 @@ where
         )?)
     }
 
+    /// Executes contract's `migrate` entry-point.
     pub fn call_migrate(
         &self,
         address: Addr,
@@ -1048,6 +1129,7 @@ where
         })
     }
 
+    /// Saves contract data in a storage under specified address.
     pub fn save_contract(
         &self,
         storage: &mut dyn Storage,


Test patch:
diff --git a/src/tests/test_custom_handler.rs b/src/tests/test_custom_handler.rs
index 2bc821b..7ded4f7 100644
--- a/src/tests/test_custom_handler.rs
+++ b/src/tests/test_custom_handler.rs
@@ -71,7 +71,7 @@ fn custom_handler_has_no_sudo() {
 
     // run sudo function
     assert_eq!(
-        "Unexpected sudo msg Empty",
+        "Unexpected custom sudo message Empty",
         custom_handler
             .sudo(
                 app.api(),
diff --git a/tests/test_wasm/test_with_addr_gen.rs b/tests/test_wasm/test_with_addr_gen.rs
index f536b69..af0035c 100644
--- a/tests/test_wasm/test_with_addr_gen.rs
+++ b/tests/test_wasm/test_with_addr_gen.rs
@@ -53,7 +53,7 @@ fn custom_address_generator_should_work() {
     struct CustomAddressGenerator;
 
     impl AddressGenerator for CustomAddressGenerator {
-        // deprecated from version 0.18.0
+        // deprecated since version 0.18.0
         fn next_address(&self, _storage: &mut dyn Storage) -> Addr {
             // Panic in case of calling this function
             unreachable!("this function should not be called")
diff --git a/tests/test_wasm/test_with_checksum_gen.rs b/tests/test_wasm/test_with_checksum_gen.rs
index 8917a29..89b7d60 100644
--- a/tests/test_wasm/test_with_checksum_gen.rs
+++ b/tests/test_wasm/test_with_checksum_gen.rs
@@ -1,7 +1,7 @@
 #![cfg(feature = "cosmwasm_1_2")]
 
 use crate::test_contracts;
-use cosmwasm_std::{Addr, Empty, HexBinary};
+use cosmwasm_std::{Addr, HexBinary};
 use cw_multi_test::{no_init, App, AppBuilder, ChecksumGenerator, WasmKeeper};
 
 #[test]
@@ -37,8 +37,7 @@ impl ChecksumGenerator for MyChecksumGenerator {
 #[test]
 fn custom_checksum_generator_should_work() {
     // prepare wasm keeper with custom checksum generator
-    let wasm_keeper: WasmKeeper<Empty, Empty> =
-        WasmKeeper::default().with_checksum_generator(MyChecksumGenerator);
+    let wasm_keeper = WasmKeeper::new().with_checksum_generator(MyChecksumGenerator);
 
     // prepare application with custom wasm keeper
     let mut app = AppBuilder::default().with_wasm(wasm_keeper).build(no_init);