Improving docstrings for UpgradableModule interface

modules/core/05-port/types/module.go

@@ -107,8 +107,12 @@ type IBCModule interface {
 }
 
 // UpgradableModule defines the callbacks required to perform a channel upgrade.
+// Note: applications must ensure that state related to packet processing remains unmodified until the OnChanUpgradeOpen callback is executed.
+// This guarantees that in-flight packets are correctly flushed using the existing channel parameters.
 type UpgradableModule interface {
-	// OnChanUpgradeInit initializes the channel upgrade handshake.
+	// OnChanUpgradeInit enables additional custom logic to be executed when the channel upgrade is initialized.
+	// It must validate the proposed version, order, and connection hops.
+	// Note: in the case of crossing hellos, this callback may be executed on both chains.
 	OnChanUpgradeInit(
 		ctx sdk.Context,
 		portID, channelID string,
@@ -117,7 +121,9 @@ type UpgradableModule interface {
 		version string,
 	) (string, error)
 
-	// OnChanUpgradeTry verifies the counterparty upgrade and sets the upgrade on TRY chain
+	// OnChanUpgradeTry enables additional custom logic to be executed in the ChannelUpgradeTry step of the
+	// channel upgrade handshake. It must validate the proposed version (provided by the counterparty), order,
+	// and connection hops.
 	OnChanUpgradeTry(
 		ctx sdk.Context,
 		portID, channelID string,
@@ -126,15 +132,18 @@ type UpgradableModule interface {
 		counterpartyVersion string,
 	) (string, error)
 
-	// OnChanUpgradeAck TODO
+	// OnChanUpgradeAck enables additional custom logic to be executed in the ChannelUpgradeAck step of the
+	// channel upgrade handshake. It must validate the version proposed by the counterparty.
 	OnChanUpgradeAck(
 		ctx sdk.Context,
 		portID,
 		channelID,
 		counterpartyVersion string,
 	) error
 
-	// OnChanUpgradeOpen TODO
+	// OnChanUpgradeOpen enables additional custom logic to be executed when the channel upgrade has successfully completed, and the channel
+	// has returned to the OPEN state. Any logic associated with changing of the channel fields should be performed
+	// in this callback.
 	OnChanUpgradeOpen(
 		ctx sdk.Context,
 		portID,
@@ -144,7 +153,11 @@ type UpgradableModule interface {
 		version string,
 	)
 
-	// OnChanUpgradeRestore TODO
+	// OnChanUpgradeRestore enables additional custom logic to be executed when any of the following occur:
+	//    - the channel upgrade is aborted.
+	//    - the channel upgrade is cancelled.
+	//    - the channel upgrade times out.
+	// Any logic set due to an upgrade attempt should be reverted in this callback.
 	OnChanUpgradeRestore(
 		ctx sdk.Context,
 		portID,