📚(WQ): typos and fixes

contracts/0.8.9/WithdrawalQueue.sol

@@ -92,7 +92,9 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit
     }
 
     /// @notice Resume withdrawal requests placement and finalization
-    ///  Contract is deployed in paused state and should be resumed explicitly
+    /// @dev The contract is deployed in paused state and should be resumed explicitly
+    /// @dev Reverts if sender has no `RESUME_ROLE`
+    /// @dev Reverts if contract is already resumed
     function resume() external {
         _checkRole(RESUME_ROLE, msg.sender);
         _resume();
@@ -101,7 +103,7 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit
     /// @notice Pause withdrawal requests placement and finalization. Claiming finalized requests will still be available
     /// @param _duration pause duration in seconds (use `PAUSE_INFINITELY` for unlimited)
     /// @dev Reverts if contract is already paused
-    /// @dev Reverts reason if sender has no `PAUSE_ROLE`
+    /// @dev Reverts if sender has no `PAUSE_ROLE`
     /// @dev Reverts if zero duration is passed
     function pauseFor(uint256 _duration) external onlyRole(PAUSE_ROLE) {
         _pauseFor(_duration);
@@ -192,7 +194,7 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit
         return requestWithdrawalsWstETH(_amounts, _owner);
     }
 
-    /// @notice Returns all withdrawal requests that belongs to the `_owner` address
+    /// @notice Returns all withdrawal requests that belong to the `_owner` address
     ///
     /// WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     /// to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
@@ -202,7 +204,7 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit
         return _getRequestsByOwner()[_owner].values();
     }
 
-    /// @notice Returns status for requests with provided ids
+    /// @notice Returns status of requests with provided ids
     /// @param _requestIds array of withdrawal request ids
     function getWithdrawalStatus(uint256[] calldata _requestIds)
         external
@@ -215,7 +217,7 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit
         }
     }
 
-    /// @notice Returns amount of ether available for claim for each provided request id
+    /// @notice Returns the amount of ether available for claiming for each provided request id
     /// @param _requestIds array of request ids
     /// @param _hints checkpoint hints. can be found with `findCheckpointHints(_requestIds, 1, getLastCheckpointIndex())`
     /// @return claimableEthValues amount of claimable ether for each request, amount is equal to 0 if request
@@ -311,10 +313,10 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit
     }
 
     /// @notice Update bunker mode state and last report timestamp on oracle report
-    /// @dev should be called by oracle
+    /// @dev Reverts if sender has no `RESUME_ROLE`
     ///
-    /// @param _isBunkerModeNow is bunker mode reported by oracle
-    /// @param _bunkerStartTimestamp timestamp of start of the bunker mode
+    /// @param _isBunkerModeNow is bunker mode reported by the oracle
+    /// @param _bunkerStartTimestamp timestamp of the bunker mode activation
     /// @param _currentReportTimestamp timestamp of the current report ref slot
     function onOracleReport(bool _isBunkerModeNow, uint256 _bunkerStartTimestamp, uint256 _currentReportTimestamp)
         external
@@ -342,12 +344,12 @@ abstract contract WithdrawalQueue is AccessControlEnumerable, PausableUntil, Wit
         }
     }
 
-    /// @notice Check if bunker mode is active
+    /// @notice Returns `true` if bunker mode is active
     function isBunkerModeActive() public view returns (bool) {
         return bunkerModeSinceTimestamp() < BUNKER_MODE_DISABLED_TIMESTAMP;
     }
 
