Document all tests that did not have documentation

Author: Niols

ouroboros-consensus-diffusion/test/consensus-test/Test/Consensus/Genesis/Tests/LoE.hs

@@ -42,7 +42,14 @@ tests =
     ]
 
 -- | Tests that the selection advances in presence of the LoE when a peer is
--- killed by something that is not LoE-aware, eg. the timeouts.
+-- killed by something that is not LoE-aware, eg. the timeouts. This test
+-- features an honest peer behaving normally and an adversarial peer behaving
+-- such that it will get killed by timeouts. We check that, after the adversary
+-- gets disconnected, the LoE gets updated to stop taking it into account. There
+-- are two variants of the test: one with timeouts enabled, and one without. In
+-- the case where timeouts are disabled, we check that we do in fact remain
+-- stuck at the intersection between trunk and other chain.
+--
 -- NOTE: Same as 'LoP.prop_delayAttack' with timeouts instead of LoP.
 prop_adversaryHitsTimeouts :: Bool -> Property
 prop_adversaryHitsTimeouts timeoutsEnabled =

ouroboros-consensus-diffusion/test/consensus-test/Test/Consensus/Genesis/Tests/LoP.hs

@@ -59,6 +59,13 @@ tests =
         testProperty "delaying attack fails with LoP" (prop_delayAttack True)
     ]
 
+-- | Simple test in which we connect to only one peer, who advertises the tip of
+-- the block tree trunk and then does nothing. If the given boolean,
+-- @mustTimeout@, if @True@, then we wait just long enough for the LoP bucket to
+-- empty; we expect to observe an 'EmptyBucket' exception in the ChainSync
+-- client. If @mustTimeout@ is @False@, then we wait not quite as long, so the
+-- LoP bucket should not be empty at the end of the test and we should observe
+-- no exception in the ChainSync client.
 prop_wait :: Bool -> Property
 prop_wait mustTimeout =
   forAllGenesisTest
@@ -90,6 +97,13 @@ prop_wait mustTimeout =
             , psMinEndTime = Time $ timeout + offset
             }
 
+-- | Simple test in which we connect to only one peer, who advertises the tip of
+-- the block tree trunk, serves all of its headers, and then does nothing.
+-- Because the peer does not send its blocks, then the ChainSync client will end
+-- up stuck, waiting behind the forecast horizon. We expect that the LoP will
+-- then be disabled and that, therefore, one could wait forever in this state.
+-- We disable the timeouts and check that, indeed, the ChainSync client observes
+-- no exception.
 prop_waitBehindForecastHorizon :: Property
 prop_waitBehindForecastHorizon =
   forAllGenesisTest

ouroboros-consensus-diffusion/test/consensus-test/Test/Consensus/Genesis/Tests/LongRangeAttack.hs

@@ -34,6 +34,12 @@ tests =
     testProperty "one adversary" prop_longRangeAttack
   ]
 
+-- | This test case features a long-range attack with one adversary. The honest
+-- peer serves the block tree trunk, while the adversary serves its own chain,
+-- forking off the trunk by at least @k@ blocks, but less good than the trunk.
+-- The adversary serves the chain more rapidly than the honest peer. We check at
+-- the end that the selection is honest. This property does not hold with Praos,
+-- but should hold with Genesis.
 prop_longRangeAttack :: Property
 prop_longRangeAttack =
   -- NOTE: `shrinkPeerSchedules` only makes sense for tests that expect the