Fix Doxygen warnings in IPPL API comments

AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Repository purpose
+IPPL is a C++ Particle and fields Framework. Preserve physical correctness over stylistic cleanup.
+
+## Build
+- Configure with CMake using the project’s normal toolchain and dependency prefixes.
+- Build in the local build or build_openmp directory.
+- build instructions can be found online.
+- Run the relevant test subset after changes.
+- External dependencies are in the _deps directory fetched with cmake
+
+## External dependencies
+- heFFte and Kokkos are external dependencies.
+- Prefer changing IPPL adapter/wrapper code over patching upstream dependencies.
+- When a change touches parallel kernels, explain execution space, memory space, and data movement implications.
+
+## Physics / numerics rules
+- For algorithmic changes, state expected impact on conservation, stability, and reproducibility.
+- Flag any change that may alter floating-point behavior or MPI/GPU execution order.
+- Add or update at least one regression/sanity test for physics-facing changes.
+- Keep am eye on parallel efficincy at least on the openmp level

scripts/pre-commit

@@ -14,7 +14,16 @@
 # from the .git/hooks directory, so the symlink has to be redirected)
 # ln -s -f ../../scripts/pre-commit .git/hooks/pre-commit
 
-CLANG_FORMAT_VERSION=clang-format-21
+CLANG_FORMAT_VERSION=${CLANG_FORMAT_VERSION:-clang-format-21}
+
+if ! command -v "$CLANG_FORMAT_VERSION" >/dev/null 2>&1; then
+    if command -v clang-format >/dev/null 2>&1; then
+        CLANG_FORMAT_VERSION=clang-format
+    else
+        printf "clang-format executable not found. Install clang-format-21 or set CLANG_FORMAT_VERSION.\n"
+        exit 1
+    fi
+fi
 
 red=$(tput setaf 1)
 green=$(tput setaf 2)
@@ -25,9 +34,33 @@ normal=$(tput sgr0)
 cxx_match="c|cc|cp|cxx|cpp|c\+\+|h|hh|hpp|hxx|h\+\+|ipp|tpp|tcc|txx|inl|inc"
 cmake_match="CMakeLists\.txt|\.cmake"
 
+relative_to_git_prefix() {
+    local path="$1"
+    local prefix="${GIT_PREFIX:-}"
+
+    if [ -n "$prefix" ]; then
+        case "$path" in
+            "$prefix"*) printf "%s\n" "${path#$prefix}" ;;
+            *) printf "%s\n" "$path" ;;
+        esac
+    else
+        printf "%s\n" "$path"
+    fi
+}
+
+clang_assume_filename() {
+    local path="$1"
+
+    case "$path" in
+        *.h) printf "%s.cpp\n" "$path" ;;
+        *) printf "%s\n" "$path" ;;
+    esac
+}
+
 cxxfiles=()
 for file in `git diff --cached --name-only --diff-filter=ACMRT | grep -E "\.(${cxx_match})$"`; do
-    if ! cmp -s <(git show :${file}) <(git show :${file}|$CLANG_FORMAT_VERSION -style=file --assume-filename="${file}"); then
+    assume_filename=$(clang_assume_filename "$file")
+    if ! cmp -s <(git show :${file}) <(git show :${file}|$CLANG_FORMAT_VERSION -style=file --assume-filename="${assume_filename}"); then
         cxxfiles+=("${file}")
     fi
 done
@@ -49,7 +82,7 @@ full_list=
 if [ -n "${cxxfiles}" ]; then
     printf "# ${blue}clang-format ${red}error pre-commit${normal} : To fix run the following (use git commit ${yellow}--no-verify${normal} to bypass)\n"
     for f in "${cxxfiles[@]}" ; do
-        rel=$(realpath --relative-to "./$GIT_PREFIX" "$f")
+        rel=$(relative_to_git_prefix "$f")
         printf "$CLANG_FORMAT_VERSION -style=file -i %s\n" "$rel"
         full_list="${rel} ${full_list}"
     done
