doc: new functions in rlp package

core/types/rlp_backwards_compat.libevm_test.go

@@ -175,7 +175,7 @@ func testBodyRLPBackwardsCompatibility(t *testing.T, seed uint64) {
 			body.Withdrawals = tt.withdrawals
 
 			// The original [Body] doesn't implement [rlp.Encoder] nor
-			// [rlp.Decoder] so we can use a methodless equivalent as gold
+			// [rlp.Decoder] so we can use a methodless equivalent as the gold
 			// standard.
 			type withoutMethods Body
 			wantRLP, err := rlp.EncodeToBytes((*withoutMethods)(body))

rlp/list.libevm.go

@@ -16,6 +16,9 @@
 
 package rlp
 
+// InList is a convenience wrapper, calling `fn` between calls to
+// [EncoderBuffer.List] and [EncoderBuffer.ListEnd]. If `fn` returns an error,
+// it is propagated directly.
 func (b EncoderBuffer) InList(fn func() error) error {
 	l := b.List()
 	if err := fn(); err != nil {
@@ -25,6 +28,9 @@ func (b EncoderBuffer) InList(fn func() error) error {
 	return nil
 }
 
+// EncodeListToBuffer is equivalent to [Encode], writing the RLP encoding of
+// each element to `b`, except that it wraps the writes inside a call to
+// [EncoderBuffer.InList].
 func EncodeListToBuffer[T any](b EncoderBuffer, vals []T) error {
 	return b.InList(func() error {
 		for _, v := range vals {
@@ -36,6 +42,9 @@ func EncodeListToBuffer[T any](b EncoderBuffer, vals []T) error {
 	})
 }
 
+// FromList is a convenience wrapper, calling `fn` between calls to
+// [Stream.List] and [Stream.ListEnd]. If `fn` returns an error, it is
+// propagated directly.
 func (s *Stream) FromList(fn func() error) error {
 	if _, err := s.List(); err != nil {
 		return err
@@ -46,14 +55,13 @@ func (s *Stream) FromList(fn func() error) error {
 	return s.ListEnd()
 }
 
+// DecodeList assumes that the next item in `s` is a list and decodes every item
+// in said list to a `*T`.
+//
+// The returned slice is guaranteed to be non-nil, even if the list is empty.
+// This is in keeping with other behaviour in this package and it is therefore
+// the responsibility of callers to respect `rlp:"nil"` struct tags.
 func DecodeList[T any](s *Stream) ([]*T, error) {
-	// From the package-level documentation:
-	//
-	// > Note that package rlp never leaves a pointer-type struct field as nil
-	// > unless one of the "nil" struct tags is present.
-	//
-	// We therefore return a non-nil pointer to maintain said invariant as it
-	// makes use of this function easier.
 	vals := make([]*T, 0)
 	err := s.FromList(func() error {
 		for s.MoreDataInList() {