JBDeadline + JBDirectory doc updates

src/JBController.sol

@@ -40,8 +40,7 @@ import {JBSplitGroup} from "./structs/JBSplitGroup.sol";
 import {JBSplitHookContext} from "./structs/JBSplitHookContext.sol";
 import {JBTerminalConfig} from "./structs/JBTerminalConfig.sol";
 
-/// @notice `JBController` coordinates rulesets and project tokens, and is the entry point for most operations related
-/// to projects and their tokens.
+/// @notice `JBController` coordinates rulesets and project tokens, and is the entry point for most operations related to rulesets and project tokens.
 contract JBController is JBPermissioned, ERC2771Context, ERC165, IJBController, IJBMigratable {
     // A library that parses packed ruleset metadata into a friendlier format.
     using JBRulesetMetadataResolver for JBRuleset;
@@ -232,9 +231,9 @@ contract JBController is JBPermissioned, ERC2771Context, ERC165, IJBController,
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
-    /// @notice Indicates if this contract adheres to the specified interface.
+    /// @notice Indicates whether this contract adheres to the specified interface.
     /// @dev See {IERC165-supportsInterface}.
-    /// @param interfaceId The ID of the interface to check for adherance to.
+    /// @param interfaceId The ID of the interface to check for adherence to.
     /// @return A flag indicating if the provided interface ID is supported.
     function supportsInterface(bytes4 interfaceId) public view virtual override(ERC165, IERC165) returns (bool) {
         return interfaceId == type(IJBController).interfaceId || interfaceId == type(IJBProjectUriRegistry).interfaceId

src/JBDeadline.sol

@@ -8,34 +8,31 @@ import {JBApprovalStatus} from "./enums/JBApprovalStatus.sol";
 import {IJBRulesetApprovalHook} from "./interfaces/IJBRulesetApprovalHook.sol";
 import {JBRuleset} from "./structs/JBRuleset.sol";
 
-/// @notice Ruleset approval hook which rejects rulesets if they are not queued at least `duration` seconds before the
-/// current ruleset ends. In other words, rulesets must be queued before the deadline to take effect.
+/// @notice `JBDeadline` is a ruleset approval hook which rejects rulesets if they are not queued at least `duration` seconds before the current ruleset ends. In other words, rulesets must be queued before the deadline to take effect.
+/// @dev Project rulesets are stored in a queue. Rulesets take effect after the previous ruleset in the queue ends, and only if they are approved by the previous ruleset's approval hook.
 contract JBDeadline is ERC165, IJBRulesetApprovalHook {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    /// @notice Throw if the duration used to initialize this contract is too long.
     error DURATION_TOO_LONG();
 
     //*********************************************************************//
     // ---------------- public immutable stored properties --------------- //
     //*********************************************************************//
 
-    /// @notice The minimum difference between the time a ruleset is queued and the time it starts, as a number of
-    /// seconds. If the difference is greater than this number, the ruleset is `Approved`.
+    /// @notice The minimum number of seconds between the time a ruleset is queued and the time it starts. If the difference is greater than this number, the ruleset is `Approved`.
     uint256 public immutable override DURATION;
 
     //*********************************************************************//
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
-    /// @notice The approval status of a particular ruleset.
-    /// @param projectId The ID of the project to which the ruleset being checked belongs.
-    /// @param rulesetId The `rulesetId` of the ruleset to check the status of. The `rulesetId` is the timestamp for
-    /// when ruleset was queued.
+    /// @notice The approval status of a given ruleset.
+    /// @param projectId The ID of the project the ruleset belongs to.
+    /// @param rulesetId The ID of the ruleset to check the status of.
     /// @param start The start timestamp of the ruleset to check the status of.
-    /// @return The status of the approval hook.
+    /// @return The ruleset's approval status.
     function approvalStatusOf(
         uint256 projectId,
         uint256 rulesetId,
@@ -48,22 +45,23 @@ contract JBDeadline is ERC165, IJBRulesetApprovalHook {
     {
         projectId; // Prevents unused var compiler and natspec complaints.
 
-        // If the provided rulesetId timestamp is after the start timestamp, the approval hook is Failed.
+        // The ruleset ID is the timestamp at which the ruleset was queued.
+        // If the provided `rulesetId` timestamp is after the start timestamp, the ruleset has `Failed`.
         if (rulesetId > start) return JBApprovalStatus.Failed;
 
         unchecked {
-            // If there was sufficient time between queuing and the start of the ruleset, it is approved. Otherwise, it
-            // is failed.
-            // If the approval hook hasn't yet started, its approval status is ApprovalExpected.
+            // If there aren't enough seconds between the time the ruleset was queued and the time it starts, it has `Failed`.
+            // Otherwise, if there is still time before the deadline, the ruleset's status is `ApprovalExpected`.
+            // If we've already passed the deadline, the ruleset is `Approved`.
             return (start - rulesetId < DURATION)
                 ? JBApprovalStatus.Failed
                 : (block.timestamp < start - DURATION) ? JBApprovalStatus.ApprovalExpected : JBApprovalStatus.Approved;
         }
     }
 
-    /// @notice Indicates if this contract adheres to the specified interface.
+    /// @notice Indicates whether this contract adheres to the specified interface.
     /// @dev See {IERC165-supportsInterface}.
-    /// @param interfaceId The ID of the interface to check for adherance to.
+    /// @param interfaceId The ID of the interface to check for adherence to.
     /// @return A flag indicating if this contract adheres to the specified interface.
     function supportsInterface(bytes4 interfaceId) public view virtual override(ERC165, IERC165) returns (bool) {
         return interfaceId == type(IJBRulesetApprovalHook).interfaceId || super.supportsInterface(interfaceId);
@@ -73,8 +71,7 @@ contract JBDeadline is ERC165, IJBRulesetApprovalHook {
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
-    /// @param duration The minimum number of seconds between the time a ruleset is queued and that ruleset's `start`
-    /// for it to be `Approved`.
+    /// @param duration The minimum number of seconds between the time a ruleset is queued and the time it starts for it to be `Approved`.
     constructor(uint256 duration) {
         // Ensure we don't underflow in `approvalStatusOf(...)`.
         if (duration > block.timestamp) revert DURATION_TOO_LONG();