From 49737fbc82228f4b227d51b59e22948997f94a72 Mon Sep 17 00:00:00 2001
From: Paul Hauner <paul@paulhauner.com>
Date: Tue, 2 Oct 2018 17:58:33 +1000
Subject: [PATCH] Add doc comments to attestation validation

---
 .../validation/src/attestation_validation.rs      | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/beacon_chain/validation/src/attestation_validation.rs b/beacon_chain/validation/src/attestation_validation.rs
index e04450a15..46cac7885 100644
--- a/beacon_chain/validation/src/attestation_validation.rs
+++ b/beacon_chain/validation/src/attestation_validation.rs
@@ -47,21 +47,36 @@ pub enum AttestationValidationError {
     DBError(String),
 }
 
+/// The context against which some attestation should be validated.
 pub struct AttestationValidationContext<T>
     where T: ClientDB + Sized
 {
+    /// The slot as determined by the system time.
     pub block_slot: u64,
+    /// The cycle_length as determined by the chain configuration.
     pub cycle_length: u8,
+    /// The last justified slot as per the client's view of the canonical chain.
     pub last_justified_slot: u64,
+    /// A vec of the hashes of the blocks preceeding the present slot.
     pub parent_hashes: Arc<Vec<Hash256>>,
+    /// The store containing block information.
     pub block_store: Arc<BlockStore<T>>,
+    /// The store containing validator information.
     pub validator_store: Arc<ValidatorStore<T>>,
+    /// A map of (slot, shard_id) to the attestation set of validation indices.
     pub attester_map: Arc<AttesterMap>,
 }
 
 impl<T> AttestationValidationContext<T>
     where T: ClientDB
 {
+    /// Validate a (fully deserialized) AttestationRecord against this context.
+    ///
+    /// The function will return a HashSet of validator indices (canonical validator indices not
+    /// attestation indices) if the validation passed successfully, or an error otherwise.
+    ///
+    /// The attestation's aggregate signature will be verified, therefore the function must able to
+    /// access all required validation public keys via the `validator_store`.
     pub fn validate_attestation(&self, a: &AttestationRecord)
         -> Result<HashSet<usize>, AttestationValidationError>
     {