docs: improved channel closure docs (cosmos#5170)

* docs: improved channel closure docs

* docs: ran linter

docs/docs/01-ibc/01-overview.md

@@ -217,15 +217,27 @@ handshake; either `OnChanOpenInit` on the initializing chain or `OnChanOpenTry`
 #### Closing channels
 
 Closing a channel occurs in 2 handshake steps as defined in [ICS 04](https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics).
+Once a channel is closed, it cannot be reopened. The channel handshake steps are:
 
-`ChanCloseInit` closes a channel on the executing chain if the channel exists, it is not
-already closed and the connection it exists upon is OPEN. Channels can only be closed by a
-calling module or in the case of a packet timeout on an ORDERED channel.
+**`ChanCloseInit`** closes a channel on the executing chain if
 
-`ChanCloseConfirm` is a response to a counterparty channel executing `ChanCloseInit`. The channel
-on the executing chain closes if the channel exists, the channel is not already closed,
-the connection the channel exists upon is OPEN and the executing chain successfully verifies
-that the counterparty channel has been closed.
+- the channel exists and it is not already closed,
+- the connection it exists upon is OPEN,
+- the [IBC module callback `OnChanCloseInit`](./03-apps/02-ibcmodule.md#channel-closing-callbacks) returns `nil`.
+
+`ChanCloseInit` can be initiated by any user by submitting a `MsgChannelCloseInit` transaction. 
+Note that channels are automatically closed when a packet times out on an `ORDERED` channel.
+A timeout on an `ORDERED` channel skips the `ChanCloseInit` step and immediately closes the channel.
+
+**`ChanCloseConfirm`** is a response to a counterparty channel executing `ChanCloseInit`. The channel
+on the executing chain closes if
+
+- the channel exists and is not already closed,
+- the connection the channel exists upon is OPEN,
+- the executing chain successfully verifies that the counterparty channel has been closed
+- the [IBC module callback `OnChanCloseConfirm`](./03-apps/02-ibcmodule.md#channel-closing-callbacks) returns `nil`.
+
+Currently, none of the IBC applications provided in ibc-go support `ChanCloseInit`.
 
 ### [Packets](https://github.com/cosmos/ibc-go/blob/main/modules/core/04-channel)
 

docs/docs/01-ibc/03-apps/02-ibcmodule.md

@@ -141,8 +141,12 @@ func (im IBCModule) OnChanOpenConfirm(
 }
 ```
 
+### Channel closing callbacks
+
 The channel closing handshake will also invoke module callbacks that can return errors to abort the closing handshake. Closing a channel is a 2-step handshake, the initiating chain calls `ChanCloseInit` and the finalizing chain calls `ChanCloseConfirm`.
 
+Currently, all IBC modules in this repository return an error for `OnChanCloseInit` to prevent the channels from closing. This is because any user can call `ChanCloseInit` by submitting a `MsgChannelCloseInit` transaction.
+
 ```go
 // Called by IBC Handler on MsgCloseInit
 func (im IBCModule) OnChanCloseInit(

docs/docs/02-apps/01-transfer/01-overview.md

@@ -126,3 +126,7 @@ form.
 
 For safety, no other module must be capable of minting tokens with the `ibc/` prefix. The IBC
 transfer module needs a subset of the denomination space that only it can create tokens in.
+
+## Channel Closure
+
+The IBC transfer module does not support channel closure.

docs/docs/02-apps/02-interchain-accounts/01-overview.md

@@ -37,3 +37,8 @@ SDK modules on a chain are assumed to be trustworthy. For example, there are no
 The implementation of ICS-27 in ibc-go uses this assumption in its security considerations.
 
 The implementation assumes other IBC application modules will not bind to ports within the ICS-27 namespace.
+
+## Channel Closure
+
+The provided interchain account host and controller implementations do not support `ChanCloseInit`. However, they do support `ChanCloseConfirm`.
+This means that the host and controller modules cannot close channels, but they will confirm channel closures initiated by other implementations of ICS-27.