fix and refine docs

Signed-off-by: Bugen Zhao <[email protected]>

src/common/src/types/cow.rs

@@ -18,6 +18,19 @@ use super::{Datum, DatumRef, ToDatumRef, ToOwnedDatum};
 ///
 /// We do not use [`std::borrow::Cow`] because it requires the borrowed variant
 /// to be a reference, whereas what we have is a [`DatumRef`] with a lifetime.
+///
+/// # Usage
+///
+/// Generally, you don't need to match on the variants of `DatumCow` to access
+/// the underlying datum. Instead, you can...
+///
+/// - call [`to_datum_ref`](ToDatumRef::to_datum_ref) to get a borrowed
+///   [`DatumRef`] without any allocation, which can be used to append to an
+///   array builder or to encode into the storage representation,
+///
+/// - call [`to_owned_datum`](ToOwnedDatum::to_owned_datum) to get an owned
+///   [`Datum`] with potentially an allocation, which can be used to store in a
+///   struct without lifetime constraints.
 #[derive(Debug, Clone)]
 pub enum DatumCow<'a> {
     Borrowed(DatumRef<'a>),

src/connector/codec/src/decoder/mod.rs

@@ -56,10 +56,6 @@ pub trait Access {
     /// and we use different `path` to access one column at a time.
     ///
     /// e.g., for Avro, we access `["col_name"]`; for Debezium Avro, we access `["before", "col_name"]`.
-    /// Similar to `access`, but may return a borrowed [`DatumCow::Borrowed`] to avoid unnecessary allocation.
-    /// If not overridden, it will call forward to `access` and always wrap the result in [`DatumCow::Owned`].
-    ///
-    /// This should be preferred over `access` for both callers and implementors.
     ///
     /// # Returns
     ///