docs

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>

Author: 0ax1

vortex-cuda/cub/src/scan.rs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
-//! Safe wrappers around CUB DeviceScan operations used by CUDA kernels.
+//! Rust wrappers around CUB DeviceScan operations used by CUDA kernels.
 
 use std::ffi::c_void;
 

vortex-cuda/src/arrow/canonical.rs

@@ -162,19 +162,15 @@ fn export_canonical(
                 export_fixed_size(bits, len, offset, validity_buffer, null_count, ctx)
             }
             Canonical::List(listview) => {
-                // cuDF expects standard Arrow `List`, while Vortex canonical lists are list-views.
-                // Try the CUDA path first, copying host metadata/children to GPU as needed. If a
-                // host list-view hits a GPU implementation gap, rebuild it to `ListArray` on CPU;
-                // `export_list` still exports the rebuilt Arrow layout back to GPU buffers.
+                // cuDF imports standard Arrow `List`, while Vortex canonical lists are list-views.
+                // Try the GPU path first; host list-views can fall back to a CPU rebuild.
                 let is_host = listview.as_ref().is_host();
                 let gpu_err = match export_device_list_view(listview.clone(), ctx).await {
                     Ok(exported) => return Ok(exported),
                     Err(err) => err,
                 };
 
-                // The fallback calls the CPU list-view rebuild, which requires host-resident
-                // buffers. Device-resident fallback would need an explicit D2H materialization
-                // step; until then, preserve the original GPU export error.
+                // CPU rebuild requires host-resident buffers; device-resident arrays keep the GPU error.
                 if !is_host {
                     return Err(gpu_err);
                 }
@@ -328,9 +324,8 @@ pub(super) async fn export_list_layout(
 
 /// Export a Vortex fixed-size-list as Arrow `List`.
 ///
-/// Arrow has a native `FixedSizeList` layout, but cuDF's Arrow Device import currently maps Arrow
-/// `List`/`LargeList` to cuDF `LIST` and rejects `FixedSizeList`. Emit equivalent standard Arrow
-/// `List` offsets so fixed-size-list columns can be consumed by cuDF.
+/// cuDF's Arrow Device import accepts `List`/`LargeList` as cuDF `LIST`, but rejects
+/// `FixedSizeList`, so emit equivalent standard Arrow `List` offsets.
 async fn export_fixed_size_list(
     array: FixedSizeListArray,
     ctx: &mut CudaExecutionCtx,

vortex-cuda/src/arrow/list_view.rs

@@ -35,7 +35,7 @@ use crate::CudaExecutionCtx;
 use crate::cub::exclusive_sum_i32;
 use crate::executor::CudaArrayExt;
 
-/// Export a device-resident Vortex list-view as Arrow `List` without staging offsets on host.
+/// Export a Vortex list-view as Arrow `List` using device kernels.
 ///
 /// Contiguous list-views reuse their child elements. Non-contiguous list-views are rebuilt on GPU
 /// only when the child is primitive and non-nullable/non-null; other child shapes are rejected.
@@ -101,7 +101,7 @@ enum DeviceListViewOffsets {
     RequiresRebuild,
 }
 
-/// Build cuDF-supported `i32` Arrow `List` offsets for a contiguous device-resident list-view.
+/// Build cuDF-supported `i32` Arrow `List` offsets from list-view offset/size device buffers.
 #[expect(clippy::cognitive_complexity)]
 async fn export_device_list_view_offsets(
     offsets_ptype: PType,

vortex-test/e2e-cuda/src/lib.rs

@@ -1,15 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
-//! This file is a simple C-compatible API that is called from the cudf-test-harness at CI time.
-//!
-//! The flow is:
-//!
-//! * test harness calls `dlopen` in this library
-//! * invokes the `export_array` function to get back the device array
-//! * pass the array to `cudf`'s `from_arrow_device`
-//! * convert the loaded table back to Arrow host data for validation
-//! * call `array->release()` to drop the data allocated from the Rust side
+//! C ABI used by `cudf-test-harness` to export and validate Arrow Device data in CI.
 
 #![expect(clippy::expect_used)]
 
@@ -129,7 +121,7 @@ fn fixed_size_list_as_list_array() -> VortexArrayRef {
 }
 
 /// # Safety
-/// called by C++ code.
+/// `schema_ptr` and `array_ptr` must be valid writable pointers.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn export_array(
     schema_ptr: &mut FFI_ArrowSchema,
@@ -207,7 +199,7 @@ fn export_array_inner(schema_ptr: &mut FFI_ArrowSchema, array_ptr: &mut ArrowDev
 }
 
 /// # Safety
-/// called by C++ code.
+/// `ffi_schema` and `ffi_array` must describe a valid Arrow C Data array.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn validate_array(
     ffi_schema: &FFI_ArrowSchema,
@@ -229,7 +221,7 @@ fn ffi_boundary(name: &str, f: impl FnOnce() -> i32) -> i32 {
 }
 
 fn validate_array_inner(ffi_schema: &FFI_ArrowSchema, ffi_array: &mut FFI_ArrowArray) -> i32 {
-    // SAFETY: the provided pointers must not be null, and must point at valid FFI Arrow types.
+    // SAFETY: guaranteed by the C ABI contract.
     let array_data = unsafe {
         let ffi_array = mem::replace(ffi_array, FFI_ArrowArray::empty());
         match from_ffi(ffi_array, ffi_schema) {