[arrow-rs] branch master updated: Improve JSON reader documentation (#1559)

[al...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

alamb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git


The following commit(s) were added to refs/heads/master by this push:
     new d20ebc069 Improve JSON reader documentation (#1559)
d20ebc069 is described below

commit d20ebc069c714876f67be264647b032603c178ad
Author: Andrew Lamb <an...@nerdnetworks.org>
AuthorDate: Wed Apr 13 12:46:53 2022 -0400

    Improve JSON reader documentation (#1559)
    
    * Improve JSON reader documentation
    
    * Apply suggestions from code review
    
    Co-authored-by: Raphael Taylor-Davies <17...@users.noreply.github.com>
    
    Co-authored-by: Raphael Taylor-Davies <17...@users.noreply.github.com>
---
 arrow/src/json/reader.rs | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/arrow/src/json/reader.rs b/arrow/src/json/reader.rs
index 9334e1839..d9ec407ff 100644
--- a/arrow/src/json/reader.rs
+++ b/arrow/src/json/reader.rs
@@ -555,8 +555,11 @@ where
     generate_schema(field_types)
 }
 
-/// JSON values to Arrow record batch decoder. Decoder's next_batch method takes a JSON Value
-/// iterator as input and outputs Arrow record batch.
+/// JSON values to Arrow record batch decoder.
+///
+/// A [`Decoder`] decodes arbitrary streams of [`serde_json::Value`]s and
+/// converts them to [`RecordBatch`]es. To decode JSON formatted files,
+/// see [`Reader`].
 ///
 /// # Examples
 /// ```
@@ -635,8 +638,9 @@ impl DecoderOptions {
 }
 
 impl Decoder {
-    /// Create a new JSON decoder from any value that implements the `Iterator<Item=Result<Value>>`
-    /// trait.
+    /// Create a new JSON decoder from some value that implements an
+    /// iterator over [`serde_json::Value`]s (aka implements the
+    /// `Iterator<Item=Result<Value>>` trait).
     pub fn new(schema: SchemaRef, options: DecoderOptions) -> Self {
         Self { schema, options }
     }
@@ -664,7 +668,10 @@ impl Decoder {
         }
     }
 
-    /// Read the next batch of records
+    /// Read the next batch of [`serde_json::Value`] records from the
+    /// interator into a [`RecordBatch`].
+    ///
+    /// Returns `None` if the input iterator is exhausted.
     pub fn next_batch<I>(&self, value_iter: &mut I) -> Result<Option<RecordBatch>>
     where
         I: Iterator<Item = Result<Value>>,