#34 Added docstring to general.hh

src/lib/cpp/include/general.hh

@@ -1,9 +1,24 @@
-//#define _OPENACC
+/**
+ * @file general.hh
+ * @author Carl-Johannes Johnsen ([email protected])
+ * @brief Generic functions that can be used in a variety of contexts. Mostly parallel implementations of common numpy / scipy functions.
+ * @version 0.1
+ * @date 2024-09-16
+ *
+ * @copyright Copyright (c) 2024
+ */
 #include "datatypes.hh"
 #include "boilerplate.hh"
 
 namespace NS {
 
+    /**
+     * Bincount. Counts the number of occurrences of each value in an array of non-negative integers.
+     * It is assumed that the output is pre-allocated and zeroed.
+     *
+     * @param src The input array containing the non-negative integers.
+     * @param dst The output array containing the counts.
+     */
     inline void bincount(const input_ndarray<uint64_t> &src, output_ndarray<uint64_t> &dst) {
         UNPACK_NUMPY(src);
         UNPACK_NUMPY(dst);
@@ -15,6 +30,14 @@ namespace NS {
         }
     }
 
+    /**
+     * Finds the minimum and maximum values in an array.
+     *
+     * @param in the input array.
+     * @param vmin the reference to where the minimum value should be stored.
+     * @param vmax the reference to where the maximum value should be stored.
+     * @tparam T the internal datatype of the input array.
+     */
     template <typename T>
     inline void min_max(const input_ndarray<T> &in, T &vmin, T &vmax) {
         UNPACK_NUMPY(in);
@@ -26,6 +49,16 @@ namespace NS {
         } BLOCK_END_T();
     }
 
+    /**
+     * Normalized conversion between datatypes. The output will be between the minimum and maximum values that the type `U` can represent.
+     *
+     * @param in the input array.
+     * @param out the output array.
+     * @param vmin the minimum value of the input array.
+     * @param vmax the maximum value of the input array.
+     * @tparam T internal datatype of the input array.
+     * @tparam U internal datatype of the output array.
+     */
     template <typename T, typename U>
     inline void normalized_convert(const input_ndarray<T> &in, output_ndarray<U> &out, const T vmin, const T vmax) {
         UNPACK_NUMPY(in);
@@ -35,6 +68,15 @@ namespace NS {
         } BLOCK_END_WITH_OUTPUT_TU();
     }
 
+    /**
+     * Normalized conversion between datatypes. The output will be between the minimum and maximum values that the type `U` can represent.
+     * This overload differs from the other in that it calculates the minimum and maximum values of the input array.
+     *
+     * @param in the input array.
+     * @param out the output array.
+     * @tparam T the internal datatype of the input array.
+     * @tparam U the internal datatype of the output array.
+     */
     template <typename T, typename U>
     inline void normalized_convert(const input_ndarray<T> &in, output_ndarray<U> &out) {
         T vmin, vmax;
@@ -43,6 +85,14 @@ namespace NS {
     }
 
     // Assumes `allowed` is sorted
+    /**
+     * Filters the input array `src` such that only elements that are in the `allowed` array are kept.
+     * The `allowed` array is assumed to be sorted as it uses a binary search to find the elements.
+     *
+     * @param src the input array.
+     * @param allowed the array containing the allowed values.
+     * @tparam T The internal datatype of the arrays.
+     */
     template <typename T>
     inline void where_in(output_ndarray<T> &src, const input_ndarray<T> &allowed) {
         UNPACK_NUMPY(src);