Add doc comments for validator service.

validator_client/src/duties/grpc.rs

@@ -6,6 +6,12 @@ use ssz::ssz_encode;
 use types::PublicKey;
 
 impl BeaconNode for ValidatorServiceClient {
+    /// Request the shuffling from the Beacon Node (BN).
+    ///
+    /// As this function takes a `PublicKey`, it will first attempt to resolve the public key into
+    /// a validator index, then call the BN for production/attestation duties.
+    ///
+    /// Note: presently only block production information is returned.
     fn request_shuffling(
         &self,
         epoch: u64,

validator_client/src/duties/mod.rs

@@ -13,6 +13,11 @@ use std::sync::{Arc, RwLock};
 
 pub use self::service::DutiesManagerService;
 
+/// The information required for a validator to propose and attest during some epoch.
+///
+/// Generally obtained from a Beacon Node, this information contains the validators canonical index
+/// (thier sequence in the global validator induction process) and the "shuffling" for that index
+/// for some epoch.
 #[derive(Debug, PartialEq, Clone, Copy, Default)]
 pub struct EpochDuties {
     pub validator_index: u64,
@@ -21,6 +26,8 @@ pub struct EpochDuties {
 }
 
 impl EpochDuties {
+    /// Returns `true` if the supplied `slot` is a slot in which the validator should produce a
+    /// block.
     pub fn is_block_production_slot(&self, slot: u64) -> bool {
         match self.block_production_slot {
             Some(s) if s == slot => true,
@@ -29,13 +36,20 @@ impl EpochDuties {
     }
 }
 
+/// Maps an `epoch` to some `EpochDuties` for a single validator.
 pub type EpochDutiesMap = HashMap<u64, EpochDuties>;
 
 #[derive(Debug, PartialEq, Clone, Copy)]
 pub enum PollOutcome {
+    /// The `EpochDuties` were not updated during this poll.
     NoChange(u64),
+    /// The `EpochDuties` for the `epoch` were previously unknown, but obtained in the poll.
     NewDuties(u64, EpochDuties),
+    /// New `EpochDuties` were obtained, different to those which were previously known. This is
+    /// likely to be the result of chain re-organisation.
     DutiesChanged(u64, EpochDuties),
+    /// The Beacon Node was unable to return the duties as the validator is unknown, or the
+    /// shuffling for the epoch is unknown.
     UnknownValidatorOrEpoch(u64),
 }
 
@@ -49,8 +63,13 @@ pub enum Error {
     BeaconNodeError(BeaconNodeError),
 }
 
+/// A polling state machine which ensures the latest `EpochDuties` are obtained from the Beacon
+/// Node.
+///
+/// There is a single `DutiesManager` per validator instance.
 pub struct DutiesManager<T: SlotClock, U: BeaconNode> {
     pub duties_map: Arc<RwLock<EpochDutiesMap>>,
+    /// The validator's public key.
     pub pubkey: PublicKey,
     pub spec: Arc<ChainSpec>,
     pub slot_clock: Arc<RwLock<T>>,
@@ -58,6 +77,10 @@ pub struct DutiesManager<T: SlotClock, U: BeaconNode> {
 }
 
 impl<T: SlotClock, U: BeaconNode> DutiesManager<T, U> {
+    /// Poll the Beacon Node for `EpochDuties`.
+    ///
+    /// The present `epoch` will be learned from the supplied `SlotClock`. In production this will
+    /// be a wall-clock (e.g., system time, remote server time, etc.).
     pub fn poll(&self) -> Result<PollOutcome, Error> {
         let slot = self
             .slot_clock
@@ -109,6 +132,7 @@ mod tests {
     use slot_clock::TestingSlotClock;
 
     // TODO: implement more thorough testing.
+    // https://github.com/sigp/lighthouse/issues/160
     //
     // These tests should serve as a good example for future tests.
 

validator_client/src/duties/service.rs

@@ -11,6 +11,9 @@ pub struct DutiesManagerService<T: SlotClock, U: BeaconNode> {
 }
 
 impl<T: SlotClock, U: BeaconNode> DutiesManagerService<T, U> {
+    /// Run a loop which polls the manager each `poll_interval_millis` milliseconds.
+    ///
+    /// Logs the results of the polls.
     pub fn run(&mut self) {
         loop {
             match self.manager.poll() {

validator_client/src/duties/test_node.rs

@@ -5,6 +5,7 @@ use std::sync::RwLock;
 
 type ShufflingResult = Result<Option<EpochDuties>, BeaconNodeError>;
 
+/// A test-only struct used to simulate a Beacon Node.
 #[derive(Default)]
 pub struct TestBeaconNode {
     pub request_shuffling_input: RwLock<Option<(u64, PublicKey)>>,
@@ -12,12 +13,14 @@ pub struct TestBeaconNode {
 }
 
 impl TestBeaconNode {
+    /// Set the result to be returned when `request_shuffling` is called.
     pub fn set_next_shuffling_result(&self, result: ShufflingResult) {
         *self.request_shuffling_result.write().unwrap() = Some(result);
     }
 }
 
 impl BeaconNode for TestBeaconNode {
+    /// Returns the value specified by the `set_next_shuffling_result`.
     fn request_shuffling(&self, epoch: u64, public_key: &PublicKey) -> ShufflingResult {
         *self.request_shuffling_input.write().unwrap() = Some((epoch, public_key.clone()));
         match *self.request_shuffling_result.read().unwrap() {

validator_client/src/duties/traits.rs

@@ -6,7 +6,11 @@ pub enum BeaconNodeError {
     RemoteFailure(String),
 }
 
+/// Defines the methods required to obtain a validators shuffling from a Beacon Node.
 pub trait BeaconNode: Send + Sync {
+    /// Get the shuffling for the given epoch and public key.
+    ///
+    /// Returns Ok(None) if the public key is unknown, or the shuffling for that epoch is unknown.
     fn request_shuffling(
         &self,
         epoch: u64,