Document Morton.h file and its functions, adding detailed descriptions and parameters

Author: Q-Minh

source/pbat/geometry/Morton.h

@@ -1,3 +1,13 @@
+/**
+ * @file Morton.h
+ * @author Quoc-Minh Ton-That ([email protected])
+ * @brief This file contains functions to compute Morton codes.
+ * @date 2025-02-12
+ *
+ * @copyright Copyright (c) 2025
+ *
+ */
+
 #ifndef PBAT_GEOMETRY_MORTON_H
 #define PBAT_GEOMETRY_MORTON_H
 
@@ -11,14 +21,17 @@
 namespace pbat {
 namespace geometry {
 
-using MortonCodeType = std::uint32_t;
-
-// NOTE:
-// We make these (otherwise non-templated) functions inline so that they
-// are compiled by nvcc whenever this header is included in cuda sources.
+using MortonCodeType = std::uint32_t; ///< Type used to represent Morton codes
 
-// Expands a 10-bit integer into 30 bits
-// by inserting 2 zeros after each bit.
+/**
+ * @brief Expands a 10-bit integer into 30 bits by inserting 2 zeros after each bit.
+ *
+ * @note We make this (otherwise non-templated) function inline so that it gets compiled by nvcc
+ * whenever this header is included in cuda sources.
+ *
+ * @param v 10-bit integer
+ * @return Expanded 30-bit integer
+ */
 PBAT_HOST_DEVICE inline MortonCodeType ExpandBits(MortonCodeType v)
 {
     v = (v * 0x00010001u) & 0xFF0000FFu;
@@ -28,13 +41,32 @@ PBAT_HOST_DEVICE inline MortonCodeType ExpandBits(MortonCodeType v)
     return v;
 }
 
-// Calculates a 30-bit Morton code for the
-// given 3D point located within the unit cube [0,1].
+namespace detail {
+
 template <class Point>
-requires std::is_convertible_v<
-    decltype(std::declval<Point>()[std::declval<int>()]),
-    float> [[maybe_unused]] PBAT_HOST_DEVICE inline MortonCodeType
-Morton3D(Point x)
+concept CMorton3dPoint = requires(Point p)
+{
+    {
+        p[0]
+    } -> std::convertible_to<float>;
+    {
+        p[1]
+    } -> std::convertible_to<float>;
+    {
+        p[2]
+    } -> std::convertible_to<float>;
+};
+
+} // namespace detail
+
+/**
+ * @brief Calculates a 30-bit Morton code for the given 3D point located within the unit cube [0,1].
+ * @tparam Point Type of the point
+ * @param x 3D point located within the unit cube [0,1]
+ * @return Morton code of x
+ */
+template <detail::CMorton3dPoint Point>
+[[maybe_unused]] PBAT_HOST_DEVICE inline MortonCodeType Morton3D(Point x)
 {
     using namespace std;
     MortonCodeType xx =