minor doc chores (#4219)

* fix/warn: name is unused, only in debug would be used and but nobody does

* chore: Add better docs to `expansion` and why it exists

* chore: fmt

* Revert "chore: fmt"

This reverts commit 94d39bab5d1553d082a032ab6e31f579316dfa40.

polkadot/node/overseer/overseer-gen/proc-macro/Cargo.toml

@@ -23,5 +23,5 @@ assert_matches = "1.5.0"
 [features]
 default = []
 # write the expanded version to a `overlord-expansion.rs`
-# in the `cwd`
+# in the `OUT_DIR` as defined by `cargo`.
 expansion = []

polkadot/node/overseer/overseer-gen/proc-macro/src/impl_channels_out.rs

@@ -56,7 +56,8 @@ pub(crate) fn impl_channels_out_struct(info: &OverseerInfo) -> Result<proc_macro
 			)*
 		}
 
-		#[allow(unreachable_code)] // when no defined messages in enum
+		#[allow(unreachable_code)]
+		// when no defined messages in enum
 		impl ChannelsOut {
 			/// Send a message via a bounded channel.
 			pub async fn send_and_log_error(

polkadot/node/overseer/overseer-gen/proc-macro/src/lib.rs

@@ -98,6 +98,8 @@ pub(crate) fn impl_overseer_gen(
 	additive.extend(impl_message_wrapper_enum(&info)?);
 	additive.extend(impl_dispatch(&info));
 
+	// Write to a file for expansion, and then use it via `include!()`
+	// in order to obtain better compiler errors when modifying `overlord`.
 	if cfg!(feature = "expansion") {
 		use std::io::Write;