alamb commented on code in PR #2913: URL: https://github.com/apache/arrow-rs/pull/2913#discussion_r1003662356
########## arrow/src/lib.rs: ########## @@ -21,12 +21,32 @@ //! Please see the [arrow crates.io](https://crates.io/crates/arrow) //! page for feature flags and tips to improve performance. //! +//! # Crate Topology +//! +//! The `arrow` project is implemented as multiple sub-crates, which are then re-exported by +//! this top-level `arrow` crate. +//! +//! Crate authors can choose to depend on this top-level `arrow` crate, or just +//! the sub-crates they need. +//! +//! The current list of sub-crates is: +//! +//! * [`arrow_buffer`] - buffer abstractions for arrow arrays +//! * [`arrow_schema`] - the logical types for arrow arrays +//! * [`arrow_data`] - the underlying data of arrow arrays +//! * [`arrow_array`] - type-safe arrow array abstractions +//! * [`arrow_select`] - selection kernels for arrow arrays Review Comment: Would it also help to mention that some crates, such as `arrow-flight` are meant to be used by themselves (not as an implementation detail of `arrow`)? ########## arrow/src/lib.rs: ########## @@ -21,12 +21,32 @@ //! Please see the [arrow crates.io](https://crates.io/crates/arrow) //! page for feature flags and tips to improve performance. //! +//! # Crate Topology +//! +//! The `arrow` project is implemented as multiple sub-crates, which are then re-exported by +//! this top-level `arrow` crate. +//! +//! Crate authors can choose to depend on this top-level `arrow` crate, or just +//! the sub-crates they need. +//! +//! The current list of sub-crates is: +//! +//! * [`arrow_buffer`] - buffer abstractions for arrow arrays +//! * [`arrow_schema`] - the logical types for arrow arrays +//! * [`arrow_data`] - the underlying data of arrow arrays +//! * [`arrow_array`] - type-safe arrow array abstractions +//! * [`arrow_select`] - selection kernels for arrow arrays +//! +//! _This list is likely to grow as further functionality is split out from the top-level crate_ +//! //! # Columnar Format //! -//! The [`array`] module provides statically typed implementations of all the array -//! types as defined by the [Arrow Columnar Format](https://arrow.apache.org/docs/format/Columnar.html). +//! [`arrow_array`] provides statically typed implementations of all the array types as defined Review Comment: Given I think the above says the subcrates are re-exported as the public API I suggest keeping this example in terms of `arrow` (though updating the links to the arrow-array subcrate would be fine) ########## arrow/src/lib.rs: ########## @@ -21,12 +21,32 @@ //! Please see the [arrow crates.io](https://crates.io/crates/arrow) //! page for feature flags and tips to improve performance. //! +//! # Crate Topology +//! +//! The `arrow` project is implemented as multiple sub-crates, which are then re-exported by +//! this top-level `arrow` crate. +//! +//! Crate authors can choose to depend on this top-level `arrow` crate, or just +//! the sub-crates they need. +//! +//! The current list of sub-crates is: +//! +//! * [`arrow_buffer`] - buffer abstractions for arrow arrays +//! * [`arrow_schema`] - the logical types for arrow arrays +//! * [`arrow_data`] - the underlying data of arrow arrays +//! * [`arrow_array`] - type-safe arrow array abstractions +//! * [`arrow_select`] - selection kernels for arrow arrays Review Comment: I had to alphabetize them to compare with https://github.com/apache/arrow-rs -- so figured it might help others ```suggestion //! * [`arrow_array`] - type-safe arrow array abstractions //! * [`arrow_buffer`] - buffer abstractions for arrow arrays //! * [`arrow_data`] - the underlying data of arrow arrays //! * [`arrow_schema`] - the logical types for arrow arrays //! * [`arrow_select`] - selection kernels for arrow arrays ``` -- 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]
