docs: improve natspec structure (skip ci)

src/EmergencyDropSpell.sol

@@ -71,11 +71,13 @@ contract EmergencyDropSpell is EmergencySpellLike {
     /// @notice Drop have been called.
     event Drop();
 
-    /// @param _protego The Protego factory that deployed the spell.
-    /// @param _usr The original spell action address.
-    /// @param _tag The original spell action tag (i.e.: `extcodehash`).
-    /// @param _fax The original spell encoded call.
-    /// @param _eta The original spell expiry time.
+    /**
+     * @param _protego The Protego factory that deployed the spell.
+     * @param _usr The original spell action address.
+     * @param _tag The original spell action tag (i.e.: `extcodehash`).
+     * @param _fax The original spell encoded call.
+     * @param _eta The original spell expiry time.
+     */
     constructor(address _protego, address _usr, bytes32 _tag, bytes memory _fax, uint256 _eta) {
         protego = ProtegoLike(_protego);
         pause = DsPauseLike(ProtegoLike(_protego).pause());
@@ -85,8 +87,10 @@ contract EmergencyDropSpell is EmergencySpellLike {
         eta = _eta;
     }
 
-    /// @notice Alias for `drop`.
-    /// @dev for compatibility with `DssExec`.
+    /**
+     * @notice Alias for `drop`.
+     * @dev for compatibility with `DssExec`.
+     */
     function schedule() external {
         drop();
     }
@@ -114,7 +118,4 @@ contract EmergencyDropSpell is EmergencySpellLike {
     function planned() public view returns (bool) {
         return protego.planned(action, tag, sig, eta);
     }
-
 }
-
-

src/Protego.sol

@@ -22,69 +22,83 @@ interface DsPauseLike {
     function drop(address, bytes32, bytes calldata, uint256) external;
 }
 
-/// @title Protego: permisionlessly deploy spells to drop any plan in `DsPause`-like contracts.
+/// @title Protego: permisionlessly drop any plan in `DsPause`-like contracts.
 contract Protego {
-    /// @notice A reference to the DsPause contract.
+    /// @notice A reference to the `DsPause` contract.
     address public immutable pause;
 
-    /// @notice A new `EmergencyDropSpell` instance was deployed.
-    /// @param dropSpell The new `EmergencyDropSpell` address.
+    /**
+     * @notice A new `EmergencyDropSpell` instance was deployed.
+     * @param dropSpell The new `EmergencyDropSpell` address.
+     */
     event Deploy(address dropSpell);
 
-    /// @notice A spell plan was dropped.
-    /// @param id The ID of the dropped spell
+    /**
+     * @notice A spell plan was dropped.
+     * @param id The ID of the dropped plan.
+     */
     event Drop(bytes32 id);
 
-    /// @param _pause A reference to the DsPause contract.
+    /// @param _pause A reference to the `DsPause` contract.
     constructor(address _pause) {
         pause = _pause;
     }
 
-    /// @notice Deploys a spell to drop a plan based on attributes.
-    /// @param _usr The address of the scheduled spell.
-    /// @param _tag The tag identifying the address.
-    /// @param _fax The encoded call to be made in `_usr`.
-    /// @param _eta The expiry date.
-    /// @return _spell The `EmergencyDropSpell` address.
+    /**
+     * @notice Deploys a spell to drop a plan based on attributes.
+     * @param _usr The address of the scheduled spell.
+     * @param _tag The tag identifying the address.
+     * @param _fax The encoded call to be made in `_usr`.
+     * @param _eta The expiry date.
+     * @return _spell The `EmergencyDropSpell` address.
+     */
     function deploy(address _usr, bytes32 _tag, bytes memory _fax, uint256 _eta) public returns (address _spell) {
         _spell = address(new EmergencyDropSpell(address(this), _usr, _tag, _fax, _eta));
         emit Deploy(_spell);
     }
 
-    /// @notice Calculates the id for a set of attributes.
-    /// @param _usr The address of the scheduled spell.
-    /// @param _tag The tag identifying the address.
-    /// @param _fax The encoded call to be made in `_usr`.
-    /// @param _eta The expiry date.
+    /**
+     * @notice Calculates the id for a set of attributes.
+     * @param _usr The address of the scheduled spell.
+     * @param _tag The tag identifying the address.
+     * @param _fax The encoded call to be made in `_usr`.
+     * @param _eta The expiry date.
+     */
     function id(address _usr, bytes32 _tag, bytes memory _fax, uint256 _eta) public pure returns (bytes32) {
         return keccak256(abi.encode(_usr, _tag, _fax, _eta));
     }
 
-    /// @notice Returns whether a plan matching the set of attributes is currently planned.
-    /// @param _usr The address of the scheduled spell.
-    /// @param _tag The tag identifying the address.
-    /// @param _fax The encoded call to be made in `_usr`.
-    /// @param _eta The expiry date.
+    /**
+     * @notice Returns whether a plan matching the set of attributes is currently planned.
+     * @param _usr The address of the scheduled spell.
+     * @param _tag The tag identifying the address.
+     * @param _fax The encoded call to be made in `_usr`.
+     * @param _eta The expiry date.
+     */
     function planned(address _usr, bytes32 _tag, bytes memory _fax, uint256 _eta) external view returns (bool) {
         return planned(id(_usr, _tag, _fax, _eta));
     }
 
-    /// @notice Returns whether an id is planned or not.
-    /// @param _id The ide of the plan.
+    /**
+     * @notice Returns whether an id is planned or not.
+     * @param _id The ide of the plan.
+     */
     function planned(bytes32 _id) public view returns (bool) {
         return DsPauseLike(pause).plans(_id);
     }
 
-    /// @notice Permissionlessly drop anything that has been planned on the pause.
-    /// @dev In some cases, due to a faulty spell being voted, a governance attack or other unforseen causes, it may be
-    ///      necessary to block any spell that is entered into the pause proxy.
-    ///      In this extreme case, the system can be protected during the pause delay by lifting the Protego contract
-    ///      to the hat role, which will allow any user to permissionlessly drop any id from the pause.
-    ///      This function is expected to revert if it does not have the authority to perform this function.
-    /// @param _usr The address of the scheduled spell.
-    /// @param _tag The tag identifying the address.
-    /// @param _fax The encoded call to be made in `_usr`.
-    /// @param _eta The expiration time.
+    /**
+     * @notice Permissionlessly drop anything that has been planned on the pause.
+     * @dev In some cases, due to a faulty spell being voted, a governance attack or other unforseen causes, it may be
+     *      necessary to block any spell that is entered into the pause proxy.
+     *      In this extreme case, the system can be protected during the pause delay by lifting the Protego contract to
+     *      the hat role, which will allow any user to permissionlessly drop any id from the pause.
+     *      This function is expected to revert if it does not have the authority to perform this function.
+     * @param _usr The address of the scheduled spell.
+     * @param _tag The tag identifying the address.
+     * @param _fax The encoded call to be made in `_usr`.
+     * @param _eta The expiration time.
+     */
     function drop(address _usr, bytes32 _tag, bytes memory _fax, uint256 _eta) public {
         DsPauseLike(pause).drop(_usr, _tag, _fax, _eta);
         emit Drop(id(_usr, _tag, _fax, _eta));