ARROW-10044: [Rust] Improved Arrow's README.
Closes #8224 from jorgecarleitao/readme_arrow
Authored-by: Jorge C. Leitao <jorgecarleitao@gmail.com>
Signed-off-by: Neville Dipale <nevilledips@gmail.com>
diff --git a/rust/arrow/README.md b/rust/arrow/README.md
index a7e668c..fc90fe9 100644
--- a/rust/arrow/README.md
+++ b/rust/arrow/README.md
@@ -21,10 +21,62 @@
[](https://coveralls.io/github/apache/arrow)
+This crate contains a native Rust implementation of the [Arrow columnar format](https://arrow.apache.org/docs/format/Columnar.html). It uses nightly Rust.
+
+## Developer's guide
+
+Here you can find general information about this crate's content and its organization.
+
+### DataType, Field, Schema and RecordBatch
+
+Every array in Arrow has a data type, that specifies how the data should be layed in memory and casted, and an optional null bitmap, that specifies whether each value is null or not.
+Thus, a central enum of this crate is `arrow::datatypes::DataType`, that contains the set of valid
+DataTypes in the specification. For example, `arrow::datatypes::DataType::Utf8`.
+
+Many (but not all) data types have an associated Rust native type. The trait that represents
+this relationship is `arrow::datatypes::ArrowNativeType`, that most native types implement.
+
+`arrow::datatypes::Field` is a struct that contains an arrays' metadata (datatype and whether its values
+can be null), and a name. `arrow::datatypes::Schema` is a vector of fields with optional metadata.
+
+Finally, `arrow::record_batch::RecordBatch` is a struct with a `Schema` and a vector of `Array`s all with the same `len`. A record batch is the highest order struct that this crate currently offers.
+
+### Array
+
+The central trait of this package is `arrow::array::Array`, a dynamically-typed trait that
+can be downcasted to specific implementations, such as `arrow::array::UInt32Array`.
+
+`Array` has `Array::len()`, `Array::data_type()`, and nullability of each of its entries, that can be obtained via `Array::is_null(index)`. To downcast an `Array` to a specific implementation, you can use
+
+```rust
+let specific_array = array.as_any().downcast_ref<UInt32Array>().unwrap();
+```
+
+Once downcasted, it offers two calls to retrieve specific values (and nullability):
+
+```rust
+let is_null_0: bool = specifcic_array.is_null(0)
+let value_at_0: u32 = specifcic_array.value(0)
+```
+
+### Memory and Buffers
+
+You can access the whole buffer of an `Array` via `Array::data()`, which returns an `arrow::data::ArrayData`. This struct holds the array's `DataType`, `arrow::buffer::Buffer`s, and `childs` (which are themselves `ArrayData`).
+
+The central structs that array implementations use to allocate and refer to memory
+aligned according to the specification are the `arrow::buffer::Buffer` and `arrow::buffer::MutableBuffer`.
+These are the lowest abstractions of this crate, and are used throughout the crate to
+efficiently allocate, write, read and deallocate memory.
+
+This implementation uses a architecture-dependent alignment of sizes that are multiples of 64 bytes.
+
+### Compute
+
+This crate offers many operations (called kernels) to operate on `Array`s, that you can find at `arrow::compute::kernels`.
+
## Status
-This is a native Rust implementation of Apache Arrow. Currently the project
-is developed and tested against nightly Rust. The current status is:
+The current status is:
- [x] Primitive Arrays
- [x] List Arrays
