WIP: Expand ChannelManager documentation

Author: jkczyz

lightning/src/ln/channelmanager.rs

@@ -974,6 +974,37 @@ where
 /// Additionally, [`ChannelManager`] implements both [`chain::Listen`] and [`chain::Confirm`] for
 /// notification of on-chain events.
 ///
+/// # `ChannelManager` vs `ChannelMonitor`
+///
+/// It's important to distinguish between the *off-chain* management and *on-chain* monitoring of
+/// lightning channels. [`ChannelManager`] exchanges messages with peers to manage the off-chain
+/// state of each channel. During this process, it generates a [`ChannelMonitor`] for each channel
+/// and a [`ChannelMonitorUpdate`] for each relevant change, notifying its parameterized
+/// [`chain::Watch`] of them.
+///
+/// An implementation of [`chain::Watch`], such as [`ChainMonitor`], is responsible for aggregating
+/// these [`ChannelMonitor`]s and applying any [`ChannelMonitorUpdate`]s to them. It then monitors
+/// for any pertinent on-chain activity, broadcasting claims as needed.
+///
+/// This division of off-chain management and on-chain monitoring is what allows for interesting
+/// node setups. See the [`chain`] module for further details.
+///
+/// # Initialization
+///
+///	TODO
+///
+/// # Operation
+///
+///	TODO
+///	- event processing
+///	- timer ticks
+///	- chain data
+///	- persistence
+///
+/// # Payments
+///
+/// TODO
+///
 /// # Persistence
 ///
 /// Implements [`Writeable`] to write out all channel state to disk. Implies [`peer_disconnected`] for