From 5ca53190b5408675f39250a83f285f80c537c67c Mon Sep 17 00:00:00 2001
From: Paul Hauner <paul@paulhauner.com>
Date: Fri, 1 Feb 2019 18:18:39 +1100
Subject: [PATCH] Add comments to beacon chain fork choice

---
 beacon_node/beacon_chain/src/lib.rs       |  1 +
 beacon_node/beacon_chain/src/lmd_ghost.rs | 10 +++++-----
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/beacon_node/beacon_chain/src/lib.rs b/beacon_node/beacon_chain/src/lib.rs
index e0ce5d8a7d..68c0c3c9c7 100644
--- a/beacon_node/beacon_chain/src/lib.rs
+++ b/beacon_node/beacon_chain/src/lib.rs
@@ -56,6 +56,7 @@ where
     T: ClientDB,
     U: SlotClock,
 {
+    /// Instantiate a new Beacon Chain, from genesis.
     pub fn genesis(
         state_store: Arc<BeaconStateStore<T>>,
         block_store: Arc<BeaconBlockStore<T>>,
diff --git a/beacon_node/beacon_chain/src/lmd_ghost.rs b/beacon_node/beacon_chain/src/lmd_ghost.rs
index 6116834bb4..176d4a6860 100644
--- a/beacon_node/beacon_chain/src/lmd_ghost.rs
+++ b/beacon_node/beacon_chain/src/lmd_ghost.rs
@@ -12,11 +12,6 @@ use types::{
     Hash256,
 };
 
-#[derive(Debug, PartialEq)]
-pub enum Outcome {
-    Something,
-}
-
 #[derive(Debug, PartialEq)]
 pub enum Error {
     DBError(String),
@@ -32,6 +27,7 @@ where
     U: SlotClock,
     Error: From<<U as SlotClock>::Error>,
 {
+    /// Run the fork-choice rule on the current chain, updating the canonical head, if required.
     pub fn fork_choice(&self) -> Result<(), Error> {
         let present_head = &self.finalized_head().beacon_block_root;
 
@@ -56,6 +52,7 @@ where
         Ok(())
     }
 
+    /// A very inefficient implementation of LMD ghost.
     pub fn slow_lmd_ghost(&self, start_hash: &Hash256) -> Result<Hash256, Error> {
         let start = self
             .block_store
@@ -114,6 +111,9 @@ where
     }
 }
 
+/// Get the total number of votes for some given block root.
+///
+/// The vote count is incrememented each time an attestation target votes for a block root.
 fn get_vote_count<T: ClientDB>(
     block_store: &Arc<BeaconBlockStore<T>>,
     attestation_targets: &[Hash256],