alamb commented on code in PR #10741:
URL: https://github.com/apache/arrow-rs/pull/10741#discussion_r3806889818
##########
arrow-json/src/writer/mod.rs:
##########
@@ -104,6 +104,14 @@
//! serde_json::json!({"a": 2}),
//! );
//! ```
+//!
+//! ## Customizing the encoder
Review Comment:
this is the core change -- add a note at the top level that says you can
customize the encoder
##########
arrow-json/src/writer/encoder.rs:
##########
@@ -139,10 +139,15 @@ impl EncoderOptions {
}
}
-/// A trait to create custom encoders for specific data types.
+/// Creates custom encoders for specific data types when writing JSON data.
///
-/// This allows overriding the default encoders for specific data types,
-/// or adding new encoders for custom data types.
+/// This trait allows customizing JSON encoding for specific data types,
+/// or adding new encoders for unsupported or custom data types.
+///
+/// You can register an implementation of this trait using
Review Comment:
I am trying to point people / agents to the right APIs
##########
arrow-json/src/lib.rs:
##########
@@ -20,15 +20,20 @@
//! See the module level documentation for the
//! [`reader`] and [`writer`] for usage examples.
//!
-//! # Binary Data uses `Base16` Encoding
+//! # Binary Data Encoding
//!
//! As per [RFC7159] JSON cannot encode arbitrary binary data. This crate
works around that
//! limitation by encoding/decoding binary data as a [hexadecimal] string (i.e.
//! [`Base16` encoding]).
//!
//! Note that `Base16` only has 50% space efficiency (i.e., the encoded data
is twice as large
-//! as the original). If that is an issue, we recommend to convert binary data
to/from a different
-//! encoding format such as `Base64` instead. See the following example for
details.
+//! as the original). If that is an issue, there are two alternatives:
+//!
+//! 1. Provide a custom encoder. See the [Customizing the encoder] section of
the writer documentation.
+//! 2. Convert binary data to/from a different encoding format such as
`Base64` before
+//! writing / after reading, as shown in the following example.
+//!
+//! [Customizing the encoder]: writer#customizing-the-encoder
//!
//! ## `Base64` Encoding Example
Review Comment:
I think we should consider removing the entire Base64 example here as it
would be better to simply use the encoding factory I think
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