-    /// @notice Get bunker mode activation timestamp
+    /// @notice Returns bunker mode activation timestamp
     /// @dev returns `BUNKER_MODE_DISABLED_TIMESTAMP` if bunker mode is disable (i.e., protocol in turbo mode)
     function bunkerModeSinceTimestamp() public view returns (uint256) {
         return BUNKER_MODE_SINCE_TIMESTAMP_POSITION.getStorageUint256();

contracts/0.8.9/WithdrawalQueueBase.sol

@@ -111,30 +111,30 @@ abstract contract WithdrawalQueueBase {
     error InvalidHint(uint256 _hint);
     error CantSendValueRecipientMayHaveReverted();
 
-    /// @notice id of the last request
-    ///  NB! requests are indexed from 1, so it returns 0 if there is no requests in the queue
+    /// @notice Returns the id of the last request in the queue
+    ///  NB! requests are indexed from 1, so it returns 0 if there are no requests in the queue
     function getLastRequestId() public view returns (uint256) {
         return LAST_REQUEST_ID_POSITION.getStorageUint256();
     }
 
-    /// @notice id of the last finalized request
-    ///  NB! requests are indexed from 1, so it returns 0 if there is no finalized requests in the queue
+    /// @notice Returns the id of the last finalized request in the queue
+    ///  NB! requests are indexed from 1, so it returns 0 if there are no finalized requests in the queue
     function getLastFinalizedRequestId() public view returns (uint256) {
         return LAST_FINALIZED_REQUEST_ID_POSITION.getStorageUint256();
     }
 
-    /// @notice amount of ETH on this contract balance that is locked for withdrawal and available to claim
+    /// @notice Returns the amount of ether on the balance locked for withdrawal and available to claim
     function getLockedEtherAmount() public view returns (uint256) {
         return LOCKED_ETHER_AMOUNT_POSITION.getStorageUint256();
     }
 
-    /// @notice length of the checkpoint array. Last possible value for the hint.
-    ///  NB! checkpoints are indexed from 1, so it returns 0 if there is no checkpoints
+    /// @notice Returns the length of the checkpoint array. Last possible value for the hint.
+    ///  NB! checkpoints are indexed from 1, so it returns 0 if there are no checkpoints yet
     function getLastCheckpointIndex() public view returns (uint256) {
         return LAST_CHECKPOINT_INDEX_POSITION.getStorageUint256();
     }
 
-    /// @notice return the number of unfinalized requests in the queue
+    /// @notice Returns the number of unfinalized requests in the queue
     function unfinalizedRequestNumber() external view returns (uint256) {
         return getLastRequestId() - getLastFinalizedRequestId();
     }
@@ -183,15 +183,15 @@ abstract contract WithdrawalQueueBase {
         uint256 remainingEthBudget;
         /// @notice flag that is set to `true` if returned state is final and `false` if more calls are required
         bool finished;
-        /// @notice static array to store last request id in each batch
+        /// @notice the resulting array of batches, represented by the id of the last request in the batch
         uint256[MAX_BATCHES_LENGTH] batches;
         /// @notice length of the filled part of `batches` array
         uint256 batchesLength;
     }
 
     /// @notice Offchain view for the oracle daemon that calculates how many requests can be finalized within
-    /// the given budget, time period and share rate limits. Returned requests are split into batches.
-    /// Each batch consist of the requests that all have the share rate below the `_maxShareRate` or above it.
+    /// the given budget, time period, and share rate limits. Returned requests are split into batches.
+    /// All requests belonging to one batch must have their share rate above or below (or equal) to the `_maxShareRate`.
     /// Below you can see an example how 14 requests with different share rates will be split into 5 batches by
     /// this method
     ///
@@ -285,11 +285,11 @@ abstract contract WithdrawalQueueBase {
         return _state;
     }
 
-    /// @notice Checks finalization batches, calculates required ether and the amount of shares to burn
+    /// @notice Checks finalization batches, calculates required amount of ether to lock and the number of shares to burn
     /// @param _batches finalization batches calculated offchain using `calculateFinalizationBatches()`
-    /// @param _maxShareRate max share rate that will be used for request finalization (1e27 precision)
-    /// @return ethToLock amount of ether that should be sent with `finalize()` method
-    /// @return sharesToBurn amount of shares that belongs to requests that will be finalized
+    /// @param _maxShareRate the max share rate (ETH per share) for the request finalization (1e27 precision)
+    /// @return ethToLock the amount of ether to be sent with `finalize()` method
+    /// @return sharesToBurn the number of shares to be burnt to match this finalization call
     function prefinalize(uint256[] calldata _batches, uint256 _maxShareRate)
         external
         view

contracts/0.8.9/WithdrawalQueueERC721.sol

@@ -124,7 +124,7 @@ contract WithdrawalQueueERC721 is IERC721Metadata, IERC4906, WithdrawalQueue {
     }
 
     /// @notice Sets the Base URI for computing {tokenURI}. It does not expect the ending slash in provided string.
-    /// @dev If NFTDescriptor address isn't set the `baseURI` would be used for generating erc721 tokenURI. In case
+    /// @dev If NFTDescriptor address isn't set the `baseURI` would be used for generating the ERC-721 token URI. In case
     ///  NFTDescriptor address is set it would be used as a first-priority method.
     function setBaseURI(string calldata _baseURI) external onlyRole(MANAGE_TOKEN_URI_ROLE) {
         _getBaseURI().value = _baseURI;
@@ -144,8 +144,10 @@ contract WithdrawalQueueERC721 is IERC721Metadata, IERC4906, WithdrawalQueue {
         emit NftDescriptorAddressSet(_nftDescriptorAddress);
     }
 
-    /// @notice Finalize requests from last finalized one up to `_lastRequestIdToBeFinalized`
+    /// @notice Finalize requests from the last finalized one up to `_lastRequestIdToBeFinalized`
     /// @dev ether to finalize all the requests should be calculated using `prefinalize()` and sent along
+    /// @param _lastRequestIdToBeFinalized the last request id to finalize
+    /// @param _maxShareRate the max share rate (ETH per share) for the request finalization (1e27 precision)
     function finalize(uint256 _lastRequestIdToBeFinalized, uint256 _maxShareRate) external payable {
         _checkResumed();
         _checkRole(FINALIZE_ROLE, msg.sender);