Refactor inbound members into a consistent order

And add download comments

zebrad/src/components/inbound.rs

@@ -53,17 +53,37 @@ pub type SetupData = (Outbound, Arc<Mutex<AddressBook>>);
 /// responding to block gossip by attempting to download and validate advertised
 /// blocks.
 pub struct Inbound {
-    // invariant: outbound, address_book are Some if network_setup is None
+    // invariant: address_book, outbound, downloads are Some if network_setup is None
     //
     // why not use an enum for the inbound state? because it would mean
     // match-wrapping the body of Service::call rather than just expect()ing
     // some Options.
+
+    // Setup
+    /// A oneshot channel used to receive the address_book and outbound services
+    /// after the network is set up.
     network_setup: Option<oneshot::Receiver<SetupData>>,
-    outbound: Option<Outbound>,
+
+    // Services
+    /// A list of peer addresses.
     address_book: Option<Arc<Mutex<zn::AddressBook>>>,
-    state: State,
+
-    verifier: Verifier,
+    /// A service that downloads and verifies gossipped blocks.
     downloads: Option<Pin<Box<Downloads<Timeout<Outbound>, Timeout<Verifier>, State>>>>,
+
+    /// A service that forwards requests to connected peers, and returns their
+    /// responses.
+    ///
+    /// Only used for readiness checks, and via `downloads`.
+    outbound: Option<Outbound>,
+
+    /// A service that manages cached blockchain state.
+    state: State,
+
+    /// A service that verifies downloaded blocks.
+    ///
+    /// Only used for readiness checks, and via `downloads`.
+    verifier: Verifier,
 }
 
 impl Inbound {
@@ -74,11 +94,11 @@ impl Inbound {
     ) -> Self {
         Self {
             network_setup: Some(network_setup),
-            outbound: None,
             address_book: None,
+            downloads: None,
+            outbound: None,
             state,
             verifier,
-            downloads: None,
         }
     }
 }

zebrad/src/components/inbound/downloads.rs

@@ -33,11 +33,24 @@ where
     ZS: Service<zs::Request, Response = zs::Response, Error = BoxError> + Send + Clone + 'static,
     ZS::Future: Send,
 {
+    // Services
+    /// A service that forwards requests to connected peers, and returns their
+    /// responses.
     network: ZN,
+
+    /// A service that verifies downloaded blocks.
     verifier: ZV,
+
+    /// A service that manages cached blockchain state.
     state: ZS,
+
+    // Internal downloads state
+    /// A list of pending block download and verify tasks.
     #[pin]
     pending: FuturesUnordered<JoinHandle<Result<block::Hash, (BoxError, block::Hash)>>>,
+
+    /// A list of channels that can be used to cancel pending block download and
+    /// verify tasks.
     cancel_handles: HashMap<block::Hash, oneshot::Sender<()>>,
 }
 

zebrad/src/components/sync/downloads.rs

@@ -43,10 +43,21 @@ where
     ZV: Service<Arc<Block>, Response = block::Hash, Error = BoxError> + Send + Clone + 'static,
     ZV::Future: Send,
 {
+    // Services
+    /// A service that forwards requests to connected peers, and returns their
+    /// responses.
     network: ZN,
+
+    /// A service that verifies downloaded blocks.
     verifier: ZV,
+
+    // Internal downloads state
+    /// A list of pending block download and verify tasks.
     #[pin]
     pending: FuturesUnordered<JoinHandle<Result<block::Hash, (BoxError, block::Hash)>>>,
+
+    /// A list of channels that can be used to cancel pending block download and
+    /// verify tasks.
     cancel_handles: HashMap<block::Hash, oneshot::Sender<()>>,
 }