Add natspec comments for adapter update process (#792)

Author: hieronx

src/core/hub/interfaces/IHub.sol

@@ -425,7 +425,18 @@ interface IHub is IBatchedMulticall {
     /// @param credits Array of credit journal entries
     function updateJournal(PoolId poolId, JournalEntry[] memory debits, JournalEntry[] memory credits) external payable;
 
-    /// @notice Set adapters for a pool in another chain
+    /// @notice Set adapters for a pool in another chain.
+    /// @dev    Changing adapters increments the session ID, which invalidates any messages that were sent
+    ///         before the update but not yet delivered. To avoid failed deliveries, block outgoing messages on all
+    ///         affected chains before calling this function, and unblock after the new configuration has been delivered:
+    ///
+    ///         1. Grant gateway manager role on each affected chain via `updateGatewayManager`
+    ///         2. Call `gateway.blockOutgoing(canSend=false)` on each affected chain to pause outgoing messages
+    ///         3. Wait for all pending message deliveries to complete
+    ///         4. Call `setAdapters` with the new configuration
+    ///         5. Wait for the adapter update to be delivered
+    ///         6. Call `gateway.blockOutgoing(canSend=true)` on each affected chain to resume
+    ///
     /// @param poolId Pool associated to this configuration
     /// @param centrifugeId Chain where to perform the adapter configuration
     /// @param localAdapters Adapter addresses in this chain

src/core/messaging/interfaces/IGateway.sol

@@ -119,7 +119,9 @@ interface IGateway is IMessageHandler, IRecoverable {
     /// @param canManage If enabled as manager
     function updateManager(PoolId poolId, address who, bool canManage) external;
 
-    /// @notice Indicates if the gateway for a determined pool can send messages or not
+    /// @notice Block or unblock outgoing messages for a pool on a specific chain.
+    /// @dev    Used during adapter migrations to ensure no messages are in-flight while the adapter
+    ///         configuration is being updated. See `IHub.setAdapters` for the full procedure.
     /// @param centrifugeId Centrifuge ID associated to this block
     /// @param poolId PoolId associated to this block
     /// @param canSend If can send messages or not