Skip to content

Commit 0a708e5

Browse files
authored
chore: add docs, part of #37 (apache#6424)
* chore: add docs, part of #37 - add pragma `#![warn(missing_docs)]` to `arrow`, `arrow-arith`, `arrow-avro` - add docs to the same to remove lint warnings * chore: add docs, part of #37 - add pragma `#![warn(missing_docs)]` to `arrow-buffer`, `arrow-cast`, `arrow-csv` - add docs to the same to remove lint warnings * chore: update docs, resolve PR comments
1 parent 4683c20 commit 0a708e5

File tree

24 files changed

+143
-30
lines changed

24 files changed

+143
-30
lines changed

arrow-arith/src/bitwise.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515
// specific language governing permissions and limitations
1616
// under the License.
1717

18+
//! Module contains bitwise operations on arrays
19+
1820
use crate::arity::{binary, unary};
1921
use arrow_array::*;
2022
use arrow_buffer::ArrowNativeType;

arrow-arith/src/lib.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717

1818
//! Arrow arithmetic and aggregation kernels
1919
20+
#![warn(missing_docs)]
2021
pub mod aggregate;
2122
#[doc(hidden)] // Kernels to be removed in a future release
2223
pub mod arithmetic;

arrow-array/src/ffi_stream.rs

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -83,17 +83,18 @@ const ENOSYS: i32 = 78;
8383
/// This was created by bindgen
8484
#[repr(C)]
8585
#[derive(Debug)]
86-
#[allow(missing_docs)]
86+
#[allow(non_camel_case_types)]
8787
pub struct FFI_ArrowArrayStream {
88-
pub get_schema: Option<
89-
unsafe extern "C" fn(arg1: *mut FFI_ArrowArrayStream, out: *mut FFI_ArrowSchema) -> c_int,
90-
>,
91-
pub get_next: Option<
92-
unsafe extern "C" fn(arg1: *mut FFI_ArrowArrayStream, out: *mut FFI_ArrowArray) -> c_int,
93-
>,
94-
pub get_last_error:
95-
Option<unsafe extern "C" fn(arg1: *mut FFI_ArrowArrayStream) -> *const c_char>,
96-
pub release: Option<unsafe extern "C" fn(arg1: *mut FFI_ArrowArrayStream)>,
88+
/// C function to get schema from the stream
89+
pub get_schema:
90+
Option<unsafe extern "C" fn(arg1: *mut Self, out: *mut FFI_ArrowSchema) -> c_int>,
91+
/// C function to get next array from the stream
92+
pub get_next: Option<unsafe extern "C" fn(arg1: *mut Self, out: *mut FFI_ArrowArray) -> c_int>,
93+
/// C function to get the error from last operation on the stream
94+
pub get_last_error: Option<unsafe extern "C" fn(arg1: *mut Self) -> *const c_char>,
95+
/// C function to release the stream
96+
pub release: Option<unsafe extern "C" fn(arg1: *mut Self)>,
97+
/// Private data used by the stream
9798
pub private_data: *mut c_void,
9899
}
99100

arrow-avro/src/lib.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
//! [Apache Arrow]: https://arrow.apache.org
2121
//! [Apache Avro]: https://avro.apache.org/
2222
23+
#![warn(missing_docs)]
2324
#![allow(unused)] // Temporary
2425

2526
pub mod reader;

arrow-buffer/src/bigint/mod.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,7 @@ impl i256 {
216216
}
217217
}
218218

219+
/// Create an `i256` value from a 128-bit value.
219220
pub const fn from_i128(v: i128) -> Self {
220221
Self::from_parts(v as u128, v >> 127)
221222
}

arrow-buffer/src/builder/null.rs

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,7 @@ impl NullBufferBuilder {
159159
}
160160
}
161161

162+
/// Return a mutable reference to the inner bitmap slice.
162163
pub fn as_slice_mut(&mut self) -> Option<&mut [u8]> {
163164
self.bitmap_builder.as_mut().map(|b| b.as_slice_mut())
164165
}
@@ -173,14 +174,12 @@ impl NullBufferBuilder {
173174
}
174175

