Add comments to new functions

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,

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,

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,

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,

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
     }