doc: Improve versionbits.h documentation #16587

  61 | @@ -50,12 +62,17 @@ class AbstractThresholdConditionChecker {
  62 |      virtual int Threshold(const Consensus::Params& params) const =0;
  63 |  
  64 |  public:
  65 | +    /** Returns the numerical statistics of an in-progess BIP9 softfork in the current period */

---

  27 | -    DEFINED,
  28 | -    STARTED,
  29 | -    LOCKED_IN,
  30 | -    ACTIVE,
  31 | -    FAILED,
  32 | +    DEFINED,   // First state that each softfork starts out as. The genesis block is by definition in this state for each deployment.

---

  70 |      ThresholdState GetStateFor(const CBlockIndex* pindexPrev, const Consensus::Params& params, ThresholdConditionCache& cache) const;
  71 | +    /** Returns the height since when the ThresholdState has started for pindex A based on parent pindexPrev B, all blocks of a period share the same */
  72 |      int GetStateSinceHeightFor(const CBlockIndex* pindexPrev, const Consensus::Params& params, ThresholdConditionCache& cache) const;
  73 |  };
  74 |  
  75 | +/** BIP 9 allows multiple softforks being deployed in parallel. We cache per-period state for every one of them

---

  16 | @@ -17,24 +17,36 @@ static const int32_t VERSIONBITS_TOP_MASK = 0xE0000000UL;
  17 |  /** Total bits available for versionbits */
  18 |  static const int32_t VERSIONBITS_NUM_BITS = 29;
  19 |  
  20 | +/** BIP 9 defines a finite-state-machine to deploy a softfork in multiple stages.
  21 | + *  It relies on the chain being a monotonic clock to start or timeout the

---

  61 | @@ -50,12 +62,17 @@ class AbstractThresholdConditionChecker {
  62 |      virtual int Threshold(const Consensus::Params& params) const =0;
  63 |  
  64 |  public:
  65 | +    /** Returns the numerical statistics of an in-progess BIP9 softfork in the current period */
  66 |      BIP9Stats GetStateStatisticsFor(const CBlockIndex* pindex, const Consensus::Params& params) const;
  67 | -    // Note that the functions below take a pindexPrev as input: they compute information for block B based on its parent.
  68 | +    /** Returns the state for pindex A based on parent pindexPrev B. Applies any state transition if conditions are present.
  69 | +     *  Caches state for first block of period. */

---

  30 | -    FAILED,
  31 | +    DEFINED,   // First state that each softfork starts out as. The genesis block is by definition in this state for each deployment.
  32 | +    STARTED,   // For blocks past the starttime.
  33 | +    LOCKED_IN, // For one retarget period after the first retarget period with STARTED blocks of which at least threshold have the associated bit set in nVersion.
  34 | +    ACTIVE,    // For all blocks after the LOCKED_IN retarget period (final state)
  35 | +    FAILED,    // For one retarget period past the timeout time, if LOCKED_IN was not reached (final state)

---