@@ -59,7 +92,7 @@ fi
 if [ -n "${cmakefiles}" ]; then
     printf "# ${green}cmake-format ${red}error pre-commit${normal} : To fix run the following (use git commit ${yellow}--no-verify${normal} to bypass)\n"
     for f in "${cmakefiles[@]}" ; do
-        rel=$(realpath --relative-to "./$GIT_PREFIX" "$f")
+        rel=$(relative_to_git_prefix "$f")
         printf "cmake-format -i %s\n" "$rel"
         full_list="${rel} ${full_list}"
     done

src/Communicate/BufferHandler.h

@@ -121,22 +121,22 @@ namespace ippl {
         void freeBuffer(buffer_type buffer) override;
 
         /**
-         * @copydoc BufferHandler::freeBuffer
+         * @copydoc BufferHandler::freeAllBuffers
          */
         void freeAllBuffers() override;
 
         /**
-         * @copydoc BufferHandler::freeBuffer
+         * @copydoc BufferHandler::deleteAllBuffers
          */
         void deleteAllBuffers() override;
 
         /**
-         * @copydoc BufferHandler::freeBuffer
+         * @copydoc BufferHandler::getUsedSize
          */
         size_type getUsedSize() const override;
 
         /**
-         * @copydoc BufferHandler::freeBuffer
+         * @copydoc BufferHandler::getFreeSize
          */
         size_type getFreeSize() const override;
 

src/Communicate/Communicator.cpp

@@ -25,7 +25,7 @@ namespace ippl::mpi {
         return *this;
     }
 
-    Communicator Communicator::Communicator::split(int color, int key) const {
+    Communicator Communicator::split(int color, int key) const {
         MPI_Comm newcomm;
         MPI_Comm_split(*comm_m, color, key, &newcomm);
         return Communicator(newcomm);

src/Communicate/Operations.h

@@ -91,14 +91,9 @@ namespace ippl {
                 constexpr binaryOperationKind opKind = extractBinaryOperationKind<Op>::value;
                 MPI_Op ret;
                 MPI_Op_create(
-                    /**
-                     * @brief Construct a new lambda object without captures, therefore convertible
-                     * to a function pointer
-                     *
-                     * @param inputBuffer pointing to a Type object
-                     * @param outputBuffer pointing to a Type object
-                     * @param len Amount of _Type objects_! NOT amount of bytes!
-                     */
+                    // Captureless lambda, therefore convertible to a function pointer.
+                    // inputBuffer and outputBuffer point to Type objects; len is the number of
+                    // Type objects, not bytes.
                     [](void* inputBuffer, void* outputBuffer, int* len, MPI_Datatype*) {
                         Type* input = (Type*)inputBuffer;
 

src/FEM/Elements/EdgeElement.h

@@ -59,7 +59,8 @@ namespace ippl {
          *
          * @return point_t
          */
-        KOKKOS_FUNCTION point_t globalToLocal(const vertex_points_t&, const point_t&) const;
+        KOKKOS_FUNCTION point_t globalToLocal(const vertex_points_t& global_vertices,
+                                              const point_t& point) const;
 
         /**
          * @brief Transforms a point from local to global coordinates.

src/FEM/Elements/HexahedralElement.h

@@ -58,7 +58,8 @@ namespace ippl {
          *
          * @return point_t
          */
-        KOKKOS_FUNCTION point_t globalToLocal(const vertex_points_t&, const point_t&) const;
+        KOKKOS_FUNCTION point_t globalToLocal(const vertex_points_t& global_vertices,
+                                              const point_t& point) const;
 
         /**
          * @brief Transforms a point from local to global coordinates.

src/FEM/Elements/QuadrilateralElement.h

@@ -59,7 +59,8 @@ namespace ippl {
          *
          * @return point_t
          */
-        KOKKOS_FUNCTION point_t globalToLocal(const vertex_points_t&, const point_t&) const;
+        KOKKOS_FUNCTION point_t globalToLocal(const vertex_points_t& global_vertices,
+                                              const point_t& point) const;
 
         /**
          * @brief Transforms a point from local to global coordinates.

src/FEM/LagrangeSpace.h

@@ -112,7 +112,7 @@ namespace ippl {
 
         ///////////////////////////////////////////////////////////////////////
         /**
-         * @brief Function to update the element partition and the layout of 
+         * @brief Function to update the element partition and the layout of
          * fields in the LagrangeSpace if the layout has been changed during
          * the simulation (for example by the load balancer).
          */
@@ -138,7 +138,7 @@ namespace ippl {
          * @return size_t - The local DOF index
          */
         KOKKOS_FUNCTION size_t getLocalDOFIndex(const size_t& elementIndex,
-                                 const size_t& globalDOFIndex) const override;
+                                                const size_t& globalDOFIndex) const override;
 
         /**
          * @brief Get the global DOF index from the element index and local DOF
@@ -163,7 +163,7 @@ namespace ippl {
         /**
          * @brief Get the global DOF indices (vector of global DOF indices) of an element
          *
-         * @param elementIndex size_t - The index of the element
+         * @param element_index size_t - The index of the element
          *
          * @return Vector<size_t, NumElementDOFs> - The global DOF indices
          */
@@ -203,7 +203,8 @@ namespace ippl {
         /// Functions to access element info from outside /////////////////////
         ///////////////////////////////////////////////////////////////////////
 
-        KOKKOS_FUNCTION point_t getInverseTransposeTransformationJacobian(vertex_points_t pt) const {
+        KOKKOS_FUNCTION point_t
+        getInverseTransposeTransformationJacobian(vertex_points_t pt) const {
             return this->ref_element_m.getInverseTransposeTransformationJacobian(pt);
         }
 
@@ -238,8 +239,8 @@ namespace ippl {
         FieldLHS evaluateAx_diag(FieldLHS& field, F& evalFunction);
 
         /**
-         * @brief Assemble the left stiffness matrix A of the system 
-         * but only for the boundary values, so that they can be 
+         * @brief Assemble the left stiffness matrix A of the system
+         * but only for the boundary values, so that they can be
          * subtracted from the RHS for treatment of Dirichlet BCs
          *
          * @param field The field to assemble the matrix for
@@ -253,9 +254,7 @@ namespace ippl {
         /**
          * @brief Assemble the load vector b of the system Ax = b
          *
-         * @param rhs_field The field to set with the load vector
-         *
-         * @return FieldRHS - The RHS field containing b
+         * @param field The field to set with the load vector
          */
         void evaluateLoadVector(FieldRHS& field) const;
         void evaluateLumpedMass(FieldRHS& field) const;
@@ -298,17 +297,17 @@ namespace ippl {
             KOKKOS_FUNCTION indices_t getMeshVertexNDIndex(const size_t& vertex_index) const;
 
             KOKKOS_FUNCTION size_t getLocalDOFIndex(const indices_t& elementNDIndex,
-                const size_t& globalDOFIndex) const;
+                                                    const size_t& globalDOFIndex) const;
             KOKKOS_FUNCTION Vector<size_t, numElementDOFs> getGlobalDOFIndices(
                 const indices_t& elementNDIndex) const;
 
             KOKKOS_FUNCTION T evaluateRefElementShapeFunction(const size_t& localDOF,
-                const point_t& localPoint) const;
+                                                              const point_t& localPoint) const;
             KOKKOS_FUNCTION point_t evaluateRefElementShapeFunctionGradient(
                 const size_t& localDOF, const point_t& localPoint) const;
         };
 
-        DeviceStruct getDeviceMirror() const; 
+        DeviceStruct getDeviceMirror() const;
 
     private:
         /**