From ec0e13b764b12fe10390c4b84be7f8f31fede8d0 Mon Sep 17 00:00:00 2001
From: Paul Hauner <paul@paulhauner.com>
Date: Sun, 3 Mar 2019 15:32:44 +1100
Subject: [PATCH] Add comments to new functions

---
 .../block_processable/verify_slashable_attestation.rs |  2 ++
 eth2/types/src/attester_slashing/builder.rs           | 11 +++++++++++
 eth2/types/src/beacon_state.rs                        |  6 ++++++
 eth2/types/src/proposer_slashing/builder.rs           | 11 +++++++++++
 eth2/types/src/validator.rs                           |  4 +++-
 5 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/eth2/state_processing/src/block_processable/verify_slashable_attestation.rs b/eth2/state_processing/src/block_processable/verify_slashable_attestation.rs
index 35ad67df0..a406af24e 100644
--- a/eth2/state_processing/src/block_processable/verify_slashable_attestation.rs
+++ b/eth2/state_processing/src/block_processable/verify_slashable_attestation.rs
@@ -9,6 +9,8 @@ macro_rules! ensure {
     };
 }
 
+/// Returns `Ok(())` if some `AttesterSlashing` is valid to be included in some `BeaconState`,
+/// otherwise returns an `Err`.
 pub fn verify_slashable_attestation(
     state: &mut BeaconState,
     attester_slashing: &AttesterSlashing,
diff --git a/eth2/types/src/attester_slashing/builder.rs b/eth2/types/src/attester_slashing/builder.rs
index e53706192..ed203d6e1 100644
--- a/eth2/types/src/attester_slashing/builder.rs
+++ b/eth2/types/src/attester_slashing/builder.rs
@@ -1,9 +1,20 @@
 use crate::*;
 use ssz::TreeHash;
 
+/// Builds an `AttesterSlashing`.
 pub struct AttesterSlashingBuilder();
 
 impl AttesterSlashingBuilder {
+    /// Builds an `AttesterSlashing` that is a double vote.
+    ///
+    /// The `signer` function is used to sign the double-vote and accepts:
+    ///
+    /// - `validator_index: u64`
+    /// - `message: &[u8]`
+    /// - `epoch: Epoch`
+    /// - `domain: u64`
+    ///
+    /// Where domain is a domain "constant" (e.g., `spec.domain_attestation`).
     pub fn double_vote<F>(
         validator_indices: &[u64],
         signer: F,
diff --git a/eth2/types/src/beacon_state.rs b/eth2/types/src/beacon_state.rs
index 932233445..a9e2f2673 100644
--- a/eth2/types/src/beacon_state.rs
+++ b/eth2/types/src/beacon_state.rs
@@ -1140,6 +1140,9 @@ impl BeaconState {
         )
     }
 
+    /// Verify ``bitfield`` against the ``committee_size``.
+    ///
+    /// Spec v0.2.0
     pub fn verify_bitfield(&self, bitfield: &Bitfield, committee_size: usize) -> bool {
         if bitfield.num_bytes() != ((committee_size + 7) / 8) {
             return false;
@@ -1159,6 +1162,9 @@ impl BeaconState {
         true
     }
 
+    /// Verify validity of ``slashable_attestation`` fields.
+    ///
+    /// Spec v0.2.0
     pub fn verify_slashable_attestation(
         &self,
         slashable_attestation: &SlashableAttestation,
diff --git a/eth2/types/src/proposer_slashing/builder.rs b/eth2/types/src/proposer_slashing/builder.rs
index 363155a14..7923ff74d 100644
--- a/eth2/types/src/proposer_slashing/builder.rs
+++ b/eth2/types/src/proposer_slashing/builder.rs
@@ -1,9 +1,20 @@
 use crate::*;
 use ssz::TreeHash;
 
+/// Builds a `ProposerSlashing`.
 pub struct ProposerSlashingBuilder();
 
 impl ProposerSlashingBuilder {
+    /// Builds a `ProposerSlashing` that is a double vote.
+    ///
+    /// The `signer` function is used to sign the double-vote and accepts:
+    ///
+    /// - `validator_index: u64`
+    /// - `message: &[u8]`
+    /// - `epoch: Epoch`
+    /// - `domain: u64`
+    ///
+    /// Where domain is a domain "constant" (e.g., `spec.domain_attestation`).
     pub fn double_vote<F>(proposer_index: u64, signer: F, spec: &ChainSpec) -> ProposerSlashing
     where
         F: Fn(u64, &[u8], Epoch, u64) -> Signature,
diff --git a/eth2/types/src/validator.rs b/eth2/types/src/validator.rs
index bc8d467ec..587a48a1f 100644
--- a/eth2/types/src/validator.rs
+++ b/eth2/types/src/validator.rs
@@ -54,15 +54,17 @@ pub struct Validator {
 }
 
 impl Validator {
-    /// This predicate indicates if the validator represented by this record is considered "active" at `slot`.
+    /// Returns `true` if the validator is considered active at some epoch.
     pub fn is_active_at(&self, epoch: Epoch) -> bool {
         self.activation_epoch <= epoch && epoch < self.exit_epoch
     }
 
+    /// Returns `true` if the validator is considered exited at some epoch.
     pub fn is_exited_at(&self, epoch: Epoch) -> bool {
         self.exit_epoch <= epoch
     }
 
+    /// Returns `true` if the validator is considered penalized at some epoch.
     pub fn is_penalized_at(&self, epoch: Epoch) -> bool {
         self.penalized_epoch <= epoch
     }