Port libraries to triple slash natspec styling.

packages/contracts-bedrock/contracts/libraries/Arithmetic.sol

@@ -4,20 +4,14 @@ pragma solidity 0.8.15;
 import { SignedMath } from "@openzeppelin/contracts/utils/math/SignedMath.sol";
 import { FixedPointMathLib } from "@rari-capital/solmate/src/utils/FixedPointMathLib.sol";
 
-/**
- * @title Arithmetic
- * @notice Even more math than before.
- */
+/// @title Arithmetic
+/// @notice Even more math than before.
 library Arithmetic {
-    /**
-     * @notice Clamps a value between a minimum and maximum.
-     *
-     * @param _value The value to clamp.
-     * @param _min   The minimum value.
-     * @param _max   The maximum value.
-     *
-     * @return The clamped value.
-     */
+    /// @notice Clamps a value between a minimum and maximum.
+    /// @param _value The value to clamp.
+    /// @param _min   The minimum value.
+    /// @param _max   The maximum value.
+    /// @return The clamped value.
     function clamp(
         int256 _value,
         int256 _min,
@@ -26,16 +20,12 @@ library Arithmetic {
         return SignedMath.min(SignedMath.max(_value, _min), _max);
     }
 
-    /**
-     * @notice (c)oefficient (d)enominator (exp)onentiation function.
-     *         Returns the result of: c * (1 - 1/d)^exp.
-     *
-     * @param _coefficient Coefficient of the function.
-     * @param _denominator Fractional denominator.
-     * @param _exponent    Power function exponent.
-     *
-     * @return Result of c * (1 - 1/d)^exp.
-     */
+    /// @notice (c)oefficient (d)enominator (exp)onentiation function.
+    ///         Returns the result of: c * (1 - 1/d)^exp.
+    /// @param _coefficient Coefficient of the function.
+    /// @param _denominator Fractional denominator.
+    /// @param _exponent    Power function exponent.
+    /// @return Result of c * (1 - 1/d)^exp.
     function cdexp(
         int256 _coefficient,
         int256 _denominator,

packages/contracts-bedrock/contracts/libraries/Burn.sol

 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.15;
 
-/**
- * @title Burn
- * @notice Utilities for burning stuff.
- */
+/// @title Burn
+/// @notice Utilities for burning stuff.
 library Burn {
-    /**
-     * Burns a given amount of ETH.
-     *
-     * @param _amount Amount of ETH to burn.
-     */
+    /// @notice Burns a given amount of ETH.
+    /// @param _amount Amount of ETH to burn.
     function eth(uint256 _amount) internal {
         new Burner{ value: _amount }();
     }
 
-    /**
-     * Burns a given amount of gas.
-     *
-     * @param _amount Amount of gas to burn.
-     */
+    /// @notice Burns a given amount of gas.
+    /// @param _amount Amount of gas to burn.
     function gas(uint256 _amount) internal view {
         uint256 i = 0;
         uint256 initialGas = gasleft();
@@ -29,12 +21,10 @@ library Burn {
     }
 }
 
-/**
- * @title Burner
- * @notice Burner self-destructs on creation and sends all ETH to itself, removing all ETH given to
- *         the contract from the circulating supply. Self-destructing is the only way to remove ETH
- *         from the circulating supply.
- */
+/// @title Burner
+/// @notice Burner self-destructs on creation and sends all ETH to itself, removing all ETH given to
+///         the contract from the circulating supply. Self-destructing is the only way to remove ETH
+///         from the circulating supply.
 contract Burner {
     constructor() payable {
         selfdestruct(payable(address(this)));

packages/contracts-bedrock/contracts/libraries/Bytes.sol

 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/**
- * @title Bytes
- * @notice Bytes is a library for manipulating byte arrays.
- */
+/// @title Bytes
+/// @notice Bytes is a library for manipulating byte arrays.
 library Bytes {
-    /**
-     * @custom:attribution https://github.com/GNSPS/solidity-bytes-utils
-     * @notice Slices a byte array with a given starting index and length. Returns a new byte array
-     *         as opposed to a pointer to the original array. Will throw if trying to slice more
-     *         bytes than exist in the array.
-     *
-     * @param _bytes Byte array to slice.
-     * @param _start Starting index of the slice.
-     * @param _length Length of the slice.
-     *
-     * @return Slice of the input byte array.
-     */
+    /// @custom:attribution https://github.com/GNSPS/solidity-bytes-utils
+    /// @notice Slices a byte array with a given starting index and length. Returns a new byte array
+    ///         as opposed to a pointer to the original array. Will throw if trying to slice more
+    ///         bytes than exist in the array.
+    /// @param _bytes Byte array to slice.
+    /// @param _start Starting index of the slice.
+    /// @param _length Length of the slice.
+    /// @return Slice of the input byte array.
     function slice(
         bytes memory _bytes,
         uint256 _start,
@@ -87,15 +81,11 @@ library Bytes {
         return tempBytes;
     }
 
-    /**
-     * @notice Slices a byte array with a given starting index up to the end of the original byte
-     *         array. Returns a new array rathern than a pointer to the original.
-     *
-     * @param _bytes Byte array to slice.
-     * @param _start Starting index of the slice.
-     *
-     * @return Slice of the input byte array.
-     */
+    /// @notice Slices a byte array with a given starting index up to the end of the original byte
+    ///         array. Returns a new array rathern than a pointer to the original.
+    /// @param _bytes Byte array to slice.
+    /// @param _start Starting index of the slice.
+    /// @return Slice of the input byte array.
     function slice(bytes memory _bytes, uint256 _start) internal pure returns (bytes memory) {
         if (_start >= _bytes.length) {
             return bytes("");
@@ -103,14 +93,10 @@ library Bytes {
         return slice(_bytes, _start, _bytes.length - _start);
     }
 
-    /**
-     * @notice Converts a byte array into a nibble array by splitting each byte into two nibbles.
-     *         Resulting nibble array will be exactly twice as long as the input byte array.
-     *
-     * @param _bytes Input byte array to convert.
-     *
-     * @return Resulting nibble array.
-     */
+    /// @notice Converts a byte array into a nibble array by splitting each byte into two nibbles.
+    ///         Resulting nibble array will be exactly twice as long as the input byte array.
+    /// @param _bytes Input byte array to convert.
+    /// @return Resulting nibble array.
     function toNibbles(bytes memory _bytes) internal pure returns (bytes memory) {
         bytes memory _nibbles;
         assembly {
@@ -158,14 +144,10 @@ library Bytes {
         return _nibbles;
     }
 
-    /**
-     * @notice Compares two byte arrays by comparing their keccak256 hashes.
-     *
-     * @param _bytes First byte array to compare.
-     * @param _other Second byte array to compare.
-     *
-     * @return True if the two byte arrays are equal, false otherwise.
-     */
+    /// @notice Compares two byte arrays by comparing their keccak256 hashes.
+    /// @param _bytes First byte array to compare.
+    /// @param _other Second byte array to compare.
+    /// @return True if the two byte arrays are equal, false otherwise.
     function equal(bytes memory _bytes, bytes memory _other) internal pure returns (bool) {
         return keccak256(_bytes) == keccak256(_other);
     }

packages/contracts-bedrock/contracts/libraries/Clone.sol

 // SPDX-License-Identifier: BSD
 pragma solidity ^0.8.15;
 
-// solhint-disable
-/**
- * @title Clone
- * @author zefram.eth, Saw-mon & Natalie, clabby
- * @notice Provides helper functions for reading immutable args from calldata
- * @dev Original: https://github.com/Saw-mon-and-Natalie/clones-with-immutable-args/blob/105efee1b9127ed7f6fedf139e1fc796ce8791f2/src/Clone.sol
- * @dev MODIFICATIONS:
- *      - Added `_getArgDynBytes` function.
- */
-// solhint-enable
+/// @title Clone
+/// @author zefram.eth, Saw-mon & Natalie, clabby
+/// @notice Provides helper functions for reading immutable args from calldata
+/// @dev Original:
+///      https://github.com/Saw-mon-and-Natalie/clones-with-immutable-args/
+///      blob/105efee1b9127ed7f6fedf139e1fc796ce8791f2/src/Clone.sol
+/// @dev MODIFICATIONS:
+///      - Added `_getArgDynBytes` function.
 contract Clone {
     uint256 private constant ONE_WORD = 0x20;
 
-    /**
-     * @notice Reads an immutable arg with type address
-     * @param argOffset The offset of the arg in the packed data
-     * @return arg The arg value
-     */
+    /// @notice Reads an immutable arg with type address
+    /// @param argOffset The offset of the arg in the packed data
+    /// @return arg The arg value
     function _getArgAddress(uint256 argOffset) internal pure returns (address arg) {
         uint256 offset = _getImmutableArgsOffset();
         assembly {
@@ -26,11 +22,9 @@ contract Clone {
         }
     }
 
-    /**
-     * @notice Reads an immutable arg with type uint256
-     * @param argOffset The offset of the arg in the packed data
-     * @return arg The arg value
-     */
+    /// @notice Reads an immutable arg with type uint256
+    /// @param argOffset The offset of the arg in the packed data
+    /// @return arg The arg value
     function _getArgUint256(uint256 argOffset) internal pure returns (uint256 arg) {
         uint256 offset = _getImmutableArgsOffset();
         assembly {
@@ -38,11 +32,9 @@ contract Clone {
         }
     }
 
-    /**
-     * @notice Reads an immutable arg with type bytes32
-     * @param argOffset The offset of the arg in the packed data
-     * @return arg The arg value
-     */
+    /// @notice Reads an immutable arg with type bytes32
+    /// @param argOffset The offset of the arg in the packed data
+    /// @return arg The arg value
     function _getArgFixedBytes(uint256 argOffset) internal pure returns (bytes32 arg) {
         uint256 offset = _getImmutableArgsOffset();
         assembly {
@@ -50,12 +42,10 @@ contract Clone {
         }
     }
 
-    /**
-     * @notice Reads a uint256 array stored in the immutable args.
-     * @param argOffset The offset of the arg in the packed data
-     * @param arrLen Number of elements in the array
-     * @return arr The array
-     */
+    /// @notice Reads a uint256 array stored in the immutable args.
+    /// @param argOffset The offset of the arg in the packed data
+    /// @param arrLen Number of elements in the array
+    /// @return arr The array
     function _getArgUint256Array(uint256 argOffset, uint64 arrLen)
         internal
         pure
@@ -69,12 +59,10 @@ contract Clone {
         }
     }
 
-    /**
-     * @notice Reads a dynamic bytes array stored in the immutable args.
-     * @param argOffset The offset of the arg in the packed data
-     * @param arrLen Number of elements in the array
-     * @return arr The array
-     */
+    /// @notice Reads a dynamic bytes array stored in the immutable args.
+    /// @param argOffset The offset of the arg in the packed data
+    /// @param arrLen Number of elements in the array
+    /// @return arr The array
     function _getArgDynBytes(uint256 argOffset, uint64 arrLen)
         internal
         pure
@@ -88,11 +76,9 @@ contract Clone {
         }
     }
 
-    /**
-     * @notice Reads an immutable arg with type uint64
-     * @param argOffset The offset of the arg in the packed data
-     * @return arg The arg value
-     */
+    /// @notice Reads an immutable arg with type uint64
+    /// @param argOffset The offset of the arg in the packed data
+    /// @return arg The arg value
     function _getArgUint64(uint256 argOffset) internal pure returns (uint64 arg) {
         uint256 offset = _getImmutableArgsOffset();
         assembly {
@@ -100,11 +86,9 @@ contract Clone {
         }
     }
 
-    /**
-     * @notice Reads an immutable arg with type uint8
-     * @param argOffset The offset of the arg in the packed data
-     * @return arg The arg value
-     */
+    /// @notice Reads an immutable arg with type uint8
+    /// @param argOffset The offset of the arg in the packed data
+    /// @return arg The arg value
     function _getArgUint8(uint256 argOffset) internal pure returns (uint8 arg) {
         uint256 offset = _getImmutableArgsOffset();
         assembly {
@@ -112,9 +96,7 @@ contract Clone {
         }
     }
 
-    /**
-     * @return offset The offset of the packed immutable args in calldata
-     */
+    /// @return offset The offset of the packed immutable args in calldata
     function _getImmutableArgsOffset() internal pure returns (uint256 offset) {
         assembly {
             offset := sub(calldatasize(), shr(0xf0, calldataload(sub(calldatasize(), 2))))

packages/contracts-bedrock/contracts/libraries/Constants.sol

@@ -3,34 +3,26 @@ pragma solidity ^0.8.0;
 
 import { ResourceMetering } from "../L1/ResourceMetering.sol";
 
-/**
- * @title Constants
- * @notice Constants is a library for storing constants. Simple! Don't put everything in here, just
- *         the stuff used in multiple contracts. Constants that only apply to a single contract
- *         should be defined in that contract instead.
- */
+/// @title Constants
+/// @notice Constants is a library for storing constants. Simple! Don't put everything in here, just
+///         the stuff used in multiple contracts. Constants that only apply to a single contract
+///         should be defined in that contract instead.
 library Constants {
-    /**
-     * @notice Special address to be used as the tx origin for gas estimation calls in the
-     *         OptimismPortal and CrossDomainMessenger calls. You only need to use this address if
-     *         the minimum gas limit specified by the user is not actually enough to execute the
-     *         given message and you're attempting to estimate the actual necessary gas limit. We
-     *         use address(1) because it's the ecrecover precompile and therefore guaranteed to
-     *         never have any code on any EVM chain.
-     */
+    /// @notice Special address to be used as the tx origin for gas estimation calls in the
+    ///         OptimismPortal and CrossDomainMessenger calls. You only need to use this address if
+    ///         the minimum gas limit specified by the user is not actually enough to execute the
+    ///         given message and you're attempting to estimate the actual necessary gas limit. We
+    ///         use address(1) because it's the ecrecover precompile and therefore guaranteed to
+    ///         never have any code on any EVM chain.
     address internal constant ESTIMATION_ADDRESS = address(1);
 
-    /**
-     * @notice Value used for the L2 sender storage slot in both the OptimismPortal and the
-     *         CrossDomainMessenger contracts before an actual sender is set. This value is
-     *         non-zero to reduce the gas cost of message passing transactions.
-     */
+    /// @notice Value used for the L2 sender storage slot in both the OptimismPortal and the
+    ///         CrossDomainMessenger contracts before an actual sender is set. This value is
+    ///         non-zero to reduce the gas cost of message passing transactions.
     address internal constant DEFAULT_L2_SENDER = 0x000000000000000000000000000000000000dEaD;
 
-    /**
-     * @notice Returns the default values for the ResourceConfig. These are the recommended values
-     *         for a production network.
-     */
+    /// @notice Returns the default values for the ResourceConfig. These are the recommended values
+    ///         for a production network.
     function DEFAULT_RESOURCE_CONFIG()
         internal
         pure

packages/contracts-bedrock/contracts/libraries/Encoding.sol

@@ -5,20 +5,14 @@ import { Types } from "./Types.sol";
 import { Hashing } from "./Hashing.sol";
 import { RLPWriter } from "./rlp/RLPWriter.sol";
 
-/**
- * @title Encoding
- * @notice Encoding handles Optimism's various different encoding schemes.
- */
+/// @title Encoding
+/// @notice Encoding handles Optimism's various different encoding schemes.
 library Encoding {
-    /**
-     * @notice RLP encodes the L2 transaction that would be generated when a given deposit is sent
-     *         to the L2 system. Useful for searching for a deposit in the L2 system. The
-     *         transaction is prefixed with 0x7e to identify its EIP-2718 type.
-     *
-     * @param _tx User deposit transaction to encode.
-     *
-     * @return RLP encoded L2 deposit transaction.
-     */
+    /// @notice RLP encodes the L2 transaction that would be generated when a given deposit is sent
+    ///         to the L2 system. Useful for searching for a deposit in the L2 system. The
+    ///         transaction is prefixed with 0x7e to identify its EIP-2718 type.
+    /// @param _tx User deposit transaction to encode.
+    /// @return RLP encoded L2 deposit transaction.
     function encodeDepositTransaction(Types.UserDepositTransaction memory _tx)
         internal
         pure
@@ -37,19 +31,15 @@ library Encoding {
         return abi.encodePacked(uint8(0x7e), RLPWriter.writeList(raw));
     }
 
-    /**
-     * @notice Encodes the cross domain message based on the version that is encoded into the
-     *         message nonce.
-     *
-     * @param _nonce    Message nonce with version encoded into the first two bytes.
-     * @param _sender   Address of the sender of the message.
-     * @param _target   Address of the target of the message.
-     * @param _value    ETH value to send to the target.
-     * @param _gasLimit Gas limit to use for the message.
-     * @param _data     Data to send with the message.
-     *
-     * @return Encoded cross domain message.
-     */
+    /// @notice Encodes the cross domain message based on the version that is encoded into the
+    ///         message nonce.
+    /// @param _nonce    Message nonce with version encoded into the first two bytes.
+    /// @param _sender   Address of the sender of the message.
+    /// @param _target   Address of the target of the message.
+    /// @param _value    ETH value to send to the target.
+    /// @param _gasLimit Gas limit to use for the message.
+    /// @param _data     Data to send with the message.
+    /// @return Encoded cross domain message.
     function encodeCrossDomainMessage(
         uint256 _nonce,
         address _sender,
@@ -68,16 +58,12 @@ library Encoding {
         }
     }
 
-    /**
-     * @notice Encodes a cross domain message based on the V0 (legacy) encoding.
-     *
-     * @param _target Address of the target of the message.
-     * @param _sender Address of the sender of the message.
-     * @param _data   Data to send with the message.
-     * @param _nonce  Message nonce.
-     *
-     * @return Encoded cross domain message.
-     */
+    /// @notice Encodes a cross domain message based on the V0 (legacy) encoding.
+    /// @param _target Address of the target of the message.
+    /// @param _sender Address of the sender of the message.
+    /// @param _data   Data to send with the message.
+    /// @param _nonce  Message nonce.
+    /// @return Encoded cross domain message.
     function encodeCrossDomainMessageV0(
         address _target,
         address _sender,
@@ -94,18 +80,14 @@ library Encoding {
             );
     }
 
-    /**
-     * @notice Encodes a cross domain message based on the V1 (current) encoding.
-     *
-     * @param _nonce    Message nonce.
-     * @param _sender   Address of the sender of the message.
-     * @param _target   Address of the target of the message.
-     * @param _value    ETH value to send to the target.
-     * @param _gasLimit Gas limit to use for the message.
-     * @param _data     Data to send with the message.
-     *
-     * @return Encoded cross domain message.
-     */
+    /// @notice Encodes a cross domain message based on the V1 (current) encoding.
+    /// @param _nonce    Message nonce.
+    /// @param _sender   Address of the sender of the message.
+    /// @param _target   Address of the target of the message.
+    /// @param _value    ETH value to send to the target.
+    /// @param _gasLimit Gas limit to use for the message.
+    /// @param _data     Data to send with the message.
+    /// @return Encoded cross domain message.
     function encodeCrossDomainMessageV1(
         uint256 _nonce,
         address _sender,
@@ -126,14 +108,10 @@ library Encoding {
             );
     }
 
-    /**
-     * @notice Adds a version number into the first two bytes of a message nonce.
-     *
-     * @param _nonce   Message nonce to encode into.
-     * @param _version Version number to encode into the message nonce.
-     *
-     * @return Message nonce with version encoded into the first two bytes.
-     */
+    /// @notice Adds a version number into the first two bytes of a message nonce.
+    /// @param _nonce   Message nonce to encode into.
+    /// @param _version Version number to encode into the message nonce.
+    /// @return Message nonce with version encoded into the first two bytes.
     function encodeVersionedNonce(uint240 _nonce, uint16 _version) internal pure returns (uint256) {
         uint256 nonce;
         assembly {
@@ -142,14 +120,10 @@ library Encoding {
         return nonce;
     }
 
-    /**
-     * @notice Pulls the version out of a version-encoded nonce.
-     *
-     * @param _nonce Message nonce with version encoded into the first two bytes.
-     *
-     * @return Nonce without encoded version.
-     * @return Version of the message.
-     */
+    /// @notice Pulls the version out of a version-encoded nonce.
+    /// @param _nonce Message nonce with version encoded into the first two bytes.
+    /// @return Nonce without encoded version.
+    /// @return Version of the message.
     function decodeVersionedNonce(uint256 _nonce) internal pure returns (uint240, uint16) {
         uint240 nonce;
         uint16 version;

packages/contracts-bedrock/contracts/libraries/Hashing.sol

@@ -4,20 +4,14 @@ pragma solidity ^0.8.0;
 import { Types } from "./Types.sol";
 import { Encoding } from "./Encoding.sol";
 
-/**
- * @title Hashing
- * @notice Hashing handles Optimism's various different hashing schemes.
- */
+/// @title Hashing
+/// @notice Hashing handles Optimism's various different hashing schemes.
 library Hashing {
-    /**
-     * @notice Computes the hash of the RLP encoded L2 transaction that would be generated when a
-     *         given deposit is sent to the L2 system. Useful for searching for a deposit in the L2
-     *         system.
-     *
-     * @param _tx User deposit transaction to hash.
-     *
-     * @return Hash of the RLP encoded L2 deposit transaction.
-     */
+    /// @notice Computes the hash of the RLP encoded L2 transaction that would be generated when a
+    ///         given deposit is sent to the L2 system. Useful for searching for a deposit in the L2
+    ///         system.
+    /// @param _tx User deposit transaction to hash.
+    /// @return Hash of the RLP encoded L2 deposit transaction.
     function hashDepositTransaction(Types.UserDepositTransaction memory _tx)
         internal
         pure
@@ -26,16 +20,12 @@ library Hashing {
         return keccak256(Encoding.encodeDepositTransaction(_tx));
     }
 
-    /**
-     * @notice Computes the deposit transaction's "source hash", a value that guarantees the hash
-     *         of the L2 transaction that corresponds to a deposit is unique and is
-     *         deterministically generated from L1 transaction data.
-     *
-     * @param _l1BlockHash Hash of the L1 block where the deposit was included.
-     * @param _logIndex    The index of the log that created the deposit transaction.
-     *
-     * @return Hash of the deposit transaction's "source hash".
-     */
+    /// @notice Computes the deposit transaction's "source hash", a value that guarantees the hash
+    ///         of the L2 transaction that corresponds to a deposit is unique and is
+    ///         deterministically generated from L1 transaction data.
+    /// @param _l1BlockHash Hash of the L1 block where the deposit was included.
+    /// @param _logIndex    The index of the log that created the deposit transaction.
+    /// @return Hash of the deposit transaction's "source hash".
     function hashDepositSource(bytes32 _l1BlockHash, uint256 _logIndex)
         internal
         pure
@@ -45,19 +35,15 @@ library Hashing {
         return keccak256(abi.encode(bytes32(0), depositId));
     }
 
-    /**
-     * @notice Hashes the cross domain message based on the version that is encoded into the
-     *         message nonce.
-     *
-     * @param _nonce    Message nonce with version encoded into the first two bytes.
-     * @param _sender   Address of the sender of the message.
-     * @param _target   Address of the target of the message.
-     * @param _value    ETH value to send to the target.
-     * @param _gasLimit Gas limit to use for the message.
-     * @param _data     Data to send with the message.
-     *
-     * @return Hashed cross domain message.
-     */
+    /// @notice Hashes the cross domain message based on the version that is encoded into the
+    ///         message nonce.
+    /// @param _nonce    Message nonce with version encoded into the first two bytes.
+    /// @param _sender   Address of the sender of the message.
+    /// @param _target   Address of the target of the message.
+    /// @param _value    ETH value to send to the target.
+    /// @param _gasLimit Gas limit to use for the message.
+    /// @param _data     Data to send with the message.
+    /// @return Hashed cross domain message.
     function hashCrossDomainMessage(
         uint256 _nonce,
         address _sender,
@@ -76,16 +62,12 @@ library Hashing {
         }
     }
 
-    /**
-     * @notice Hashes a cross domain message based on the V0 (legacy) encoding.
-     *
-     * @param _target Address of the target of the message.
-     * @param _sender Address of the sender of the message.
-     * @param _data   Data to send with the message.
-     * @param _nonce  Message nonce.
-     *
-     * @return Hashed cross domain message.
-     */
+    /// @notice Hashes a cross domain message based on the V0 (legacy) encoding.
+    /// @param _target Address of the target of the message.
+    /// @param _sender Address of the sender of the message.
+    /// @param _data   Data to send with the message.
+    /// @param _nonce  Message nonce.
+    /// @return Hashed cross domain message.
     function hashCrossDomainMessageV0(
         address _target,
         address _sender,
@@ -95,18 +77,14 @@ library Hashing {
         return keccak256(Encoding.encodeCrossDomainMessageV0(_target, _sender, _data, _nonce));
     }
 
-    /**
-     * @notice Hashes a cross domain message based on the V1 (current) encoding.
-     *
-     * @param _nonce    Message nonce.
-     * @param _sender   Address of the sender of the message.
-     * @param _target   Address of the target of the message.
-     * @param _value    ETH value to send to the target.
-     * @param _gasLimit Gas limit to use for the message.
-     * @param _data     Data to send with the message.
-     *
-     * @return Hashed cross domain message.
-     */
+    /// @notice Hashes a cross domain message based on the V1 (current) encoding.
+    /// @param _nonce    Message nonce.
+    /// @param _sender   Address of the sender of the message.
+    /// @param _target   Address of the target of the message.
+    /// @param _value    ETH value to send to the target.
+    /// @param _gasLimit Gas limit to use for the message.
+    /// @param _data     Data to send with the message.
+    /// @return Hashed cross domain message.
     function hashCrossDomainMessageV1(
         uint256 _nonce,
         address _sender,
@@ -128,13 +106,9 @@ library Hashing {
             );
     }
 
-    /**
-     * @notice Derives the withdrawal hash according to the encoding in the L2 Withdrawer contract
-     *
-     * @param _tx Withdrawal transaction to hash.
-     *
-     * @return Hashed withdrawal transaction.
-     */
+    /// @notice Derives the withdrawal hash according to the encoding in the L2 Withdrawer contract
+    /// @param _tx Withdrawal transaction to hash.
+    /// @return Hashed withdrawal transaction.
     function hashWithdrawal(Types.WithdrawalTransaction memory _tx)
         internal
         pure
@@ -146,14 +120,10 @@ library Hashing {
             );
     }
 
-    /**
-     * @notice Hashes the various elements of an output root proof into an output root hash which
-     *         can be used to check if the proof is valid.
-     *
-     * @param _outputRootProof Output root proof which should hash to an output root.
-     *
-     * @return Hashed output root proof.
-     */
+    /// @notice Hashes the various elements of an output root proof into an output root hash which
+    ///         can be used to check if the proof is valid.
+    /// @param _outputRootProof Output root proof which should hash to an output root.
+    /// @return Hashed output root proof.
     function hashOutputRootProof(Types.OutputRootProof memory _outputRootProof)
         internal
         pure

packages/contracts-bedrock/contracts/libraries/LegacyCrossDomainUtils.sol

@@ -5,18 +5,15 @@ pragma solidity ^0.8.9;
 // so we just copy the library here from
 // /packages/contracts/contracts/libraries/bridge/Lib_CrossDomainUtils.sol at commit
 // 7866168c
-/**
- * @title LegacyCrossDomainUtils
- */
+
+/// @title LegacyCrossDomainUtils
 library LegacyCrossDomainUtils {
-    /**
-     * Generates the correct cross domain calldata for a message.
-     * @param _target Target contract address.
-     * @param _sender Message sender address.
-     * @param _message Message to send to the target.
-     * @param _messageNonce Nonce for the provided message.
-     * @return ABI encoded cross domain calldata.
-     */
+    /// @notice Generates the correct cross domain calldata for a message.
+    /// @param _target Target contract address.
+    /// @param _sender Message sender address.
+    /// @param _message Message to send to the target.
+    /// @param _messageNonce Nonce for the provided message.
+    /// @return ABI encoded cross domain calldata.
     function encodeXDomainCalldata(
         address _target,
         address _sender,

packages/contracts-bedrock/contracts/libraries/Predeploys.sol

 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/**
- * @title Predeploys
- * @notice Contains constant addresses for contracts that are pre-deployed to the L2 system.
- */
+/// @title Predeploys
+/// @notice Contains constant addresses for contracts that are pre-deployed to the L2 system.
 library Predeploys {
-    /**
-     * @notice Address of the L2ToL1MessagePasser predeploy.
-     */
+    /// @notice Address of the L2ToL1MessagePasser predeploy.
     address internal constant L2_TO_L1_MESSAGE_PASSER = 0x4200000000000000000000000000000000000016;
 
-    /**
-     * @notice Address of the L2CrossDomainMessenger predeploy.
-     */
+    /// @notice Address of the L2CrossDomainMessenger predeploy.
     address internal constant L2_CROSS_DOMAIN_MESSENGER =
         0x4200000000000000000000000000000000000007;
 
-    /**
-     * @notice Address of the L2StandardBridge predeploy.
-     */
+    /// @notice Address of the L2StandardBridge predeploy.
     address internal constant L2_STANDARD_BRIDGE = 0x4200000000000000000000000000000000000010;
 
-    /**
-     * @notice Address of the L2ERC721Bridge predeploy.
-     */
+    /// @notice Address of the L2ERC721Bridge predeploy.
     address internal constant L2_ERC721_BRIDGE = 0x4200000000000000000000000000000000000014;
 
-    /**
-     * @notice Address of the SequencerFeeWallet predeploy.
-     */
+    //// @notice Address of the SequencerFeeWallet predeploy.
     address internal constant SEQUENCER_FEE_WALLET = 0x4200000000000000000000000000000000000011;
 
-    /**
-     * @notice Address of the OptimismMintableERC20Factory predeploy.
-     */
+    /// @notice Address of the OptimismMintableERC20Factory predeploy.
     address internal constant OPTIMISM_MINTABLE_ERC20_FACTORY =
         0x4200000000000000000000000000000000000012;
 
-    /**
-     * @notice Address of the OptimismMintableERC721Factory predeploy.
-     */
+    /// @notice Address of the OptimismMintableERC721Factory predeploy.
     address internal constant OPTIMISM_MINTABLE_ERC721_FACTORY =
         0x4200000000000000000000000000000000000017;
 
-    /**
-     * @notice Address of the L1Block predeploy.
-     */
+    /// @notice Address of the L1Block predeploy.
     address internal constant L1_BLOCK_ATTRIBUTES = 0x4200000000000000000000000000000000000015;
 
-    /**
-     * @notice Address of the GasPriceOracle predeploy. Includes fee information
-     *         and helpers for computing the L1 portion of the transaction fee.
-     */
+    /// @notice Address of the GasPriceOracle predeploy. Includes fee information
+    ///         and helpers for computing the L1 portion of the transaction fee.
     address internal constant GAS_PRICE_ORACLE = 0x420000000000000000000000000000000000000F;
 
-    /**
-     * @custom:legacy
-     * @notice Address of the L1MessageSender predeploy. Deprecated. Use L2CrossDomainMessenger
-     *         or access tx.origin (or msg.sender) in a L1 to L2 transaction instead.
-     */
+    /// @custom:legacy
+    /// @notice Address of the L1MessageSender predeploy. Deprecated. Use L2CrossDomainMessenger
+    ///         or access tx.origin (or msg.sender) in a L1 to L2 transaction instead.
     address internal constant L1_MESSAGE_SENDER = 0x4200000000000000000000000000000000000001;
 
-    /**
-     * @custom:legacy
-     * @notice Address of the DeployerWhitelist predeploy. No longer active.
-     */
+    /// @custom:legacy
+    /// @notice Address of the DeployerWhitelist predeploy. No longer active.
     address internal constant DEPLOYER_WHITELIST = 0x4200000000000000000000000000000000000002;
 
-    /**
-     * @custom:legacy
-     * @notice Address of the LegacyERC20ETH predeploy. Deprecated. Balances are migrated to the
-     *         state trie as of the Bedrock upgrade. Contract has been locked and write functions
-     *         can no longer be accessed.
-     */
+    /// @custom:legacy
+    /// @notice Address of the LegacyERC20ETH predeploy. Deprecated. Balances are migrated to the
+    ///         state trie as of the Bedrock upgrade. Contract has been locked and write functions
+    ///         can no longer be accessed.
     address internal constant LEGACY_ERC20_ETH = 0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000;
 
-    /**
-     * @custom:legacy
-     * @notice Address of the L1BlockNumber predeploy. Deprecated. Use the L1Block predeploy
-     *         instead, which exposes more information about the L1 state.
-     */
+    /// @custom:legacy
+    /// @notice Address of the L1BlockNumber predeploy. Deprecated. Use the L1Block predeploy
+    ///         instead, which exposes more information about the L1 state.
     address internal constant L1_BLOCK_NUMBER = 0x4200000000000000000000000000000000000013;
 
-    /**
-     * @custom:legacy
-     * @notice Address of the LegacyMessagePasser predeploy. Deprecate. Use the updated
-     *         L2ToL1MessagePasser contract instead.
-     */
+    /// @custom:legacy
+    /// @notice Address of the LegacyMessagePasser predeploy. Deprecate. Use the updated
+    ///         L2ToL1MessagePasser contract instead.
     address internal constant LEGACY_MESSAGE_PASSER = 0x4200000000000000000000000000000000000000;
 
-    /**
-     * @notice Address of the ProxyAdmin predeploy.
-     */
+    /// @notice Address of the ProxyAdmin predeploy.
     address internal constant PROXY_ADMIN = 0x4200000000000000000000000000000000000018;
 
-    /**
-     * @notice Address of the BaseFeeVault predeploy.
-     */
+    /// @notice Address of the BaseFeeVault predeploy.
     address internal constant BASE_FEE_VAULT = 0x4200000000000000000000000000000000000019;
 
-    /**
-     * @notice Address of the L1FeeVault predeploy.
-     */
+    /// @notice Address of the L1FeeVault predeploy.
     address internal constant L1_FEE_VAULT = 0x420000000000000000000000000000000000001A;
 
-    /**
-     * @notice Address of the GovernanceToken predeploy.
-     */
+    /// @notice Address of the GovernanceToken predeploy.
     address internal constant GOVERNANCE_TOKEN = 0x4200000000000000000000000000000000000042;
 }

packages/contracts-bedrock/contracts/libraries/SafeCall.sol

 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.15;
 
-/**
- * @title SafeCall
- * @notice Perform low level safe calls
- */
+/// @title SafeCall
+/// @notice Perform low level safe calls
 library SafeCall {
-    /**
-     * @notice Performs a low level call without copying any returndata.
-     * @dev Passes no calldata to the call context.
-     *
-     * @param _target   Address to call
-     * @param _gas      Amount of gas to pass to the call
-     * @param _value    Amount of value to pass to the call
-     */
+    /// @notice Performs a low level call without copying any returndata.
+    /// @dev Passes no calldata to the call context.
+    /// @param _target   Address to call
+    /// @param _gas      Amount of gas to pass to the call
+    /// @param _value    Amount of value to pass to the call
     function send(
         address _target,
         uint256 _gas,
@@ -34,14 +29,11 @@ library SafeCall {
         return _success;
     }
 
-    /**
-     * @notice Perform a low level call without copying any returndata
-     *
-     * @param _target   Address to call
-     * @param _gas      Amount of gas to pass to the call
-     * @param _value    Amount of value to pass to the call
-     * @param _calldata Calldata to pass to the call
-     */
+    /// @notice Perform a low level call without copying any returndata
+    /// @param _target   Address to call
+    /// @param _gas      Amount of gas to pass to the call
+    /// @param _value    Amount of value to pass to the call
+    /// @param _calldata Calldata to pass to the call
     function call(
         address _target,
         uint256 _gas,
@@ -63,31 +55,29 @@ library SafeCall {
         return _success;
     }
 
-    /**
-     * @notice Helper function to determine if there is sufficient gas remaining within the context
-     *         to guarantee that the minimum gas requirement for a call will be met as well as
-     *         optionally reserving a specified amount of gas for after the call has concluded.
-     * @param _minGas      The minimum amount of gas that may be passed to the target context.
-     * @param _reservedGas Optional amount of gas to reserve for the caller after the execution
-     *                     of the target context.
-     * @return `true` if there is enough gas remaining to safely supply `_minGas` to the target
-     *         context as well as reserve `_reservedGas` for the caller after the execution of
-     *         the target context.
-     * @dev !!!!! FOOTGUN ALERT !!!!!
-     *      1.) The 40_000 base buffer is to account for the worst case of the dynamic cost of the
-     *          `CALL` opcode's `address_access_cost`, `positive_value_cost`, and
-     *          `value_to_empty_account_cost` factors with an added buffer of 5,700 gas. It is
-     *          still possible to self-rekt by initiating a withdrawal with a minimum gas limit
-     *          that does not account for the `memory_expansion_cost` & `code_execution_cost`
-     *          factors of the dynamic cost of the `CALL` opcode.
-     *      2.) This function should *directly* precede the external call if possible. There is an
-     *          added buffer to account for gas consumed between this check and the call, but it
-     *          is only 5,700 gas.
-     *      3.) Because EIP-150 ensures that a maximum of 63/64ths of the remaining gas in the call
-     *          frame may be passed to a subcontext, we need to ensure that the gas will not be
-     *          truncated.
-     *      4.) Use wisely. This function is not a silver bullet.
-     */
+    /// @notice Helper function to determine if there is sufficient gas remaining within the context
+    ///         to guarantee that the minimum gas requirement for a call will be met as well as
+    ///         optionally reserving a specified amount of gas for after the call has concluded.
+    /// @param _minGas      The minimum amount of gas that may be passed to the target context.
+    /// @param _reservedGas Optional amount of gas to reserve for the caller after the execution
+    ///                     of the target context.
+    /// @return `true` if there is enough gas remaining to safely supply `_minGas` to the target
+    ///         context as well as reserve `_reservedGas` for the caller after the execution of
+    ///         the target context.
+    /// @dev !!!!! FOOTGUN ALERT !!!!!
+    ///      1.) The 40_000 base buffer is to account for the worst case of the dynamic cost of the
+    ///          `CALL` opcode's `address_access_cost`, `positive_value_cost`, and
+    ///          `value_to_empty_account_cost` factors with an added buffer of 5,700 gas. It is
+    ///          still possible to self-rekt by initiating a withdrawal with a minimum gas limit
+    ///          that does not account for the `memory_expansion_cost` & `code_execution_cost`
+    ///          factors of the dynamic cost of the `CALL` opcode.
+    ///      2.) This function should *directly* precede the external call if possible. There is an
+    ///          added buffer to account for gas consumed between this check and the call, but it
+    ///          is only 5,700 gas.
+    ///      3.) Because EIP-150 ensures that a maximum of 63/64ths of the remaining gas in the call
+    ///          frame may be passed to a subcontext, we need to ensure that the gas will not be
+    ///          truncated.
+    ///      4.) Use wisely. This function is not a silver bullet.
     function hasMinGas(uint256 _minGas, uint256 _reservedGas) internal view returns (bool) {
         bool _hasMinGas;
         assembly {
@@ -99,16 +89,13 @@ library SafeCall {
         return _hasMinGas;
     }
 
-    /**
-     * @notice Perform a low level call without copying any returndata. This function
-     *         will revert if the call cannot be performed with the specified minimum
-     *         gas.
-     *
-     * @param _target   Address to call
-     * @param _minGas   The minimum amount of gas that may be passed to the call
-     * @param _value    Amount of value to pass to the call
-     * @param _calldata Calldata to pass to the call
-     */
+    /// @notice Perform a low level call without copying any returndata. This function
+    ///         will revert if the call cannot be performed with the specified minimum
+    ///         gas.
+    /// @param _target   Address to call
+    /// @param _minGas   The minimum amount of gas that may be passed to the call
+    /// @param _value    Amount of value to pass to the call
+    /// @param _calldata Calldata to pass to the call
     function callWithMinGas(
         address _target,
         uint256 _minGas,

packages/contracts-bedrock/contracts/libraries/Types.sol

 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/**
- * @title Types
- * @notice Contains various types used throughout the Optimism contract system.
- */
+/// @title Types
+/// @notice Contains various types used throughout the Optimism contract system.
 library Types {
-    /**
-     * @notice OutputProposal represents a commitment to the L2 state. The timestamp is the L1
-     *         timestamp that the output root is posted. This timestamp is used to verify that the
-     *         finalization period has passed since the output root was submitted.
-     *
-     * @custom:field outputRoot    Hash of the L2 output.
-     * @custom:field timestamp     Timestamp of the L1 block that the output root was submitted in.
-     * @custom:field l2BlockNumber L2 block number that the output corresponds to.
-     */
+    /// @notice OutputProposal represents a commitment to the L2 state. The timestamp is the L1
+    ///         timestamp that the output root is posted. This timestamp is used to verify that the
+    ///         finalization period has passed since the output root was submitted.
+    /// @custom:field outputRoot    Hash of the L2 output.
+    /// @custom:field timestamp     Timestamp of the L1 block that the output root was submitted in.
+    /// @custom:field l2BlockNumber L2 block number that the output corresponds to.
     struct OutputProposal {
         bytes32 outputRoot;
         uint128 timestamp;
         uint128 l2BlockNumber;
     }
 
-    /**
-     * @notice Struct representing the elements that are hashed together to generate an output root
-     *         which itself represents a snapshot of the L2 state.
-     *
-     * @custom:field version                  Version of the output root.
-     * @custom:field stateRoot                Root of the state trie at the block of this output.
-     * @custom:field messagePasserStorageRoot Root of the message passer storage trie.
-     * @custom:field latestBlockhash          Hash of the block this output was generated from.
-     */
+    /// @notice Struct representing the elements that are hashed together to generate an output root
+    ///         which itself represents a snapshot of the L2 state.
+    /// @custom:field version                  Version of the output root.
+    /// @custom:field stateRoot                Root of the state trie at the block of this output.
+    /// @custom:field messagePasserStorageRoot Root of the message passer storage trie.
+    /// @custom:field latestBlockhash          Hash of the block this output was generated from.
     struct OutputRootProof {
         bytes32 version;
         bytes32 stateRoot;
@@ -37,20 +29,17 @@ library Types {
         bytes32 latestBlockhash;
     }
 
-    /**
-     * @notice Struct representing a deposit transaction (L1 => L2 transaction) created by an end
-     *         user (as opposed to a system deposit transaction generated by the system).
-     *
-     * @custom:field from        Address of the sender of the transaction.
-     * @custom:field to          Address of the recipient of the transaction.
-     * @custom:field isCreation  True if the transaction is a contract creation.
-     * @custom:field value       Value to send to the recipient.
-     * @custom:field mint        Amount of ETH to mint.
-     * @custom:field gasLimit    Gas limit of the transaction.
-     * @custom:field data        Data of the transaction.
-     * @custom:field l1BlockHash Hash of the block the transaction was submitted in.
-     * @custom:field logIndex    Index of the log in the block the transaction was submitted in.
-     */
+    /// @notice Struct representing a deposit transaction (L1 => L2 transaction) created by an end
+    ///         user (as opposed to a system deposit transaction generated by the system).
+    /// @custom:field from        Address of the sender of the transaction.
+    /// @custom:field to          Address of the recipient of the transaction.
+    /// @custom:field isCreation  True if the transaction is a contract creation.
+    /// @custom:field value       Value to send to the recipient.
+    /// @custom:field mint        Amount of ETH to mint.
+    /// @custom:field gasLimit    Gas limit of the transaction.
+    /// @custom:field data        Data of the transaction.
+    /// @custom:field l1BlockHash Hash of the block the transaction was submitted in.
+    /// @custom:field logIndex    Index of the log in the block the transaction was submitted in.
     struct UserDepositTransaction {
         address from;
         address to;
@@ -63,16 +52,13 @@ library Types {
         uint256 logIndex;
     }
 
-    /**
-     * @notice Struct representing a withdrawal transaction.
-     *
-     * @custom:field nonce    Nonce of the withdrawal transaction
-     * @custom:field sender   Address of the sender of the transaction.
-     * @custom:field target   Address of the recipient of the transaction.
-     * @custom:field value    Value to send to the recipient.
-     * @custom:field gasLimit Gas limit of the transaction.
-     * @custom:field data     Data of the transaction.
-     */
+    /// @notice Struct representing a withdrawal transaction.
+    /// @custom:field nonce    Nonce of the withdrawal transaction
+    /// @custom:field sender   Address of the sender of the transaction.
+    /// @custom:field target   Address of the recipient of the transaction.
+    /// @custom:field value    Value to send to the recipient.
+    /// @custom:field gasLimit Gas limit of the transaction.
+    /// @custom:field data     Data of the transaction.
     struct WithdrawalTransaction {
         uint256 nonce;
         address sender;

packages/contracts-bedrock/contracts/test/Bytes.t.sol

 pragma solidity 0.8.15;
 
+// Testing utilities
 import { Test } from "forge-std/Test.sol";
+
+// Target contract
 import { Bytes } from "../libraries/Bytes.sol";
 
 contract Bytes_slice_Test is Test {
-    /**
-     * @notice Tests that the `slice` function works as expected when starting from index 0.
-     */
+    /// @notice Tests that the `slice` function works as expected when starting from index 0.
     function test_slice_fromZeroIdx_works() public {
         bytes memory input = hex"11223344556677889900";
 
@@ -24,10 +25,8 @@ contract Bytes_slice_Test is Test {
         assertEq(Bytes.slice(input, 0, 10), hex"11223344556677889900");
     }
 
-    /**
-     * @notice Tests that the `slice` function works as expected when starting from indices [1, 9]
-     *         with lengths [1, 9], in reverse order.
-     */
+    /// @notice Tests that the `slice` function works as expected when starting from indices [1, 9]
+    ///         with lengths [1, 9], in reverse order.
     function test_slice_fromNonZeroIdx_works() public {
         bytes memory input = hex"11223344556677889900";
 
@@ -44,11 +43,9 @@ contract Bytes_slice_Test is Test {
         assertEq(Bytes.slice(input, 1, 9), hex"223344556677889900");
     }
 
-    /**
-     * @notice Tests that the `slice` function works as expected when slicing between multiple words
-     *         in memory. In this case, we test that a 2 byte slice between the 32nd byte of the
-     *         first word and the 1st byte of the second word is correct.
-     */
+    /// @notice Tests that the `slice` function works as expected when slicing between multiple words
+    ///         in memory. In this case, we test that a 2 byte slice between the 32nd byte of the
+    ///         first word and the 1st byte of the second word is correct.
     function test_slice_acrossWords_works() public {
         bytes
             memory input = hex"00000000000000000000000000000000000000000000000000000000000000112200000000000000000000000000000000000000000000000000000000000000";
@@ -56,11 +53,9 @@ contract Bytes_slice_Test is Test {
         assertEq(Bytes.slice(input, 31, 2), hex"1122");
     }
 
-    /**
-     * @notice Tests that the `slice` function works as expected when slicing between multiple
-     *         words in memory. In this case, we test that a 34 byte slice between 3 separate words
-     *         returns the correct result.
-     */
+    /// @notice Tests that the `slice` function works as expected when slicing between multiple
+    ///         words in memory. In this case, we test that a 34 byte slice between 3 separate words
+    ///        returns the correct result.
     function test_slice_acrossMultipleWords_works() public {
         bytes
             memory input = hex"000000000000000000000000000000000000000000000000000000000000001122FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF1100000000000000000000000000000000000000000000000000000000000000";
@@ -70,10 +65,8 @@ contract Bytes_slice_Test is Test {
         assertEq(Bytes.slice(input, 31, 34), expected);
     }
 
-    /**
-     * @notice Tests that the `slice` function correctly updates the free memory pointer depending
-     *         on the length of the slice.
-     */
+    /// @notice Tests that the `slice` function correctly updates the free memory pointer depending
+    ///         on the length of the slice.
     function testFuzz_slice_memorySafety_succeeds(
         bytes memory _input,
         uint256 _start,
@@ -129,10 +122,8 @@ contract Bytes_slice_Test is Test {
 }
 
 contract Bytes_slice_TestFail is Test {
-    /**
-     * @notice Tests that, when given an input bytes array of length `n`, the `slice` function will
-     *         always revert if `_start + _length > n`.
-     */
+    /// @notice Tests that, when given an input bytes array of length `n`, the `slice` function will
+    ///         always revert if `_start + _length > n`.
     function testFuzz_slice_outOfBounds_reverts(
         bytes memory _input,
         uint256 _start,
@@ -147,10 +138,8 @@ contract Bytes_slice_TestFail is Test {
         Bytes.slice(_input, _start, _length);
     }
 
-    /**
-     * @notice Tests that, when given a length `n` that is greater than `type(uint256).max - 31`,
-     *         the `slice` function reverts.
-     */
+    /// @notice Tests that, when given a length `n` that is greater than `type(uint256).max - 31`,
+    ///         the `slice` function reverts.
     function testFuzz_slice_lengthOverflows_reverts(
         bytes memory _input,
         uint256 _start,
@@ -163,10 +152,8 @@ contract Bytes_slice_TestFail is Test {
         Bytes.slice(_input, _start, _length);
     }
 
-    /**
-     * @notice Tests that, when given a start index `n` that is greater than
-     *         `type(uint256).max - n`, the `slice` function reverts.
-     */
+    /// @notice Tests that, when given a start index `n` that is greater than
+    ///         `type(uint256).max - n`, the `slice` function reverts.
     function testFuzz_slice_rangeOverflows_reverts(
         bytes memory _input,
         uint256 _start,
@@ -184,10 +171,8 @@ contract Bytes_slice_TestFail is Test {
 }
 
 contract Bytes_toNibbles_Test is Test {
-    /**
-     * @notice Tests that, given an input of 5 bytes, the `toNibbles` function returns an array of
-     *         10 nibbles corresponding to the input data.
-     */
+    /// @notice Tests that, given an input of 5 bytes, the `toNibbles` function returns an array of
+    ///         10 nibbles corresponding to the input data.
     function test_toNibbles_expectedResult5Bytes_works() public {
         bytes memory input = hex"1234567890";
         bytes memory expected = hex"01020304050607080900";
@@ -198,11 +183,9 @@ contract Bytes_toNibbles_Test is Test {
         assertEq(actual, expected);
     }
 
-    /**
-     * @notice Tests that, given an input of 128 bytes, the `toNibbles` function returns an array
-     *         of 256 nibbles corresponding to the input data. This test exists to ensure that,
-     *         given a large input, the `toNibbles` function works as expected.
-     */
+    /// @notice Tests that, given an input of 128 bytes, the `toNibbles` function returns an array
+    ///         of 256 nibbles corresponding to the input data. This test exists to ensure that,
+    ///         given a large input, the `toNibbles` function works as expected.
     function test_toNibbles_expectedResult128Bytes_works() public {
         bytes
             memory input = hex"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f";
@@ -215,10 +198,8 @@ contract Bytes_toNibbles_Test is Test {
         assertEq(actual, expected);
     }
 
-    /**
-     * @notice Tests that, given an input of 0 bytes, the `toNibbles` function returns a zero
-     *         length array.
-     */
+    /// @notice Tests that, given an input of 0 bytes, the `toNibbles` function returns a zero
+    ///         length array.
     function test_toNibbles_zeroLengthInput_works() public {
         bytes memory input = hex"";
         bytes memory expected = hex"";
@@ -230,10 +211,8 @@ contract Bytes_toNibbles_Test is Test {
         assertEq(actual, expected);
     }
 
-    /**
-     * @notice Tests that the `toNibbles` function correctly updates the free memory pointer depending
-     *         on the length of the resulting array.
-     */
+    /// @notice Tests that the `toNibbles` function correctly updates the free memory pointer depending
+    ///         on the length of the resulting array.
     function testFuzz_toNibbles_memorySafety_succeeds(bytes memory _input) public {
         // Grab the free memory pointer before the `toNibbles` operation
         uint64 initPtr;
@@ -278,14 +257,10 @@ contract Bytes_toNibbles_Test is Test {
 }
 
 contract Bytes_equal_Test is Test {
-    /**
-     * @notice Manually checks equality of two dynamic `bytes` arrays in memory.
-     *
-     * @param _a The first `bytes` array to compare.
-     * @param _b The second `bytes` array to compare.
-     *
-     * @return True if the two `bytes` arrays are equal in memory.
-     */
+    /// @notice Manually checks equality of two dynamic `bytes` arrays in memory.
+    /// @param _a The first `bytes` array to compare.
+    /// @param _b The second `bytes` array to compare.
+    /// @return True if the two `bytes` arrays are equal in memory.
     function manualEq(bytes memory _a, bytes memory _b) internal pure returns (bool) {
         bool _eq;
         assembly {
@@ -300,19 +275,15 @@ contract Bytes_equal_Test is Test {
         return _eq;
     }
 
-    /**
-     * @notice Tests that the `equal` function in the `Bytes` library returns `false` if given two
-     *         non-equal byte arrays.
-     */
+    /// @notice Tests that the `equal` function in the `Bytes` library returns `false` if given two
+    ///         non-equal byte arrays.
     function testFuzz_equal_notEqual_works(bytes memory _a, bytes memory _b) public {
         vm.assume(!manualEq(_a, _b));
         assertFalse(Bytes.equal(_a, _b));
     }
 
-    /**
-     * @notice Test whether or not the `equal` function in the `Bytes` library is equivalent to
-     *         manually checking equality of the two dynamic `bytes` arrays in memory.
-     */
+    /// @notice Test whether or not the `equal` function in the `Bytes` library is equivalent to
+    ///         manually checking equality of the two dynamic `bytes` arrays in memory.
     function testDiff_equal_works(bytes memory _a, bytes memory _b) public {
         assertEq(Bytes.equal(_a, _b), manualEq(_a, _b));
     }

packages/contracts-bedrock/contracts/test/Encoding.t.sol

 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.15;
 
+// Testing utilities
 import { CommonTest } from "./CommonTest.t.sol";
+
+// Libraries
 import { Types } from "../libraries/Types.sol";
-import { Encoding } from "../libraries/Encoding.sol";
 import { LegacyCrossDomainUtils } from "../libraries/LegacyCrossDomainUtils.sol";
 
+// Target contract
+import { Encoding } from "../libraries/Encoding.sol";
+
 contract Encoding_Test is CommonTest {
+    /// @dev Tests encoding and decoding a nonce and version.
     function testFuzz_nonceVersioning_succeeds(uint240 _nonce, uint16 _version) external {
         (uint240 nonce, uint16 version) = Encoding.decodeVersionedNonce(
             Encoding.encodeVersionedNonce(_nonce, _version)
@@ -15,6 +21,7 @@ contract Encoding_Test is CommonTest {
         assertEq(nonce, _nonce);
     }
 
+    /// @dev Tests decoding a versioned nonce.
     function testDiff_decodeVersionedNonce_succeeds(uint240 _nonce, uint16 _version) external {
         uint256 nonce = uint256(Encoding.encodeVersionedNonce(_nonce, _version));
         (uint256 decodedNonce, uint256 decodedVersion) = ffi.decodeVersionedNonce(nonce);
@@ -24,6 +31,7 @@ contract Encoding_Test is CommonTest {
         assertEq(_nonce, uint240(decodedNonce));
     }
 
+    /// @dev Tests cross domain message encoding.
     function testDiff_encodeCrossDomainMessage_succeeds(
         uint240 _nonce,
         uint8 _version,
@@ -57,6 +65,7 @@ contract Encoding_Test is CommonTest {
         assertEq(encoding, _encoding);
     }
 
+    /// @dev Tests legacy cross domain message encoding.
     function testFuzz_encodeCrossDomainMessageV0_matchesLegacy_succeeds(
         uint240 _nonce,
         address _sender,
@@ -83,6 +92,7 @@ contract Encoding_Test is CommonTest {
         assertEq(legacyEncoding, bedrockEncoding);
     }
 
+    /// @dev Tests deposit transaction encoding.
     function testDiff_encodeDepositTransaction_succeeds(
         address _from,
         address _to,

packages/contracts-bedrock/contracts/test/Hashing.t.sol

 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.15;
 
+// Testing utilities
 import { CommonTest } from "./CommonTest.t.sol";
+
+// Libraries
 import { Types } from "../libraries/Types.sol";
-import { Hashing } from "../libraries/Hashing.sol";
 import { Encoding } from "../libraries/Encoding.sol";
 import { LegacyCrossDomainUtils } from "../libraries/LegacyCrossDomainUtils.sol";
 
+// Target contract
+import { Hashing } from "../libraries/Hashing.sol";
+
 contract Hashing_hashDepositSource_Test is CommonTest {
-    /**
-     * @notice Tests that hashDepositSource returns the correct hash in a simple case.
-     */
+    /// @notice Tests that hashDepositSource returns the correct hash in a simple case.
     function test_hashDepositSource_succeeds() external {
         assertEq(
             Hashing.hashDepositSource(
@@ -23,9 +26,7 @@ contract Hashing_hashDepositSource_Test is CommonTest {
 }
 
 contract Hashing_hashCrossDomainMessage_Test is CommonTest {
-    /**
-     * @notice Tests that hashCrossDomainMessage returns the correct hash in a simple case.
-     */
+    /// @notice Tests that hashCrossDomainMessage returns the correct hash in a simple case.
     function testDiff_hashCrossDomainMessage_succeeds(
         uint240 _nonce,
         uint16 _version,
@@ -45,9 +46,7 @@ contract Hashing_hashCrossDomainMessage_Test is CommonTest {
         );
     }
 
-    /**
-     * @notice Tests that hashCrossDomainMessageV0 matches the hash of the legacy encoding.
-     */
+    /// @notice Tests that hashCrossDomainMessageV0 matches the hash of the legacy encoding.
     function testFuzz_hashCrossDomainMessageV0_matchesLegacy_succeeds(
         address _target,
         address _sender,
@@ -69,9 +68,7 @@ contract Hashing_hashCrossDomainMessage_Test is CommonTest {
 }
 
 contract Hashing_hashWithdrawal_Test is CommonTest {
-    /**
-     * @notice Tests that hashWithdrawal returns the correct hash in a simple case.
-     */
+    /// @notice Tests that hashWithdrawal returns the correct hash in a simple case.
     function testDiff_hashWithdrawal_succeeds(
         uint256 _nonce,
         address _sender,
@@ -90,9 +87,7 @@ contract Hashing_hashWithdrawal_Test is CommonTest {
 }
 
 contract Hashing_hashOutputRootProof_Test is CommonTest {
-    /**
-     * @notice Tests that hashOutputRootProof returns the correct hash in a simple case.
-     */
+    /// @notice Tests that hashOutputRootProof returns the correct hash in a simple case.
     function testDiff_hashOutputRootProof_succeeds(
         bytes32 _version,
         bytes32 _stateRoot,
@@ -119,9 +114,7 @@ contract Hashing_hashOutputRootProof_Test is CommonTest {
 }
 
 contract Hashing_hashDepositTransaction_Test is CommonTest {
-    /**
-     * @notice Tests that hashDepositTransaction returns the correct hash in a simple case.
-     */
+    /// @notice Tests that hashDepositTransaction returns the correct hash in a simple case.
     function testDiff_hashDepositTransaction_succeeds(
         address _from,
         address _to,

packages/contracts-bedrock/contracts/test/SafeCall.t.sol

 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.15;
 
+// Testing utilities
 import { CommonTest } from "./CommonTest.t.sol";
+
+// Target contract
 import { SafeCall } from "../libraries/SafeCall.sol";
 
 contract SafeCall_Test is CommonTest {
+    /// @dev Tests that the `send` function succeeds.
     function testFuzz_send_succeeds(
         address from,
         address to,
@@ -44,6 +48,7 @@ contract SafeCall_Test is CommonTest {
         }
     }
 
+    /// @dev Tests that `call` succeeds.
     function testFuzz_call_succeeds(
         address from,
         address to,
@@ -84,6 +89,7 @@ contract SafeCall_Test is CommonTest {
         }
     }
 
+    /// @dev Tests that `callWithMinGas` succeeds with enough gas.
     function testFuzz_callWithMinGas_hasEnough_succeeds(
         address from,
         address to,
@@ -127,6 +133,7 @@ contract SafeCall_Test is CommonTest {
         }
     }
 
+    /// @dev Tests that `callWithMinGas` succeeds for the lower gas bounds.
     function test_callWithMinGas_noLeakageLow_succeeds() external {
         SimpleSafeCaller caller = new SimpleSafeCaller();
 
@@ -151,6 +158,7 @@ contract SafeCall_Test is CommonTest {
         }
     }
 
+    /// @dev Tests that `callWithMinGas` succeeds on the upper gas bounds.
     function test_callWithMinGas_noLeakageHigh_succeeds() external {
         SimpleSafeCaller caller = new SimpleSafeCaller();