Edit documentation of LoE and GDD

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Genesis/Governor.hs

@@ -18,14 +18,16 @@
 -- The GDD governor is the component responsible for identifying and
 -- disconnecting peers offering sparser chains than the best. This has the
 -- effect of unblocking the Limit on Eagerness, since removing disagreeing
--- peers allows the current selection to advance.
+-- peers allows the current selection to advance. See
+-- 'Ouroboros.Consensus.Storage.ChainDB.API.LoE' for more details.
 --
 -- The GDD governor, invoked with 'runGdd', is supposed to run in a background
 -- thread. It evaluates candidate chains whenever they change, or whenever a
 -- peer claims to have no more headers, or whenever a peer starts sending
 -- headers beyond the forecast horizon.
 --
--- Whenever GDD disconnects peers, the chain selection is updated.
+-- Whenever GDD disconnects peers, and as a result the youngest header present
+-- in all candidate fragments changes, the chain selection is updated.
 --
 module Ouroboros.Consensus.Genesis.Governor (
     DensityBounds (..)

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Storage/ChainDB/API.hs

@@ -866,29 +866,28 @@ instance (Typeable blk, StandardHash blk) => Exception (ChainDbError blk) where
     InvalidIteratorRange {} ->
       "An invalid range of blocks was requested"
 
--- | The Limit on Eagerness is a mechanism for keeping ChainSel from advancing
--- the current selection in the case of competing chains.
+-- | The Limit on Eagerness (LoE) is a mechanism for keeping ChainSel from
+-- advancing the current selection in the case of competing chains.
 --
--- The Limit on Eagerness prevents the selection of the node from extending
--- more than k blocks after the youngest block that is present on all candidate
--- fragments.
+-- The LoE tip is the youngest header that is present on all candidate
+-- fragments. Thus, after the LoE tip, peers either disagree on how the chain
+-- follows, or they do not offer more headers.
+--
+-- The LoE restrains the current selection of the node to be on the same chain
+-- as the LoE tip, and to not extend more than k blocks from it.
 --
 -- It requires a resolution mechanism to prevent indefinite stalling, which
 -- is implemented by the Genesis Density Disconnection governor, a component
--- that implements an 'UpdateLoEFrag' that disconnects from peers with forks
--- it considers inferior.
+-- that disconnects from peers with forks it considers inferior.
+-- See "Ouroboros.Consensus.Genesis.Governor" for details.
 --
--- This type indicates whether the feature is enabled, and contains a value
--- if it is.
+-- This type indicates whether LoE is enabled, and contains a value if it is.
 data LoE a =
   -- | The LoE is disabled, so ChainSel will not keep the selection from
   -- advancing.
   LoEDisabled
   |
-  -- | The LoE is enabled, using the security parameter @k@ as the limit.
-  -- When the selection's tip is @k@ blocks after the earliest intersection of
-  -- of all candidate fragments, ChainSel will not add new blocks to the
-  -- selection.
+  -- | The LoE is enabled.
   LoEEnabled a
   deriving (Eq, Show, Generic, NoThunks, Functor, Foldable, Traversable)