Merge pull request #40 from 9prady9/docs_content

Docs content

Author: 9prady9

src/algorithm/mod.rs

@@ -49,6 +49,16 @@ extern {
 
 macro_rules! dim_reduce_func_def {
     ($fn_name: ident, $ffi_name: ident) => (
+        /// Reduction operation along specific dimension
+        ///
+        /// # Parameters
+        ///
+        /// - `input` - Input Array
+        /// - `dim` - Dimension along which the input Array will be reduced
+        ///
+        /// # Return Values
+        ///
+        /// Reduced Array
         #[allow(unused_mut)]
         pub fn $fn_name(input: &Array, dim: i32) -> Result<Array, AfError> {
             unsafe {
@@ -95,6 +105,16 @@ dim_reduce_func_def!(diff2, af_diff2);
 
 macro_rules! all_reduce_func_def {
     ($fn_name: ident, $ffi_name: ident) => (
+        /// Reduction operation of all values
+        ///
+        /// # Parameters
+        ///
+        /// `input` - Input Array
+        ///
+        /// # Return Values
+        ///
+        /// A tuple of reduction result. For non-complex data type Arrays, second value of tuple is
+        /// zero.
         #[allow(unused_mut)]
         pub fn $fn_name(input: &Array) -> Result<(f64, f64), AfError> {
             unsafe {
@@ -141,6 +161,18 @@ all_reduce_func_def!(count_all, af_count_all);
 
 macro_rules! dim_ireduce_func_def {
     ($fn_name: ident, $ffi_name: ident) => (
+        /// Reduction operation along specific dimension
+        ///
+        /// # Parameters
+        ///
+        /// - `input` - Input Array
+        /// - `dim` - Dimension along which the input Array will be reduced
+        ///
+        /// # Return Values
+        ///
+        /// A tuple of Arrays: Reduced Array and Indices Array.
+        ///
+        /// The indices Array has the index of the result element along the reduction dimension.
         #[allow(unused_mut)]
         pub fn $fn_name(input: &Array, dim: i32) -> Result<(Array, Array), AfError> {
             unsafe {
@@ -162,6 +194,19 @@ dim_ireduce_func_def!(imax, af_imax);
 
 macro_rules! all_ireduce_func_def {
     ($fn_name: ident, $ffi_name: ident) => (
+        /// Reduction operation of all values
+        ///
+        /// # Parameters
+        ///
+        /// `input` - Input Array
+        ///
+        /// # Return Values
+        ///
+        /// A triplet of reduction result.
+        ///
+        /// The second value of the tuple is zero for non-complex data type Arrays.
+        ///
+        /// The third value of triplet is the index of result element from reduction operation.
         #[allow(unused_mut)]
         pub fn $fn_name(input: &Array) -> Result<(f64, f64, u32), AfError> {
             unsafe {
@@ -182,6 +227,17 @@ macro_rules! all_ireduce_func_def {
 all_ireduce_func_def!(imin_all, af_imin_all);
 all_ireduce_func_def!(imax_all, af_imax_all);
 
+/// Locate the indices of non-zero elements.
+///
+/// The locations are provided by flattening the input into a linear array.
+///
+/// # Parameters
+///
+/// - `input` - Input Array
+///
+/// # Return Values
+///
+/// Array of indices where the input Array has non-zero values.
 #[allow(unused_mut)]
 pub fn locate(input: &Array) -> Result<Array, AfError> {
     unsafe {
@@ -194,6 +250,19 @@ pub fn locate(input: &Array) -> Result<Array, AfError> {
     }
 }
 
+/// Sort the values in input Arrays
+///
+/// Sort an multidimensional Array along a given dimension
+///
+/// # Parameters
+///
+/// - `input` - Input Array
+/// - `dim` - Dimension along which to sort
+/// - `ascending` - Sorted output will have ascending values if ```True``` and descending order otherwise.
+///
+/// # Return Values
+///
+/// Sorted Array.
 #[allow(unused_mut)]
 pub fn sort(input: &Array, dim: u32, ascending: bool) -> Result<Array, AfError> {
     unsafe {
@@ -207,6 +276,21 @@ pub fn sort(input: &Array, dim: u32, ascending: bool) -> Result<Array, AfError>
     }
 }
 
+/// Sort the values in input Arrays
+///
+/// # Parameters
+///
+/// - `input` - Input Array
+/// - `dim` - Dimension along which to sort
+/// - `ascending` - Sorted output will have ascending values if ```True``` and descending order otherwise.
+///
+/// # Return Values
+///
+/// A tuple of Arrays.
+///
+/// The first Array contains the keys based on sorted values.
+///
+/// The second Array contains the original indices of the sorted values.
 #[allow(unused_mut)]
 pub fn sort_index(input: &Array, dim: u32, ascending: bool) -> Result<(Array, Array), AfError> {
     unsafe {
@@ -222,6 +306,24 @@ pub fn sort_index(input: &Array, dim: u32, ascending: bool) -> Result<(Array, Ar
     }
 }
 
+/// Sort the values in input Arrays
+///
+/// Sort an multidimensional Array based on keys
+///
+/// # Parameters
+///
+/// - `keys` - Array with key values
+/// - `vals` - Array with input values
+/// - `dim` - Dimension along which to sort
+/// - `ascending` - Sorted output will have ascending values if ```True``` and descending order otherwise.
+///
+/// # Return Values
+///
+/// A tuple of Arrays.
+///
+/// The first Array contains the keys based on sorted values.
+///
+/// The second Array contains the sorted values.
 #[allow(unused_mut)]
 pub fn sort_by_key(keys: &Array, vals: &Array, dim: u32,
                    ascending: bool) -> Result<(Array, Array), AfError> {
@@ -238,6 +340,16 @@ pub fn sort_by_key(keys: &Array, vals: &Array, dim: u32,
     }
 }
 
+/// Find unique values from a Set
+///
+/// # Parameters
+///
+/// - `input` - Input Array
+/// - `is_sorted` - is a boolean variable. If ```True`` indicates, the `input` Array is sorted.
+///
+/// # Return Values
+///
+/// An Array of unique values from the input Array.
 #[allow(unused_mut)]
 pub fn set_unique(input: &Array, is_sorted: bool) -> Result<Array, AfError> {
     unsafe {
@@ -251,6 +363,17 @@ pub fn set_unique(input: &Array, is_sorted: bool) -> Result<Array, AfError> {
     }
 }
 
+/// Find union of two sets
+///
+/// # Parameters
+///
+/// - `first` is one of the input sets
+/// - `second` is the other of the input sets
+/// - `is_unique` is a boolean value indicates if the input sets are unique
+///
+/// # Return Values
+///
+/// An Array with union of the input sets
 #[allow(unused_mut)]
 pub fn set_union(first: &Array, second: &Array, is_unique: bool) -> Result<Array, AfError> {
     unsafe {
@@ -264,6 +387,17 @@ pub fn set_union(first: &Array, second: &Array, is_unique: bool) -> Result<Array
     }
 }
 
+/// Find intersection of two sets
+///
+/// # Parameters
+///
+/// - `first` is one of the input sets
+/// - `second` is the other of the input sets
+/// - `is_unique` is a boolean value indicates if the input sets are unique
+///
+/// # Return Values
+///
+/// An Array with intersection of the input sets
 #[allow(unused_mut)]
 pub fn set_intersect(first: &Array, second: &Array, is_unique: bool) -> Result<Array, AfError> {
     unsafe {

src/arith/mod.rs

@@ -94,6 +94,7 @@ extern {
     fn af_isnan(out: MutAfArray, arr: AfArray) -> c_int;
 }
 
+/// Enables use of `!` on objects of type [Array](./struct.Array.html)
 impl<'f> Not for &'f Array {
     type Output = Array;
 

src/array.rs

@@ -64,12 +64,16 @@ extern {
     fn af_print_array(arr: AfArray) -> c_int;
 }
 
+/// A multidimensional data container
+///
+/// Currently, Array objects can store only data until four dimensions
 pub struct Array {
     handle: i64,
 }
 
 macro_rules! is_func {
     ($fn_name: ident, $ffi_fn: ident) => (
+        /// Checks if the Array is of specific format/data type.
         pub fn $fn_name(&self) -> Result<bool, AfError> {
             unsafe {
                 let mut ret_val: i32 = 0;
@@ -84,6 +88,14 @@ macro_rules! is_func {
 }
 
 impl Array {
+    /// Constructs a new Array object
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let values: &[f32] = &[1.0, 2.0, 3.0];
+    /// let indices = Array::new(Dim4::new(&[3, 1, 1, 1]), values, Aftype::F32).unwrap();
+    /// ```
     #[allow(unused_mut)]
     pub fn new<T>(dims: Dim4, slice: &[T], aftype: Aftype) -> Result<Array, AfError> {
         unsafe {
@@ -100,6 +112,7 @@ impl Array {
         }
     }
 
+    /// Returns the number of elements in the Array
     pub fn elements(&self) -> Result<i64, AfError> {
         unsafe {
             let mut ret_val: i64 = 0;
@@ -111,6 +124,7 @@ impl Array {
         }
     }
 
+    /// Returns the Array data type
     pub fn get_type(&self) -> Result<Aftype, AfError> {
         unsafe {
             let mut ret_val: u8 = 0;
@@ -122,6 +136,7 @@ impl Array {
         }
     }
 
+    /// Returns the dimensions of the Array
     pub fn dims(&self) -> Result<Dim4, AfError> {
         unsafe {
             let mut ret0: i64 = 0;
@@ -138,6 +153,7 @@ impl Array {
         }
     }
 
+    /// Returns the number of dimensions of the Array
     pub fn numdims(&self) -> Result<u32, AfError> {
         unsafe {
             let mut ret_val: u32 = 0;
@@ -149,10 +165,12 @@ impl Array {
         }
     }
 
+    /// Returns the native FFI handle for Rust object `Array`
     pub fn get(&self) -> i64 {
         self.handle
     }
 
+    /// Copies the data from the Array to the mutable slice `data`
     pub fn host<T>(&self, data: &mut [T]) -> Result<(), AfError> {
         unsafe {
             let ret_val = af_get_data_ptr(data.as_mut_ptr() as *mut c_void, self.handle as AfArray);
@@ -163,6 +181,7 @@ impl Array {
         }
     }
 
+    /// Evaluates any pending lazy expressions that represent the data in the Array object
     pub fn eval(&self) -> Result<(), AfError> {
         unsafe {
             let ret_val = af_eval(self.handle as AfArray);
@@ -173,6 +192,9 @@ impl Array {
         }
     }
 
+    /// Makes an copy of the Array
+    ///
+    /// Internally, this is handled by reference counting
     pub fn copy(&self) -> Result<Array, AfError> {
         unsafe {
             let mut temp: i64 = 0;
@@ -198,12 +220,14 @@ impl Array {
     is_func!(is_bool, af_is_bool);
 }
 
+/// Used for creating Array object from native resource id
 impl From<i64> for Array {
     fn from(t: i64) -> Array {
         Array {handle: t}
     }
 }
 
+/// Used for incrementing the reference count of Array's native resource
 impl Clone for Array {
     fn clone(&self) -> Array {
         unsafe {
@@ -217,6 +241,7 @@ impl Clone for Array {
     }
 }
 
+/// To free resources when Array goes out of scope
 impl Drop for Array {
     fn drop(&mut self) {
         unsafe {
@@ -229,6 +254,29 @@ impl Drop for Array {
     }
 }
 
+/// Print data in the Array
+///
+/// # Examples
+///
+///  ```
+/// println!("Create a 5-by-3 matrix of random floats on the GPU");
+/// let a = match randu(dims, Aftype::F32) {
+///     Ok(value) => value,
+///     Err(error) => panic!("{}", error),
+/// };
+/// print(&a);
+///  ```
+///
+///  The sample output will look like below:
+///
+///  ```
+///  [5 3 1 1]
+///      0.7402     0.4464     0.7762
+///      0.9210     0.6673     0.2948
+///      0.0390     0.1099     0.7140
+///      0.9690     0.4702     0.3585
+///      0.9251     0.5132     0.6814
+///  ```
 pub fn print(input: &Array) -> Result<(), AfError> {
     unsafe {
         let ret_val = af_print_array(input.get() as AfArray);