test: extra comments

Author: jaybuidl

contracts/test/foundry/KlerosCore_Appeals.t.sol

@@ -11,6 +11,9 @@ import "../../src/libraries/Constants.sol";
 /// @title KlerosCore_AppealsTest
 /// @dev Tests for KlerosCore appeal system, funding, and court/DK jumping
 contract KlerosCore_AppealsTest is KlerosCore_TestBase {
+ /// @dev Test funding appeal for only one side without completing the appeal.
+ /// Verifies appeal period calculation, funding mechanics (partial and full), overpayment reimbursement,
+ /// and error conditions (cannot appeal before appeal period, insufficient fees, only DK can call appeal).
  function test_appeal_fundOneSide() public {
  uint256 disputeID = 0;
  vm.deal(address(disputeKit), 1 ether);
@@ -103,6 +106,9 @@ contract KlerosCore_AppealsTest is KlerosCore_TestBase {
  disputeKit.fundAppeal(disputeID, 1);
  }
 
+ /// @dev Test appeal period timing constraints for losing vs winning sides.
+ /// Verifies losers can only fund appeals in the first half of the appeal period,
+ /// while winners can fund anytime until the end of the period.
  function test_appeal_timeoutCheck() public {
  uint256 disputeID = 0;
 
@@ -147,6 +153,9 @@ contract KlerosCore_AppealsTest is KlerosCore_TestBase {
  disputeKit.fundAppeal{value: 0.1 ether}(disputeID, 2);
  }
 
+ /// @dev Test complete appeal funding without court or dispute kit jumping.
+ /// Verifies that when both sides fully fund an appeal, a new round is created in the same court
+ /// with increased juror count (nbVotes * 2 + 1), and the dispute period transitions to evidence.
  function test_appeal_fullFundingNoJump() public {
  uint256 disputeID = 0;
 
@@ -209,9 +218,10 @@ contract KlerosCore_AppealsTest is KlerosCore_TestBase {
  core.passPeriod(disputeID);
  }
 
+ /// @dev Test simultaneous court jump and dispute kit jump to DISPUTE_KIT_CLASSIC.
+ /// Setup: Dispute starts in Court2 with DK2, where DK2._jumpDisputeKitID == DISPUTE_KIT_CLASSIC.
+ /// Verifies dispute jumps from Court2→GENERAL_COURT and DK2→DISPUTE_KIT_CLASSIC on appeal.
  function test_appeal_fullFundingCourtJumpAndDKJumpToClassic() public {
- // Setup: dk2 supported by court2 with dk2._jumpDisputeKitID == DISPUTE_KIT_CLASSIC
- // Ensure that court2 jumps to GENERAL_COURT and dk2 jumps to DISPUTE_KIT_CLASSIC
  uint256 disputeID = 0;
  DisputeKitClassic dkLogic = new DisputeKitClassic();
  // Create a new DK and court to check the jump
@@ -343,11 +353,10 @@ contract KlerosCore_AppealsTest is KlerosCore_TestBase {
  assertEq(account, staker1, "Wrong drawn account in the classic DK");
  }
 
+ /// @dev Test court jump and dispute kit jump to a non-classic dispute kit.
+ /// Setup: DK2 supported by GENERAL_COURT, DK3 supported by Court2, with DK3.jumpDisputeKitIDOnCourtJump == DK2.
+ /// Verifies dispute jumps from Court2→GENERAL_COURT and DK3→DK2 using jumpDisputeKitIDOnCourtJump setting.
  function test_appeal_fullFundingCourtJumpAndDKJumpToNonClassic() public {
- // Setup:
- // dk2 supported by GENERAL_COURT, which is a non-DISPUTE_KIT_CLASSIC
- // dk3 supported by court2, with dk3.nextRoundSettings[court2].jumpDisputeKitIDIncompatibilityFallback == dk2
- // Ensure that court2 jumps to GENERAL_COURT and dk3 jumps to dk2
  uint256 disputeID = 0;
  uint96 newCourtID = 2;
  uint256 dkID2 = 2;
@@ -493,9 +502,11 @@ contract KlerosCore_AppealsTest is KlerosCore_TestBase {
  assertEq(account, staker1, "Wrong drawn account in the classic DK");
  }
 
+ /// @dev Test dispute jumping between the same dispute kits multiple times across different rounds.
+ /// Setup: Court hierarchy GENERAL_COURT→Court2→Court3. DK2 supported by Court2, DK3 supported by Court3.
+ /// Verifies correct behavior when dispute oscillates: Court3/DK3 → Court2/DK2 → GENERAL_COURT/DK3,
+ /// including local dispute ID tracking and round state management across multiple DK switches.
  function test_appeal_recurringDK() public {
- // Test the behaviour when dispute jumps from DK3 to DK2 and then back to DK3 again.
-
  // Setup: create 2 more courts to facilitate appeal jump. Create 2 more DK.
  // Set General Court as parent to court2, and court2 as parent to court3. dk2 as jump DK for dk3, and dk3 as jump DK for dk2.
  // Ensure DK2 is supported by Court2 and DK3 is supported by court3.
@@ -829,6 +840,9 @@ contract KlerosCore_AppealsTest is KlerosCore_TestBase {
  disputeKit.withdrawFeesAndRewards(disputeID, payable(crowdfunder2), 2); // wrong DK, no reward
  }
 
+ /// @dev Test early termination of appeal period when no appeal is funded.
+ /// Verifies that the appeal period can be passed before timeout expires when waiting halfway
+ /// through the period with no appeal funded, allowing quick transition to execution.
  function test_appeal_quickPassPeriod() public {
  uint256 disputeID = 0;
 
@@ -863,6 +877,9 @@ contract KlerosCore_AppealsTest is KlerosCore_TestBase {
  core.passPeriod(disputeID);
  }
 
+ /// @dev Fuzz test for appeal funding with random ruling options and juror vote distributions.
+ /// Tests appeal mechanics with varying number of ruling options and different vote choices,
+ /// ensuring appeal funding works correctly regardless of the choice configuration.
  function testFuzz_appeal(uint256 numberOfOptions, uint256 choice1, uint256 choice2, uint256 choice3) public {
  uint256 disputeID = 0;
 
@@ -928,6 +945,9 @@ contract KlerosCore_AppealsTest is KlerosCore_TestBase {
  assertEq((disputeKit.getFundedChoices(disputeID)).length, 0, "No funded choices in a fresh round");
  }
 
+ /// @dev Fuzz test for appeal funding with random msg.value amounts.
+ /// Verifies overpayment is correctly reimbursed, partial funding is tracked, and the dispute kit
+ /// never holds more than the required appeal amount regardless of how much is sent.
  function testFuzz_fundAppeal_msgValue(uint256 appealValue) public {
  uint256 disputeID = 0;