diff --git a/src/chainparams.h b/src/chainparams.h
--- a/src/chainparams.h
+++ b/src/chainparams.h
@@ -25,6 +25,12 @@
     MapCheckpoints mapCheckpoints;
 };
 
+/**
+ * Holds various statistics on transactions within a chain. Used to estimate
+ * verification progress during chain sync.
+ *
+ * See also: CChainParams::TxData, GuessVerificationProgress.
+ */
 struct ChainTxData {
     int64_t nTime;
     int64_t nTxCount;
diff --git a/src/validation.cpp b/src/validation.cpp
--- a/src/validation.cpp
+++ b/src/validation.cpp
@@ -134,6 +134,11 @@
         const Config &config, CValidationState &state,
         std::shared_ptr<const CBlock> pblock = std::shared_ptr<const CBlock>());
 
+    /**
+     * If a block header hasn't already been seen, call CheckBlockHeader on it,
+     * ensure that it doesn't descend from an invalid block, and then add it to
+     * mapBlockIndex.
+     */
     bool AcceptBlockHeader(const Config &config, const CBlockHeader &block,
                            CValidationState &state, CBlockIndex **ppindex);
     bool AcceptBlock(const Config &config,
@@ -198,6 +203,12 @@
         EXCLUSIVE_LOCKS_REQUIRED(cs_main);
     /** Create a new block index entry for a given block hash */
     CBlockIndex *InsertBlockIndex(const uint256 &hash);
+    /**
+     * Make various assertions about the state of the block index.
+     *
+     * By default this only executes fully when using the Regtest chain; see:
+     * fCheckBlockIndex.
+     */
     void CheckBlockIndex(const Consensus::Params &consensusParams);
 
     void InvalidBlockFound(CBlockIndex *pindex, const CValidationState &state)
@@ -2864,6 +2875,10 @@
  * Make the best chain active, in multiple steps. The result is either failure
  * or an activated best chain. pblock is either nullptr or a pointer to a block
  * that is already loaded (to avoid loading it again from disk).
+ *
+ * ActivateBestChain is split into steps (see ActivateBestChainStep) so that
+ * we avoid holding cs_main for an extended period of time; the length of this
+ * call may be quite long during reindexing or a substantial reorg.
  */
 bool CChainState::ActivateBestChain(const Config &config,
                                     CValidationState &state,
@@ -3840,6 +3855,9 @@
                          __func__, hash.ToString(), FormatStateMessage(state));
         }
 
+        // If the previous block index isn't valid, determine if it descends
+        // from any block which has been found invalid (g_failed_blocks), then
+        // mark pindexPrev and any blocks between them as failed.
         if (!pindexPrev->IsValid(BlockValidity::SCRIPTS)) {
             for (const CBlockIndex *failedit : m_failed_blocks) {
                 if (pindexPrev->GetAncestor(failedit->nHeight) == failedit) {