Improve documentation of lazy deletion config

frame/contracts/src/lib.rs

@@ -206,10 +206,29 @@ pub mod pallet {
 		type CallStack: smallvec::Array<Item = Frame<Self>>;
 
 		/// The maximum number of tries that can be queued for deletion.
+		///
+		/// When a contract is deleted by calling `seal_terminate` it becomes inaccessible
+		/// immediatly but the deletion of the storage item it has accumulated is performaned
+		/// later. The contract address is put into the deletion queue. This defines how many
+		/// contracts can be queued up at the same time. If that limit is reached `seal_terminate`
+		/// will fail. The action then must be retried in a later block.
+		///
+		/// The reason for limiting the queue depth are:
+		///
+		/// 1. The queue is in storage in order to be persistent between blocks. We want to limit
+		/// 	the amount of storage that can be consumed.
+		/// 2. The queue is stored in a vector and needs to be decoded as a whole when reading
+		///		it at the end of each block. Longer queues take more weight to decode and hence
+		///		limit the amount of items that can be deleted per block.
 		#[pallet::constant]
 		type DeletionQueueDepth: Get<u32>;
 
 		/// The maximum amount of weight that can be consumed per block for lazy trie removal.
+		///
+		/// The amount of weight that is dedicated per block to work on the deletion queue. Larger
+		/// values allow more trie keys to be deleted in each each block but reduce the amount of
+		/// weight that is left for transactions. See [`Self::DeletionQueueDepth`] for more
+		/// information about the deletion queue.
 		#[pallet::constant]
 		type DeletionWeightLimit: Get<Weight>;
 
@@ -222,6 +241,7 @@ pub mod pallet {
 		type DepositPerByte: Get<BalanceOf<Self>>;
 
 		/// The amount of balance a caller has to pay for each storage item.
+		///
 		/// # Note
 		///
 		/// Changing this value for an existing chain might need a storage migration.