maint(ct): misc comment cleanup (#9902)

Some miscellaneous comment cleanup for dispute contracts.

packages/contracts-bedrock/semver-lock.json

@@ -105,11 +105,11 @@
   },
   "src/dispute/AnchorStateRegistry.sol": {
     "initCodeHash": "0x2f8c56069e43e306b0e40fba43109188b29328e83569560021a68aa5d9f2486b",
-    "sourceCodeHash": "0xb6e67d68b801b7a110207b0c33802ea94cf26f9a7f3ebba78123d930a2eb0b2a"
+    "sourceCodeHash": "0xba941ad1f941f5a4a066182d50634fa9b190085ed82779decef71c019ba963c5"
   },
   "src/dispute/DisputeGameFactory.sol": {
     "initCodeHash": "0x80d749a56c1776930fe0deb5c3c646217716e5875ace99c4d036af0452236476",
-    "sourceCodeHash": "0x1e5a6deded88804971fc1847c9eac65921771bff353437c0b29ed2f55513b984"
+    "sourceCodeHash": "0xf897c1a845a16cb8b217135a1c7819cdb20b315567066282f5860251e48d3611"
   },
   "src/dispute/FaultDisputeGame.sol": {
     "initCodeHash": "0x9dcd4df1dd3e7a09dab46bfe1ebd9376f533cc533f9edce2f01aa754301e25aa",
@@ -117,7 +117,7 @@
   },
   "src/dispute/weth/DelayedWETH.sol": {
     "initCodeHash": "0xf179e4249be6eda22b24ae2b32717f154f35edeb9dee0332aefa6fad3ace4dbe",
-    "sourceCodeHash": "0x5f1f07aba545be48c76285fde404308b0c51f75777720d06d7fe5087e338c39a"
+    "sourceCodeHash": "0x1a37c92242f612588f60256554107ee675678687b49b1f41087411dfcd6aabd3"
   },
   "src/legacy/DeployerWhitelist.sol": {
     "initCodeHash": "0x8de80fb23b26dd9d849f6328e56ea7c173cd9e9ce1f05c9beea559d1720deb3d",

packages/contracts-bedrock/src/dispute/AnchorStateRegistry.sol

@@ -11,6 +11,11 @@ import { IDisputeGameFactory } from "src/dispute/interfaces/IDisputeGameFactory.
 
 import "src/libraries/DisputeTypes.sol";
 
+/// @title AnchorStateRegistry
+/// @notice The AnchorStateRegistry is a contract that stores the latest "anchor" state for each available
+///         FaultDisputeGame type. The anchor state is the latest state that has been proposed on L1 and was not
+///         challenged within the challenge period. By using stored anchor states, new FaultDisputeGame instances can
+///         be initialized with a more recent starting state which reduces the amount of required offchain computation.
 contract AnchorStateRegistry is Initializable, IAnchorStateRegistry, ISemver {
     /// @notice Describes an initial anchor state for a game type.
     struct StartingAnchorRoot {

packages/contracts-bedrock/src/dispute/DisputeGameFactory.sol

@@ -14,11 +14,10 @@ import "src/libraries/DisputeTypes.sol";
 import "src/libraries/DisputeErrors.sol";
 
 /// @title DisputeGameFactory
-/// @notice A factory contract for creating `IDisputeGame` contracts. All created dispute games
-///         are stored in both a mapping and an append only array. The timestamp of the creation
-///         time of the dispute game is packed tightly into the storage slot with the address of
-///         the dispute game. This is to make offchain discoverability of playable dispute games
-///         easier.
+/// @notice A factory contract for creating `IDisputeGame` contracts. All created dispute games are stored in both a
+///         mapping and an append only array. The timestamp of the creation time of the dispute game is packed tightly
+///         into the storage slot with the address of the dispute game to make offchain discoverability of playable
+///         dispute games easier.
 contract DisputeGameFactory is OwnableUpgradeable, IDisputeGameFactory, ISemver {
     /// @dev Allows for the creation of clone proxies with immutable arguments.
     using ClonesWithImmutableArgs for address;
@@ -33,17 +32,15 @@ contract DisputeGameFactory is OwnableUpgradeable, IDisputeGameFactory, ISemver
     /// @inheritdoc IDisputeGameFactory
     mapping(GameType => uint256) public initBonds;
 
-    /// @notice Mapping of a hash of `gameType || rootClaim || extraData` to
-    ///         the deployed `IDisputeGame` clone.
-    /// @dev Note: `||` denotes concatenation.
+    /// @notice Mapping of a hash of `gameType || rootClaim || extraData` to the deployed `IDisputeGame` clone (where
+    //          `||` denotes concatenation).
     mapping(Hash => GameId) internal _disputeGames;
 
-    /// @notice an append-only array of disputeGames that have been created.
-    /// @dev this accessor is used by offchain game solvers to efficiently
-    ///      track dispute games
+    /// @notice An append-only array of disputeGames that have been created. Used by offchain game solvers to
+    ///         efficiently track dispute games.
     GameId[] internal _disputeGameList;
 
-    /// @notice constructs a new DisputeGameFactory contract.
+    /// @notice Constructs a new DisputeGameFactory contract.
     constructor() OwnableUpgradeable() {
         initialize(address(0));
     }
@@ -115,6 +112,7 @@ contract DisputeGameFactory is OwnableUpgradeable, IDisputeGameFactory, ISemver
         // If a dispute game with the same UUID already exists, revert.
         if (GameId.unwrap(_disputeGames[uuid]) != bytes32(0)) revert GameAlreadyExists(uuid);
 
+        // Pack the game ID.
         GameId id = LibGameId.pack(_gameType, Timestamp.wrap(uint64(block.timestamp)), proxy_);
 
         // Store the dispute game id in the mapping & emit the `DisputeGameCreated` event.

packages/contracts-bedrock/src/dispute/PermissionedDisputeGame.sol

@@ -11,12 +11,14 @@ import "src/libraries/DisputeErrors.sol";
 /// @notice PermissionedDisputeGame is a contract that inherits from `FaultDisputeGame`, and contains two roles:
 ///         - The `challenger` role, which is allowed to challenge a dispute.
 ///         - The `proposer` role, which is allowed to create proposals and participate in their game.
-///         This contract exists as a fallback mechanism in case of the failure of the fault proof system in the stage
-///         one release. It will not be the default implementation used, and eventually will be deprecated in favor of
-///         a fully permissionless system.
+///         This contract exists as a way for networks to support the fault proof iteration of the OptimismPortal
+///         contract without needing to support a fully permissionless system. Permissionless systems can introduce
+///         costs that certain networks may not wish to support. This contract can also be used as a fallback mechanism
+///         in case of a failure in the permissionless fault proof system in the stage one release.
 contract PermissionedDisputeGame is FaultDisputeGame {
     /// @notice The proposer role is allowed to create proposals and participate in the dispute game.
     address internal immutable PROPOSER;
+
     /// @notice The challenger role is allowed to participate in the dispute game.
     address internal immutable CHALLENGER;
 

packages/contracts-bedrock/src/dispute/interfaces/IAnchorStateRegistry.sol

@@ -17,8 +17,8 @@ interface IAnchorStateRegistry {
     /// @return DisputeGameFactory address.
     function disputeGameFactory() external view returns (IDisputeGameFactory);
 
-    /// @notice Callable by FaultDisputeGame contracts to update the anchor state. Pulls the anchor
-    ///         state directly from the FaultDisputeGame contract and stores it in the registry if
-    ///         the new anchor state is valid and the state is newer than the current anchor state.
+    /// @notice Callable by FaultDisputeGame contracts to update the anchor state. Pulls the anchor state directly from
+    ///         the FaultDisputeGame contract and stores it in the registry if the new anchor state is valid and the
+    ///         state is newer than the current anchor state.
     function tryUpdateAnchorState() external;
 }

packages/contracts-bedrock/src/dispute/weth/DelayedWETH.sol

@@ -11,16 +11,14 @@ import { WETH98 } from "src/dispute/weth/WETH98.sol";
 import { SuperchainConfig } from "src/L1/SuperchainConfig.sol";
 
 /// @title DelayedWETH
-/// @notice DelayedWETH is an extension to WETH9 that allows for delayed withdrawals. Accounts must
-///         trigger an unlock function before they can withdraw WETH. Accounts must trigger unlock
-///         by specifying a sub-account and an amount of WETH to unlock. Accounts can trigger the
-///         unlock function at any time, but must wait a delay period before they can withdraw
-///         after the unlock function is triggered. DelayedWETH is designed to be used by the
-///         DisputeGame contracts where unlock will only be triggered after a dispute is resolved.
-///         DelayedWETH is meant to sit behind a proxy contract and has an owner address that can
-///         pull WETH from any account and can recover ETH from the contract itself. Variable and
-///         function naming vaguely follows the vibe of WETH9. Not the prettiest contract in the
-///         world, but it gets the job done.
+/// @notice DelayedWETH is an extension to WETH9 that allows for delayed withdrawals. Accounts must trigger an unlock
+///         function before they can withdraw WETH. Accounts must trigger unlock by specifying a sub-account and an
+///         amount of WETH to unlock. Accounts can trigger the unlock function at any time, but must wait a delay
+///         period before they can withdraw after the unlock function is triggered. DelayedWETH is designed to be used
+///         by the DisputeGame contracts where unlock will only be triggered after a dispute is resolved. DelayedWETH
+///         is meant to sit behind a proxy contract and has an owner address that can pull WETH from any account and
+///         can recover ETH from the contract itself. Variable and function naming vaguely follows the vibe of WETH9.
+///         Not the prettiest contract in the world, but it gets the job done.
 contract DelayedWETH is OwnableUpgradeable, WETH98, IDelayedWETH, ISemver {
     /// @notice Semantic version.
     /// @custom:semver 0.2.0
@@ -57,12 +55,11 @@ contract DelayedWETH is OwnableUpgradeable, WETH98, IDelayedWETH, ISemver {
 
     /// @inheritdoc IDelayedWETH
     function unlock(address _guy, uint256 _wad) external {
-        // Note that the unlock function can be called by any address, but the actual unlocking
-        // capability still only gives the msg.sender the ability to withdraw from the account.
-        // As long as the unlock and withdraw functions are called with the proper recipient
-        // addresses, this will be safe. Could be made safer by having external accounts execute
-        // withdrawals themselves but that would have added extra complexity and made DelayedWETH
-        // a leaky abstraction, so we chose this instead.
+        // Note that the unlock function can be called by any address, but the actual unlocking capability still only
+        // gives the msg.sender the ability to withdraw from the account. As long as the unlock and withdraw functions
+        // are called with the proper recipient addresses, this will be safe. Could be made safer by having external
+        // accounts execute withdrawals themselves but that would have added extra complexity and made DelayedWETH a
+        // leaky abstraction, so we chose this instead.
         WithdrawalRequest storage wd = withdrawals[msg.sender][_guy];
         wd.timestamp = block.timestamp;
         wd.amount += _wad;