Update ChannelManager docs

Updates multipe instances of the `ChannelManager` docs related to the
previous change that moved the storage of the channels to the
`per_peer_state`. This docs update corrects some grammar errors and
incorrect information, as well as clarifies documentation that was
confusing.

Author: ViktorTigerstrom

lightning/src/ln/channelmanager.rs

@@ -743,9 +743,8 @@ where
 	/// very far in the past, and can only ever be up to two hours in the future.
 	highest_seen_timestamp: AtomicUsize,
 
-	/// The bulk of our storage will eventually be here (message queues and the like). Currently
-	/// the `per_peer_state` stores our channels on a per-peer basis, as well as the peer's latest
-	/// features.
+	/// The bulk of our storage. Currently the `per_peer_state` stores our channels on a per-peer
+	/// basis, as well as the peer's latest features.
 	///
 	/// If we are connected to a peer we always at least have an entry here, even if no channels
 	/// are currently open with that peer.
@@ -1196,7 +1195,7 @@ macro_rules! handle_error {
 					#[cfg(debug_assertions)]
 					{
 						if per_peer_state.get(&$counterparty_node_id).is_none() {
-							// This shouldn't occour in tests unless an unkown counterparty_node_id
+							// This shouldn't occur in tests unless an unknown counterparty_node_id
 							// has been passed to our message handling functions.
 							let expected_error_str = format!("Can't find a peer matching the passed counterparty node_id {}", $counterparty_node_id);
 							match err.action {
@@ -2229,7 +2228,8 @@ where
 	/// public, and thus should be called whenever the result is going to be passed out in a
 	/// [`MessageSendEvent::BroadcastChannelUpdate`] event.
 	///
-	/// May be called with peer_state already locked!
+	/// Note that this function may be called without the `peer_state` corresponding to the passed
+	/// channel's counterparty acquired, when the call site has full ownership of the channel.
 	fn get_channel_update_for_broadcast(&self, chan: &Channel<<SP::Target as SignerProvider>::Signer>) -> Result<msgs::ChannelUpdate, LightningError> {
 		if !chan.should_announce() {
 			return Err(LightningError {
@@ -2248,7 +2248,8 @@ where
 	/// is public (only returning an Err if the channel does not yet have an assigned short_id),
 	/// and thus MUST NOT be called unless the recipient of the resulting message has already
 	/// provided evidence that they know about the existence of the channel.
-	/// May be called with peer_state already locked!
+	/// Note that this function may be called without the `peer_state` corresponding to the passed
+	/// channel's counterparty acquired, when the call site has full ownership of the channel.
 	fn get_channel_update_for_unicast(&self, chan: &Channel<<SP::Target as SignerProvider>::Signer>) -> Result<msgs::ChannelUpdate, LightningError> {
 		log_trace!(self.logger, "Attempting to generate channel update for channel {}", log_bytes!(chan.channel_id()));
 		let short_channel_id = match chan.get_short_channel_id().or(chan.latest_inbound_scid_alias()) {
@@ -3553,7 +3554,7 @@ where
 	fn fail_htlc_backwards_internal(&self, source: &HTLCSource, payment_hash: &PaymentHash, onion_error: &HTLCFailReason, destination: HTLCDestination) {
 		#[cfg(debug_assertions)]
 		{
-			// Ensure that no peer state channel storage lock is not held when calling this
+			// Ensure that the peer state channel storage lock is not held when calling this
 			// function.
 			// This ensures that future code doesn't introduce a lock_order requirement for
 			// `forward_htlcs` to be locked after the `per_peer_state` peer locks, which calling
@@ -5452,7 +5453,8 @@ where
 	/// Note that that while `MessageSendEvent`s are strictly ordered per-peer, the peer order for
 	/// the chunks of `MessageSendEvent`s for different peers is random. I.e. if the array contains
 	/// `MessageSendEvent`s  for both `node_a` and `node_b`, the `MessageSendEvent`s for `node_a`
-	/// will randomly be placed first or last in the returned array.
+	/// will randomly be placed first or last in the returned array. Note that order will not be
+	/// randomized with the `no-std` feature enabled.
 	///
 	/// Note that even though `BroadcastChannelAnnouncement` and `BroadcastChannelUpdate`
 	/// `MessageSendEvent`s are intended to be broadcasted to all peers, they will be pleaced among