Add documentation

Author: szymon-zadworny

oneapi-rs/src/kernel.rs

@@ -9,6 +9,7 @@
 use bytemuck::Pod;
 use oneapi_rs_sys::{kernel_bundle::ffi, types};
 
+/// A kernel bundle which stores loaded SYCL source code.
 pub struct SourceKernelBundle(pub(crate) cxx::UniquePtr<types::ffi::SourceKernelBundle>);
 
 impl From<cxx::UniquePtr<types::ffi::SourceKernelBundle>> for SourceKernelBundle {
@@ -23,6 +24,7 @@ impl SourceKernelBundle {
     }
 }
 
+/// A kernel bundle which stores compiled SYCL kernels.
 pub struct ExecutableKernelBundle(pub(crate) cxx::UniquePtr<types::ffi::ExecutableKernelBundle>);
 
 impl From<cxx::UniquePtr<types::ffi::ExecutableKernelBundle>> for ExecutableKernelBundle {
@@ -37,6 +39,7 @@ impl ExecutableKernelBundle {
     }
 }
 
+/// An executable SYCL kernel.
 pub struct Kernel(pub(crate) cxx::UniquePtr<types::ffi::Kernel>);
 
 impl From<cxx::UniquePtr<types::ffi::Kernel>> for Kernel {
@@ -45,6 +48,7 @@ impl From<cxx::UniquePtr<types::ffi::Kernel>> for Kernel {
     }
 }
 
+/// Types which can be passed as SYCL kernel arguments.
 pub unsafe trait KernelArgument {
     unsafe fn as_raw_arg(&self) -> &[u8];
 }
@@ -55,6 +59,7 @@ unsafe impl<T: Pod> KernelArgument for T {
     }
 }
 
+/// Types which describe an argument list for a SYCL kernel.
 pub unsafe trait KernelArgumentList<const ARGC: usize> {
     unsafe fn as_raw_arg_list(&self) -> [&[u8]; ARGC];
 }

oneapi-rs/src/queue.rs

@@ -134,6 +134,8 @@ impl Queue {
         ffi::wait(&mut self.0);
     }
 
+    /// Enqueues a kernel object to the queue an an ND-range kernel, using the number of work-items
+    /// specified by the [`NdRange`] nd_range.
     pub unsafe fn launch<const ARGC: usize, const DIMENSIONS: usize>(
         &mut self,
         nd_range: NdRange<DIMENSIONS>,

oneapi-rs/src/range.rs

@@ -14,8 +14,15 @@ use crate::{
     queue::Queue,
 };
 
+/// `Range` is a 1D, 2D or 3D vector that defines the iteration domain of either a single work-group
+/// in a parallel dispatch, or the overall dimensions of the dispatch.
 pub type Range<const DIMENSIONS: usize = 1> = [u64; DIMENSIONS];
 
+/// The `NdRange` struct defines the iteration domain of both the work-groups and the overall
+/// dispatch.
+///
+/// An `NdRange` comprises two [`Range`] parameters: the whole range over which the kernel is to be
+/// executed and the range of each work group.
 pub struct NdRange<const DIMENSIONS: usize = 1> {
     pub group_size: Range<DIMENSIONS>,
     pub local_size: Range<DIMENSIONS>,
@@ -30,6 +37,7 @@ impl<const DIMENSIONS: usize> NdRange<DIMENSIONS> {
     }
 }
 
+/// [`NdRange`] types which are limited to 1, 2 or 3 dimensions.
 pub trait ValidDimension {
     unsafe fn launch<const ARGC: usize>(
         &self,