style(ctb): clean up RLP lib natspec (#2973)

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

.changeset/lucky-parents-deliver.md

+---
+'@eth-optimism/contracts-bedrock': patch
+---
+
+Add comments to RLP libraries

packages/contracts-bedrock/contracts/libraries/rlp/RLPReader.sol

@@ -2,41 +2,42 @@
 pragma solidity ^0.8.9;
 
 /**
+ * @custom:attribution https://github.com/hamdiallam/Solidity-RLP
  * @title RLPReader
- * @dev Adapted from "RLPReader" by Hamdi Allam (hamdi.allam97@gmail.com).
+ * @notice RLPReader is a library for parsing RLP-encoded byte arrays into Solidity types. Adapted
+ *         from Solidity-RLP (https://github.com/hamdiallam/Solidity-RLP) by Hamdi Allam with
+ *         various tweaks to improve readability.
  */
 library RLPReader {
-    /*************
-     * Constants *
-     *************/
-
+    /**
+     * @notice Max list length that this library will accept.
+     */
     uint256 internal constant MAX_LIST_LENGTH = 32;
 
-    /*********
-     * Enums *
-     *********/
-
+    /**
+     * @notice RLP item types.
+     *
+     * @custom:value DATA_ITEM Represents an RLP data item (NOT a list).
+     * @custom:value LIST_ITEM Represents an RLP list item.
+     */
     enum RLPItemType {
         DATA_ITEM,
         LIST_ITEM
     }
 
-    /***********
-     * Structs *
-     ***********/
-
+    /**
+     * @notice Struct representing an RLP item.
+     */
     struct RLPItem {
         uint256 length;
         uint256 ptr;
     }
 
-    /**********************
-     * Internal Functions *
-     **********************/
-
     /**
-     * Converts bytes to a reference to memory position and length.
+     * @notice Converts bytes to a reference to memory position and length.
+     *
      * @param _in Input bytes to convert.
+     *
      * @return Output memory reference.
      */
     function toRLPItem(bytes memory _in) internal pure returns (RLPItem memory) {
@@ -49,8 +50,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP list value into a list of RLP items.
+     * @notice Reads an RLP list value into a list of RLP items.
+     *
      * @param _in RLP list value.
+     *
      * @return Decoded RLP list items.
      */
     function readList(RLPItem memory _in) internal pure returns (RLPItem[] memory) {
@@ -88,8 +91,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP list value into a list of RLP items.
+     * @notice Reads an RLP list value into a list of RLP items.
+     *
      * @param _in RLP list value.
+     *
      * @return Decoded RLP list items.
      */
     function readList(bytes memory _in) internal pure returns (RLPItem[] memory) {
@@ -97,8 +102,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bytes value into bytes.
+     * @notice Reads an RLP bytes value into bytes.
+     *
      * @param _in RLP bytes value.
+     *
      * @return Decoded bytes.
      */
     function readBytes(RLPItem memory _in) internal pure returns (bytes memory) {
@@ -110,8 +117,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bytes value into bytes.
+     * @notice Reads an RLP bytes value into bytes.
+     *
      * @param _in RLP bytes value.
+     *
      * @return Decoded bytes.
      */
     function readBytes(bytes memory _in) internal pure returns (bytes memory) {
@@ -119,8 +128,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP string value into a string.
+     * @notice Reads an RLP string value into a string.
+     *
      * @param _in RLP string value.
+     *
      * @return Decoded string.
      */
     function readString(RLPItem memory _in) internal pure returns (string memory) {
@@ -128,8 +139,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP string value into a string.
+     * @notice Reads an RLP string value into a string.
+     *
      * @param _in RLP string value.
+     *
      * @return Decoded string.
      */
     function readString(bytes memory _in) internal pure returns (string memory) {
@@ -137,8 +150,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bytes32 value into a bytes32.
+     * @notice Reads an RLP bytes32 value into a bytes32.
+     *
      * @param _in RLP bytes32 value.
+     *
      * @return Decoded bytes32.
      */
     function readBytes32(RLPItem memory _in) internal pure returns (bytes32) {
@@ -163,8 +178,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bytes32 value into a bytes32.
+     * @notice Reads an RLP bytes32 value into a bytes32.
+     *
      * @param _in RLP bytes32 value.
+     *
      * @return Decoded bytes32.
      */
     function readBytes32(bytes memory _in) internal pure returns (bytes32) {
@@ -172,8 +189,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP uint256 value into a uint256.
+     * @notice Reads an RLP uint256 value into a uint256.
+     *
      * @param _in RLP uint256 value.
+     *
      * @return Decoded uint256.
      */
     function readUint256(RLPItem memory _in) internal pure returns (uint256) {
@@ -181,8 +200,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP uint256 value into a uint256.
+     * @notice Reads an RLP uint256 value into a uint256.
+     *
      * @param _in RLP uint256 value.
+     *
      * @return Decoded uint256.
      */
     function readUint256(bytes memory _in) internal pure returns (uint256) {
@@ -190,8 +211,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bool value into a bool.
+     * @notice Reads an RLP bool value into a bool.
+     *
      * @param _in RLP bool value.
+     *
      * @return Decoded bool.
      */
     function readBool(RLPItem memory _in) internal pure returns (bool) {
@@ -209,8 +232,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bool value into a bool.
+     * @notice Reads an RLP bool value into a bool.
+     *
      * @param _in RLP bool value.
+     *
      * @return Decoded bool.
      */
     function readBool(bytes memory _in) internal pure returns (bool) {
@@ -218,8 +243,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP address value into a address.
+     * @notice Reads an RLP address value into a address.
+     *
      * @param _in RLP address value.
+     *
      * @return Decoded address.
      */
     function readAddress(RLPItem memory _in) internal pure returns (address) {
@@ -233,8 +260,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP address value into a address.
+     * @notice Reads an RLP address value into a address.
+     *
      * @param _in RLP address value.
+     *
      * @return Decoded address.
      */
     function readAddress(bytes memory _in) internal pure returns (address) {
@@ -242,8 +271,10 @@ library RLPReader {
     }
 
     /**
-     * Reads the raw bytes of an RLP item.
+     * @notice Reads the raw bytes of an RLP item.
+     *
      * @param _in RLP item to read.
+     *
      * @return Raw RLP bytes.
      */
     function readRawBytes(RLPItem memory _in) internal pure returns (bytes memory) {
@@ -255,8 +286,10 @@ library RLPReader {
      *********************/
 
     /**
-     * Decodes the length of an RLP item.
+     * @notice Decodes the length of an RLP item.
+     *
      * @param _in RLP item to decode.
+     *
      * @return Offset of the encoded data.
      * @return Length of the encoded data.
      * @return RLP item type (LIST_ITEM or DATA_ITEM).
@@ -333,10 +366,12 @@ library RLPReader {
     }
 
     /**
-     * Copies the bytes from a memory location.
-     * @param _src Pointer to the location to read from.
+     * @notice Copies the bytes from a memory location.
+     *
+     * @param _src    Pointer to the location to read from.
      * @param _offset Offset to start reading from.
      * @param _length Number of bytes to read.
+     *
      * @return Copied bytes.
      */
     function _copy(
@@ -378,8 +413,10 @@ library RLPReader {
     }
 
     /**
-     * Copies an RLP item into bytes.
+     * @notice Copies an RLP item into bytes.
+     *
      * @param _in RLP item to copy.
+     *
      * @return Copied bytes.
      */
     function _copy(RLPItem memory _in) private pure returns (bytes memory) {

packages/contracts-bedrock/contracts/libraries/rlp/RLPWriter.sol

@@ -2,17 +2,18 @@
 pragma solidity ^0.8.9;
 
 /**
+ * @custom:attribution https://github.com/bakaoh/solidity-rlp-encode
  * @title RLPWriter
- * @author Bakaoh (with modifications)
+ * @author RLPWriter is a library for encoding Solidity types to RLP bytes. Adapted from Bakaoh's
+ *         RLPEncode library (https://github.com/bakaoh/solidity-rlp-encode) with minor
+ *         modifications to improve legibility.
  */
 library RLPWriter {
-    /**********************
-     * Internal Functions *
-     **********************/
-
     /**
-     * RLP encodes a byte string.
+     * @notice RLP encodes a byte string.
+     *
      * @param _in The byte string to encode.
+     *
      * @return The RLP encoded string in bytes.
      */
     function writeBytes(bytes memory _in) internal pure returns (bytes memory) {
@@ -28,8 +29,10 @@ library RLPWriter {
     }
 
     /**
-     * RLP encodes a list of RLP encoded byte byte strings.
+     * @notice RLP encodes a list of RLP encoded byte byte strings.
+     *
      * @param _in The list of RLP encoded byte strings.
+     *
      * @return The RLP encoded list of items in bytes.
      */
     function writeList(bytes[] memory _in) internal pure returns (bytes memory) {
@@ -38,8 +41,10 @@ library RLPWriter {
     }
 
     /**
-     * RLP encodes a string.
+     * @notice RLP encodes a string.
+     *
      * @param _in The string to encode.
+     *
      * @return The RLP encoded string in bytes.
      */
     function writeString(string memory _in) internal pure returns (bytes memory) {
@@ -47,8 +52,10 @@ library RLPWriter {
     }
 
     /**
-     * RLP encodes an address.
+     * @notice RLP encodes an address.
+     *
      * @param _in The address to encode.
+     *
      * @return The RLP encoded address in bytes.
      */
     function writeAddress(address _in) internal pure returns (bytes memory) {
@@ -56,8 +63,10 @@ library RLPWriter {
     }
 
     /**
-     * RLP encodes a uint.
+     * @notice RLP encodes a uint.
+     *
      * @param _in The uint256 to encode.
+     *
      * @return The RLP encoded uint256 in bytes.
      */
     function writeUint(uint256 _in) internal pure returns (bytes memory) {
@@ -65,8 +74,10 @@ library RLPWriter {
     }
 
     /**
-     * RLP encodes a bool.
+     * @notice RLP encodes a bool.
+     *
      * @param _in The bool to encode.
+     *
      * @return The RLP encoded bool in bytes.
      */
     function writeBool(bool _in) internal pure returns (bytes memory) {
@@ -75,14 +86,12 @@ library RLPWriter {
         return encoded;
     }
 
-    /*********************
-     * Private Functions *
-     *********************/
-
     /**
-     * Encode the first byte, followed by the `len` in binary form if `length` is more than 55.
-     * @param _len The length of the string or the payload.
+     * @notice Encode the first byte and then the `len` in binary form if `length` is more than 55.
+     *
+     * @param _len    The length of the string or the payload.
      * @param _offset 128 if item is string, 192 if item is list.
+     *
      * @return RLP encoded bytes.
      */
     function _writeLength(uint256 _len, uint256 _offset) private pure returns (bytes memory) {
@@ -110,9 +119,10 @@ library RLPWriter {
     }
 
     /**
-     * Encode integer in big endian binary form with no leading zeroes.
-     * @notice TODO: This should be optimized with assembly to save gas costs.
+     * @notice Encode integer in big endian binary form with no leading zeroes.
+     *
      * @param _x The integer to encode.
+     *
      * @return RLP encoded bytes.
      */
     function _toBinary(uint256 _x) private pure returns (bytes memory) {
@@ -134,11 +144,12 @@ library RLPWriter {
     }
 
     /**
-     * Copies a piece of memory to another location.
-     * @notice From: https://github.com/Arachnid/solidity-stringutils/blob/master/src/strings.sol.
+     * @custom:attribution https://github.com/Arachnid/solidity-stringutils
+     * @notice Copies a piece of memory to another location.
+     *
      * @param _dest Destination location.
-     * @param _src Source location.
-     * @param _len Length of memory to copy.
+     * @param _src  Source location.
+     * @param _len  Length of memory to copy.
      */
     function _memcpy(
         uint256 _dest,
@@ -169,9 +180,11 @@ library RLPWriter {
     }
 
     /**
-     * Flattens a list of byte strings into one byte string.
-     * @notice From: https://github.com/sammayo/solidity-rlp-encoder/blob/master/RLPEncode.sol.
+     * @custom:attribution https://github.com/sammayo/solidity-rlp-encoder
+     * @notice Flattens a list of byte strings into one byte string.
+     *
      * @param _list List of byte strings to flatten.
+     *
      * @return The flattened byte string.
      */
     function _flatten(bytes[] memory _list) private pure returns (bytes memory) {