This is an automated email from the ASF dual-hosted git repository.
kszucs pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new dc4e3ee ARROW-4245: [Rust] Add Rustdoc header to source files
dc4e3ee is described below
commit dc4e3eece25135243b959372ce2494ec0eee9eda
Author: Paul Kernfeld <[email protected]>
AuthorDate: Thu Jan 24 16:04:39 2019 +0100
ARROW-4245: [Rust] Add Rustdoc header to source files
This commit adds a short description of each module
Author: Paul Kernfeld <[email protected]>
Closes #3448 from paulkernfeld/arrow-4245-add-rustdoc-headers and squashes
the following commits:
9b8cc7fc <Paul Kernfeld> Fix flaky test, improve rustdocs
32258397 <Paul Kernfeld> Summarize each module
32d73dfd <Paul Kernfeld> Remove example from arrow lib.rs
1d95b034 <Paul Kernfeld> ARROW-4245: Add Rustdoc header to source files
---
rust/arrow/src/array.rs | 32 +++++++++++++++++++++++++++++++-
rust/arrow/src/array_data.rs | 3 +++
rust/arrow/src/array_ops.rs | 2 +-
rust/arrow/src/bitmap.rs | 3 +++
rust/arrow/src/buffer.rs | 4 ++++
rust/arrow/src/csv/mod.rs | 2 ++
rust/arrow/src/error.rs | 2 ++
rust/arrow/src/lib.rs | 6 ++++++
rust/arrow/src/memory.rs | 2 ++
rust/arrow/src/record_batch.rs | 6 ++++++
rust/arrow/src/tensor.rs | 4 +++-
rust/arrow/src/util/bit_util.rs | 2 ++
rust/arrow/src/util/test_util.rs | 2 ++
13 files changed, 67 insertions(+), 3 deletions(-)
diff --git a/rust/arrow/src/array.rs b/rust/arrow/src/array.rs
index 78910d5..69207f6 100644
--- a/rust/arrow/src/array.rs
+++ b/rust/arrow/src/array.rs
@@ -15,7 +15,37 @@
// specific language governing permissions and limitations
// under the License.
-///! Array types
+//! Defines public types representing Apache Arrow arrays. Arrow's
specification defines an array as
+//! "a sequence of values with known length all having the same type." For
example, the type
+//! `Int16Array` represents an Apache Arrow array of 16-bit integers.
+//!
+//! ```
+//! extern crate arrow;
+//!
+//! use arrow::array::Int16Array;
+//!
+//! // Create a new builder with a capacity of 100
+//! let mut builder = Int16Array::builder(100);
+//!
+//! // Append a single primitive value
+//! builder.append_value(1).unwrap();
+//!
+//! // Append a null value
+//! builder.append_null().unwrap();
+//!
+//! // Append a slice of primitive values
+//! builder.append_slice(&[2, 3, 4]).unwrap();
+//!
+//! // Build the array
+//! let array = builder.finish();
+//!
+//! assert_eq!(5, array.len(), "The array has 5 values, counting the null
value");
+//!
+//! assert_eq!(2, array.value(2), "Get the value with index 2");
+//!
+//! assert_eq!(array.value_slice(3, 2), &[3, 4], "Get slice of len 2 starting
at idx 3")
+//! ```
+
use std::any::Any;
use std::convert::From;
use std::io::Write;
diff --git a/rust/arrow/src/array_data.rs b/rust/arrow/src/array_data.rs
index 9ea01a4..1c96b51 100644
--- a/rust/arrow/src/array_data.rs
+++ b/rust/arrow/src/array_data.rs
@@ -15,6 +15,9 @@
// specific language governing permissions and limitations
// under the License.
+//! Contains `ArrayData`, a generic representation of Arrow array data which
encapsulates common
+//! attributes and operations for Arrow array.
+
use std::sync::Arc;
use crate::bitmap::Bitmap;
diff --git a/rust/arrow/src/array_ops.rs b/rust/arrow/src/array_ops.rs
index f41740a..b6afdf2 100644
--- a/rust/arrow/src/array_ops.rs
+++ b/rust/arrow/src/array_ops.rs
@@ -15,7 +15,7 @@
// specific language governing permissions and limitations
// under the License.
-//! Defines primitive computations on arrays
+//! Defines primitive computations on arrays, e.g. addition, equality, boolean
logic.
use std::ops::{Add, Div, Mul, Sub};
diff --git a/rust/arrow/src/bitmap.rs b/rust/arrow/src/bitmap.rs
index b5771c2..e8fce3e 100644
--- a/rust/arrow/src/bitmap.rs
+++ b/rust/arrow/src/bitmap.rs
@@ -15,6 +15,9 @@
// specific language governing permissions and limitations
// under the License.
+//! Defines a bitmap, which is used to track which values in an Arrow array
are null. This is called
+//! a "validity bitmap" in the Arrow documentation.
+
use super::buffer::Buffer;
use crate::util::bit_util;
diff --git a/rust/arrow/src/buffer.rs b/rust/arrow/src/buffer.rs
index b9c159f..cde38c4 100644
--- a/rust/arrow/src/buffer.rs
+++ b/rust/arrow/src/buffer.rs
@@ -15,6 +15,10 @@
// specific language governing permissions and limitations
// under the License.
+//! The main type in the module is `Buffer`, a contiguous immutable memory
region of fixed size
+//! aligned at a 64-byte boundary. `MutableBuffer` is like `Buffer`, but it
can be mutated and
+//! grown.
+
use std::cmp;
use std::io::{Error as IoError, ErrorKind, Result as IoResult, Write};
use std::mem;
diff --git a/rust/arrow/src/csv/mod.rs b/rust/arrow/src/csv/mod.rs
index 6521b19..b3deb3f 100644
--- a/rust/arrow/src/csv/mod.rs
+++ b/rust/arrow/src/csv/mod.rs
@@ -15,6 +15,8 @@
// specific language governing permissions and limitations
// under the License.
+//! Transfer data between the Arrow memory format and CSV (comma-separated
values).
+
pub mod reader;
pub use self::reader::Reader;
diff --git a/rust/arrow/src/error.rs b/rust/arrow/src/error.rs
index b75111f..85f8ee3 100644
--- a/rust/arrow/src/error.rs
+++ b/rust/arrow/src/error.rs
@@ -15,10 +15,12 @@
// specific language governing permissions and limitations
// under the License.
+//! Defines `ArrowError` for representing failures in various Arrow operations
use std::error::Error;
use csv as csv_crate;
+/// Many different operations in the `arrow` crate return this error type
#[derive(Debug, Clone, PartialEq)]
pub enum ArrowError {
MemoryError(String),
diff --git a/rust/arrow/src/lib.rs b/rust/arrow/src/lib.rs
index 199159e..0ecd97c 100644
--- a/rust/arrow/src/lib.rs
+++ b/rust/arrow/src/lib.rs
@@ -15,6 +15,12 @@
// specific language governing permissions and limitations
// under the License.
+//! A native Rust implementation of [Apache Arrow](https://arrow.apache.org),
a cross-language
+//! development platform for in-memory data.
+//!
+//! Currently the project is developed and tested against nightly Rust. To
learn more about the
+//! status of Arrow in Rust, see `README.md`.
+
#![feature(type_ascription)]
#![feature(rustc_private)]
#![feature(specialization)]
diff --git a/rust/arrow/src/memory.rs b/rust/arrow/src/memory.rs
index 763cb48..2168d09 100644
--- a/rust/arrow/src/memory.rs
+++ b/rust/arrow/src/memory.rs
@@ -15,6 +15,8 @@
// specific language governing permissions and limitations
// under the License.
+//! Defines memory-related functions, currently mostly to make this library
play nicely with C.
+
use libc;
use std::cmp;
use std::mem;
diff --git a/rust/arrow/src/record_batch.rs b/rust/arrow/src/record_batch.rs
index e6a8e79..59eaf22 100644
--- a/rust/arrow/src/record_batch.rs
+++ b/rust/arrow/src/record_batch.rs
@@ -15,6 +15,12 @@
// specific language governing permissions and limitations
// under the License.
+//! According to the [Arrow Metadata
Specification](https://arrow.apache.org/docs/metadata.html):
+//!
+//! > A record batch is a collection of top-level named, equal length Arrow
arrays (or vectors). If
+//! > one of the arrays contains nested data, its child arrays are not
required to be the same
+//! > length as the top-level arrays.
+
use std::sync::Arc;
use crate::array::*;
diff --git a/rust/arrow/src/tensor.rs b/rust/arrow/src/tensor.rs
index 1703c83..d633e35 100644
--- a/rust/arrow/src/tensor.rs
+++ b/rust/arrow/src/tensor.rs
@@ -15,7 +15,9 @@
// specific language governing permissions and limitations
// under the License.
-//! Arrow Tensor Type
+//! Arrow Tensor Type, defined in
+//!
[`format/Tensor.fbs`](https://github.com/apache/arrow/blob/master/format/Tensor.fbs).
+
use std::marker::PhantomData;
use std::mem;
diff --git a/rust/arrow/src/util/bit_util.rs b/rust/arrow/src/util/bit_util.rs
index 3f7f4cb..953fea3 100644
--- a/rust/arrow/src/util/bit_util.rs
+++ b/rust/arrow/src/util/bit_util.rs
@@ -15,6 +15,8 @@
// specific language governing permissions and limitations
// under the License.
+//! Utils for working with bits
+
static BIT_MASK: [u8; 8] = [1, 2, 4, 8, 16, 32, 64, 128];
static POPCOUNT_TABLE: [u8; 256] = [
diff --git a/rust/arrow/src/util/test_util.rs b/rust/arrow/src/util/test_util.rs
index 4ef48e6..5d0e7b9 100644
--- a/rust/arrow/src/util/test_util.rs
+++ b/rust/arrow/src/util/test_util.rs
@@ -15,6 +15,8 @@
// specific language governing permissions and limitations
// under the License.
+//! Utils to make testing easier
+
use rand::{thread_rng, Rng};
/// Returns a vector of size `n`, filled with randomly generated bytes.
