[GitHub] [arrow-rs] viirya commented on a diff in pull request #4607: Add more docs and examples for ListArray and OffsetsBuffer

["viirya (via GitHub)" <gi...@apache.org>]

viirya commented on code in PR #4607:
URL: https://github.com/apache/arrow-rs/pull/4607#discussion_r1279961487


##########
arrow-array/src/array/list_array.rs:
##########
@@ -54,11 +54,129 @@ impl OffsetSizeTrait for i64 {
     const PREFIX: &'static str = "Large";
 }
 
-/// An array of [variable length arrays](https://arrow.apache.org/docs/format/Columnar.html#variable-size-list-layout)
+/// An array of [variable length lists], similar to JSON arrays
+/// (e.g. `["A", "B", "C"]`).
 ///
-/// See [`ListArray`] and [`LargeListArray`]`
+/// Lists are represented using `offsets` into a `values` child
+/// array. Offsets are stored in two adjacent entries of an
+/// [`OffsetBuffer`].
 ///
-/// See [`GenericListBuilder`](crate::builder::GenericListBuilder) for how to construct a [`GenericListArray`]
+/// Arrow defines [`ListArray`] with `i32` offsets and
+/// [`LargeListArray`]` with `i64` offsets.
+///
+/// Use [`GenericListBuilder`](crate::builder::GenericListBuilder) to
+/// construct a [`GenericListArray`].
+///
+/// # Representation
+///
+/// A [`ListArray`] can represent a list of values of any other
+/// supported Arrow type. Each element of the `ListArray` itself is a
+/// a list which mayb be empty, may contain NULL and non-null values,

Review Comment:
   ```suggestion
   /// a list which maybe empty, may contain NULL and non-null values,
   ```



-- 
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: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org