docs: update RawContentKey and RawContentValue docs (ethereum#1543)

ethportal-api/src/types/content_key/overlay.rs

@@ -10,7 +10,8 @@ use crate::{
 use std::str::FromStr;
 
 /// Types whose values represent keys to lookup content items in an overlay network.
-/// Keys are serializable.
+///
+/// Keys are serializable as "0x" prefixed hex strings.
 pub trait OverlayContentKey:
     TryFrom<RawContentKey, Error = ContentKeyError>
     + Clone
@@ -26,6 +27,10 @@ pub trait OverlayContentKey:
     fn content_id(&self) -> [u8; 32];
 
     /// Returns the bytes of the content key.
+    ///
+    /// The [RawContentKey] is better suited than `Vec<u8>` for representing content key bytes.
+    /// For more details, see [RawContentKey] documentation. If `Vec<u8>` is still desired, one can
+    /// obtain it with: `key.to_bytes().to_vec()`.
     fn to_bytes(&self) -> RawContentKey;
 
     /// Returns the content key as a hex encoded "0x"-prefixed string.

ethportal-api/src/types/content_value/mod.rs

@@ -15,14 +15,20 @@ pub trait ContentValue: Sized {
     type TContentKey: OverlayContentKey;
 
     /// Encodes the content value into a byte vector.
+    ///
+    /// The [RawContentValue] is better suited than `Vec<u8>` for representing content value bytes.
+    /// For more details, see [RawContentValue] documentation. If `Vec<u8>` is still desired, one
+    /// can obtain it with: `value.to_bytes().to_vec()`.
     fn encode(&self) -> RawContentValue;
+
     /// Decodes `buf` into a content value.
     fn decode(key: &Self::TContentKey, buf: &[u8]) -> Result<Self, ContentValueError>;
 
     /// Encodes the content as "0x"-prefixed hex string.
     fn to_hex(&self) -> String {
         hex_encode(self.encode())
     }
+
     /// Decodes the "0x"-prefixed hex string as a content value.
     fn from_hex(key: &Self::TContentKey, data: &str) -> anyhow::Result<Self> {
         Ok(Self::decode(key, &hex_decode(data)?)?)

ethportal-api/src/types/portal.rs

@@ -7,8 +7,43 @@ use crate::{types::enr::Enr, OverlayContentKey};
 use super::query_trace::QueryTrace;
 
 /// The SSZ encoded representation of content key.
+///
+/// This is an alias for [alloy::primitives::Bytes] type, which is a wrapper around [bytes::Bytes].
+///
+/// While `Vec<u8>` is the most common way to represent the byte array, its usage as raw content
+/// key is discouraged in favor of this type, for following reasons:
+///
+/// - The [bytes::Bytes] is cheaply cloneable and sliceable chunk of contiguous memory
+///   - This makes it more suitable when cloning/coping is frequent, and modification is not
+/// - The [alloy::primitives::Bytes] is a wrapper around `bytes::Bytes` that implements frequently
+///   used traits (e.g. [ssz::Encode], [ssz::Decode], [std::fmt::Display], [std::str::FromStr]) and
+///   supports (de)serialization to/from hex strings (with or without "0x" prefix).
+///
+/// Lack of support in third-party libraries is the most common issue with using this type. To work
+/// around it, one can do any of the following:
+///
+/// - Wrap `RawContentKey` in a new type, and implement thirt-party trait that adds support
+/// - Use `RawContentKey::to_vec` and `RawContentKey::from` to convert to/from `Vec<u8>`
 pub type RawContentKey = Bytes;
+
 /// The SSZ encoded representation of content value.
+///
+/// This is an alias for [alloy::primitives::Bytes] type, which is a wrapper around [bytes::Bytes].
+///
+/// While `Vec<u8>` is the most common way to represent the byte array, its usage as raw content
+/// value is discouraged in favor of this type, for following reasons:
+///
+/// - The [bytes::Bytes] is cheaply cloneable and sliceable chunk of contiguous memory
+///   - This makes it more suitable when cloning/coping is frequent, and modification is not
+/// - The [alloy::primitives::Bytes] is a wrapper around `bytes::Bytes` that implements frequently
+///   used traits (e.g. [ssz::Encode], [ssz::Decode], [std::fmt::Display], [std::str::FromStr]) and
+///   supports (de)serialization to/from hex strings (with or without "0x" prefix).
+///
+/// Lack of support in third-party libraries is the most common issue with using this type. To work
+/// around it, one can do any of the following:
+///
+/// - Wrap `RawContentValue` in a new type, and implement thirt-party trait that adds support
+/// - Use `RawContentValue::to_vec` and `RawContentValue::from` to convert to/from `Vec<u8>`
 pub type RawContentValue = Bytes;
 
 pub type DataRadius = U256;