update docs

pallets/ah-migrator/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pallet-ah-migrator"
-description = "Asset Hub migrator pallet for Asset Hub"
+description = "Operational pallet managing and processing migration from Relay Chain to Asset Hub on Asset Hub"
 license = "Apache-2.0"
 version = "0.1.0"
 edition.workspace = true

pallets/ah-migrator/src/lib.rs

@@ -15,7 +15,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! The helper pallet for the Asset Hub migration meant to be setup on Asset Hub.
+//! The operational pallet for the Asset Hub, designed to manage and facilitate the migration of
+//! subsystems such as Governance, Staking, Balances from the Relay Chain to the Asset Hub. This
+//! pallet works alongside its counterpart, `pallet_rc_migrator`, which handles migration
+//! processes on the Relay Chain side.
+//!
+//! This pallet is responsible for controlling the initiation, progression, and completion of the
+//! migration process, including managing its various stages and transferring the necessary data.
+//! The pallet directly accesses the storage of other pallets for read/write operations while
+//! maintaining compatibility with their existing APIs.
+//!
+//! To simplify development and avoid the need to edit the original pallets, this pallet may
+//! duplicate private items such as storage entries from the original pallets. This ensures that the
+//! migration logic can be implemented without altering the original implementations.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
@@ -42,7 +54,8 @@ pub const LOG_TARGET: &str = "runtime::ah-migrator";
 pub mod pallet {
 	use super::*;
 
-	/// Super trait of all pallets the migration depends on.
+	/// Super config trait for all pallets that the migration depends on, providing convenient
+	/// access to their items.
 	#[pallet::config]
 	pub trait Config:
 		frame_system::Config<AccountData = AccountData<u128>, AccountId = AccountId32>
@@ -87,7 +100,7 @@ pub mod pallet {
 
 	#[pallet::call]
 	impl<T: Config> Pallet<T> {
-		// TODO: Currently, we use `debug_assert!` for basic test checks against a production
+		// TODO: Currently, we use `debug_assert!` for easy test checks against a production
 		// snapshot.
 
 		/// Receive accounts from the Relay Chain.

pallets/rc-migrator/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pallet-rc-migrator"
-description = "Asset Hub migrator pallet for Relay Chain"
+description = "Operational pallet managing and processing migration from Relay Chain to Asset Hub on Relay Chain"
 license = "Apache-2.0"
 version = "0.1.0"
 edition.workspace = true

pallets/rc-migrator/src/accounts.rs

@@ -19,6 +19,8 @@
 /*
 TODO: remove this dec comment when not needed
 
+Sources of account references
+
 provider refs:
 - crowdloans: fundraising system account / https://github.com/paritytech/polkadot-sdk/blob/ace62f120fbc9ec617d6bab0a5180f0be4441537/polkadot/runtime/common/src/crowdloan/mod.rs#L416
 - parachains_assigner_on_demand / on_demand: pallet's account https://github.com/paritytech/polkadot-sdk/blob/ace62f120fbc9ec617d6bab0a5180f0be4441537/polkadot/runtime/parachains/src/on_demand/mod.rs#L407
@@ -58,11 +60,14 @@ Relay: XCM teleport processed
 ^ The minimum what we should replay while moving accounts from Relay to AH
 
 When the Asset Hub turned to the mint authority
+
 Relay: let checking_total = // total checking account balance
 Relay: burn_from(checking, checking_total) // publishes Balances::Burned event
 AH: let total_issuance = // total issuance on AH
 AH: mint_into(checking, checking_total - total_issuance) // publishes Balances::Minted event
 
+^ Ensure that this is the desired method of communicating the mint authority change via events.
+
 */
 
 use crate::*;
@@ -97,7 +102,7 @@ pub struct Account<AccountId, Balance, HoldReason, FreezeReason> {
 	pub locks: Vec<BalanceLock<Balance>>,
 	/// Unnamed reserve.
 	///
-	/// No named reserves for Polkadot and Kusama.
+	/// Only unnamed reserves for Polkadot and Kusama (no named ones).
 	pub unnamed_reserve: Balance,
 	/// Consumer ref count of migrating to Asset Hub pallets except a reference for `reserved` and
 	/// `frozen` balance.

pallets/rc-migrator/src/lib.rs

@@ -15,7 +15,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! The helper pallet for the Asset Hub migration meant to be setup on Relay Chain.
+//! The operational pallet for the Relay Chain, designed to manage and facilitate the migration of
+//! subsystems such as Governance, Staking, Balances from the Relay Chain to the Asset Hub. This
+//! pallet works alongside its counterpart, `pallet_ah_migrator`, which handles migration
+//! processes on the Asset Hub side.
+//!
+//! This pallet is responsible for controlling the initiation, progression, and completion of the
+//! migration process, including managing its various stages and transferring the necessary data.
+//! The pallet directly accesses the storage of other pallets for read/write operations while
+//! maintaining compatibility with their existing APIs.
+//!
+//! To simplify development and avoid the need to edit the original pallets, this pallet may
+//! duplicate private items such as storage entries from the original pallets. This ensures that the
+//! migration logic can be implemented without altering the original implementations.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
@@ -56,7 +68,7 @@ pub enum MigrationStage<AccountId> {
 	/// The migration has not yet started.
 	#[default]
 	Pending,
-	// Initializing
+	// TODO: Initializing?
 	/// Migrating account balances.
 	MigratingAccounts {
 		// Last migrated account
@@ -76,7 +88,8 @@ pub mod pallet {
 	/// Paras Registrar Pallet
 	type ParasRegistrar<T> = paras_registrar::Pallet<T>;
 
-	/// Super trait of all pallets the migration depends on.
+	/// Super config trait for all pallets that the migration depends on, providing convenient
+	/// access to their items.
 	#[pallet::config]
 	pub trait Config:
 		frame_system::Config<AccountData = AccountData<u128>, AccountId = AccountId32>