175176
impl NullBufferBuilder {
177+
/// Return the number of bits in the buffer.
176178
pub fn len(&self) -> usize {
177-
if let Some(b) = &self.bitmap_builder {
178-
b.len()
179-
} else {
180-
self.len
181-
}
179+
self.bitmap_builder.as_ref().map_or(self.len, |b| b.len())
182180
}
183181

182+
/// Check if the builder is empty.
184183
pub fn is_empty(&self) -> bool {
185184
self.len() == 0
186185
}

arrow-buffer/src/builder/offset.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,13 @@ use std::ops::Deref;
1919

2020
use crate::{ArrowNativeType, OffsetBuffer};
2121

22+
/// Builder of [`OffsetBuffer`]
2223
#[derive(Debug)]
2324
pub struct OffsetBufferBuilder<O: ArrowNativeType> {
2425
offsets: Vec<O>,
2526
last_offset: usize,
2627
}
2728

28-
/// Builder of [`OffsetBuffer`]
2929
impl<O: ArrowNativeType> OffsetBufferBuilder<O> {
3030
/// Create a new builder with space for `capacity + 1` offsets
3131
pub fn new(capacity: usize) -> Self {

arrow-buffer/src/interval.rs

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,8 +68,11 @@ use std::ops::Neg;
6868
#[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd)]
6969
#[repr(C)]
7070
pub struct IntervalMonthDayNano {
71+
/// Number of months
7172
pub months: i32,
73+
/// Number of days
7274
pub days: i32,
75+
/// Number of nanoseconds
7376
pub nanoseconds: i64,
7477
}
7578

@@ -345,7 +348,9 @@ derive_arith!(
345348
#[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd)]
346349
#[repr(C)]
347350
pub struct IntervalDayTime {
351+
/// Number of days
348352
pub days: i32,
353+
/// Number of milliseconds
349354
pub milliseconds: i32,
350355
}
351356

arrow-buffer/src/lib.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
2020
// used by [`buffer::mutable::dangling_ptr`]
2121
#![cfg_attr(miri, feature(strict_provenance))]
22+
#![warn(missing_docs)]
2223

2324
pub mod alloc;
2425
pub mod buffer;

arrow-buffer/src/util/bit_chunk_iterator.rs

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,26 +131,32 @@ impl<'a> UnalignedBitChunk<'a> {
131131
}
132132
}
133133

134+
/// Returns the number of leading padding bits
134135
pub fn lead_padding(&self) -> usize {
135136
self.lead_padding
136137
}
137138

139+
/// Returns the number of trailing padding bits
138140
pub fn trailing_padding(&self) -> usize {
139141
self.trailing_padding
140142
}
141143

144+
/// Returns the prefix, if any
142145
pub fn prefix(&self) -> Option<u64> {
143146
self.prefix
144147
}
145148

149+
/// Returns the suffix, if any
146150
pub fn suffix(&self) -> Option<u64> {
147151
self.suffix
148152
}
149153

154+
/// Returns reference to the chunks
150155
pub fn chunks(&self) -> &'a [u64] {
151156
self.chunks
152157
}
153158

159+
/// Returns an iterator over the chunks
154160
pub fn iter(&self) -> UnalignedBitChunkIterator<'a> {
155161
self.prefix
156162
.into_iter()
@@ -164,6 +170,7 @@ impl<'a> UnalignedBitChunk<'a> {
164170
}
165171
}
166172

173+
/// Iterator over an [`UnalignedBitChunk`]
167174
pub type UnalignedBitChunkIterator<'a> = std::iter::Chain<
168175
std::iter::Chain<std::option::IntoIter<u64>, std::iter::Cloned<std::slice::Iter<'a, u64>>>,
169176
std::option::IntoIter<u64>,
@@ -212,6 +219,7 @@ pub struct BitChunks<'a> {
212219
}
213220

214221
impl<'a> BitChunks<'a> {
222+
/// Create a new [`BitChunks`] from a byte array, and an offset and length in bits
215223
pub fn new(buffer: &'a [u8], offset: usize, len: usize) -> Self {
216224
assert!(ceil(offset + len, 8) <= buffer.len() * 8);
217225

@@ -232,6 +240,7 @@ impl<'a> BitChunks<'a> {
232240
}
233241
}
234242

243+
/// Iterator over chunks of 64 bits represented as an u64
235244
#[derive(Debug)]
236245
pub struct BitChunkIterator<'a> {
237246
buffer: &'a [u8],

0 commit comments

Comments
 (0)