cleanup(state): Update some outdated comments in the state & rpcs (#7434)

* Add a module cleanup TODO

* Fix an unrelated comment

* Update the comments about the bincode legacy format

zebra-rpc/src/methods.rs

@@ -124,7 +124,7 @@ pub trait Rpc {
     ///
     /// # Parameters
     ///
-    /// - `hash|height`: (string, required) The hash or height for the block to be returned.
+    /// - `hash | height`: (string, required) The hash or height for the block to be returned.
     /// - `verbosity`: (numeric, optional, default=1) 0 for hex encoded data, 1 for a json object,
     ///     and 2 for json object with transaction data.
     ///

zebra-rpc/src/methods/get_block_template_rpcs.rs

@@ -41,6 +41,8 @@ use crate::methods::{
             check_miner_address, check_synced_to_tip, fetch_mempool_transactions,
             fetch_state_tip_and_local_time, validate_block_proposal,
         },
+        // TODO: move the types/* modules directly under get_block_template_rpcs,
+        //       and combine any modules with the same names.
         types::{
             get_block_template::GetBlockTemplate,
             get_mining_info,

zebra-state/src/service/finalized_state/disk_format/chain.rs

@@ -31,6 +31,13 @@ impl FromDisk for ValueBalance<NonNegative> {
     }
 }
 
+// The following implementations for history trees use `serde` and
+// `bincode`. `serde` serializations depend on the inner structure of the type.
+// They should not be used in new code. (This is an issue for any derived serialization format.)
+//
+// We explicitly use `bincode::DefaultOptions`  to disallow trailing bytes; see
+// https://docs.rs/bincode/1.3.3/bincode/config/index.html#options-struct-vs-bincode-functions
+
 #[derive(serde::Serialize, serde::Deserialize)]
 struct HistoryTreeParts {
     network: Network,

zebra-state/src/service/finalized_state/disk_format/shielded.rs

@@ -96,10 +96,10 @@ impl FromDisk for orchard::tree::Root {
 }
 
 // The following implementations for the note commitment trees use `serde` and
-// `bincode` because currently the inner Merkle tree frontier (from
-// `incrementalmerkletree`) only supports `serde` for serialization. `bincode`
-// was chosen because it is small and fast. We explicitly use `DefaultOptions`
-// in particular to disallow trailing bytes; see
+// `bincode`. `serde` serializations depend on the inner structure of the type.
+// They should not be used in new code. (This is an issue for any derived serialization format.)
+//
+// We explicitly use `bincode::DefaultOptions`  to disallow trailing bytes; see
 // https://docs.rs/bincode/1.3.3/bincode/config/index.html#options-struct-vs-bincode-functions
 
 impl IntoDisk for sprout::tree::NoteCommitmentTree {