Fix docstring(s) attributed to the flamegpu namespace (#1169)

* Fix docstrings wrongly attributed to the flamegpu namespace

* Document the flamegpu namespace in flamegpu.h

include/flamegpu/detail/cuda.cuh

@@ -1,18 +1,19 @@
 #ifndef INCLUDE_FLAMEGPU_DETAIL_CUDA_CUH_
 #define INCLUDE_FLAMEGPU_DETAIL_CUDA_CUH_
 
-/**
- * Collection of cuda related utility methods for internal use.
- * Mostly to allow for graceful handling of device resets when cuda is called by dtors
- * @todo - we should check for unified addressing support prior to use of cudaPointerGetAttributes, but it should be available for all valide flamegpu targets (x64 linux and windows). Tegra's might be an edge case.
- */
 #include <cuda_runtime.h>
 #include <cuda.h>
 #include <limits>
 #include "flamegpu/exception/FLAMEGPUException.h"
 
 namespace flamegpu {
 namespace detail {
+
+/**
+ * Collection of cuda related utility methods for internal use.
+ * Mostly to allow for graceful handling of device resets when cuda is called by dtors
+ * @todo - we should check for unified addressing support prior to use of cudaPointerGetAttributes, but it should be available for all valid flamegpu targets (x64 linux and windows). Tegra's might be an edge case.
+ */
 namespace cuda {
 
 /**

include/flamegpu/detail/curand.cuh

@@ -1,9 +1,7 @@
 #ifndef INCLUDE_FLAMEGPU_DETAIL_CURAND_CUH_
 #define INCLUDE_FLAMEGPU_DETAIL_CURAND_CUH_
 
-/**
- * This header exists to allow a convenient way to switch between curand implementations
- */
+// This header exists to allow a convenient way to switch between curand implementations
 
 #include <curand_kernel.h>
 

include/flamegpu/flamegpu.h

@@ -12,6 +12,13 @@
 #include <glm/glm.hpp>
 #endif
 
+/**
+ * @namespace flamegpu
+ * The flamegpu namespace containing all namespace'd elements of the flamegpu api.
+ *
+ * The inner detail namespace and it's members are implementation details not considered part of the public facing API and may change at any time.
+ */
+
 // include all host API classes (top level header from each module)
 #include "flamegpu/version.h"
 #include "flamegpu/runtime/HostAPI.h"

include/flamegpu/runtime/detail/curve/Curve.cuh

@@ -4,7 +4,7 @@
 #ifndef __CUDACC_RTC__
 #include <string>
 #endif
-/**
+/*
  * The main cuRVE header file for the CUDA Runtime Variable Environment (cuRVE)
  * Based off the following article http:// www.gamasutra.com/view/news/127915/InDepth_Quasi_CompileTime_String_Hashing.php
  * This file contains definitions common to HostCurve and DeviceCurve

include/flamegpu/runtime/environment/DeviceMacroProperty.cuh

@@ -5,15 +5,15 @@
 #include <limits>
 #include <algorithm>
 
-/**
- * CUDA does not implement atomicAdd(double*, double) for pre-pascal GPUs, which do not have the underlying hardware instruction.
- * A CAS based software implementation is required instead, which will be much slower.
- * This implementation is based on the reference implementation prodived by the CUDA toolkit documentation.
- */
 #ifdef __CUDACC__
 #include <cuda_runtime.h>
 // Needs to be mutually exclusive with definitions in CUDA's sm_60_atomic_functions.h
 #if defined(__CUDA_ARCH__) && __CUDA_ARCH__ < 600
+/**
+ * CUDA does not implement atomicAdd(double*, double) for pre-pascal GPUs, which do not have the underlying hardware instruction.
+ * A CAS based software implementation is required instead, which will be much slower.
+ * This implementation is based on the reference implementation provided by the CUDA toolkit documentation.
+ */
 __device__ __forceinline__ double atomicAdd(double* address, double val) {
     // cpplint enforces uint64_t, but atomicCAS is implemented for unsigned long long int
     unsigned long long int* address_as_ull = reinterpret_cast<unsigned long long int*>(address);  // NOLINT(runtime/int)

include/flamegpu/simulation/AgentVector_Agent.h

@@ -1,8 +1,8 @@
 #ifndef INCLUDE_FLAMEGPU_SIMULATION_AGENTVECTOR_AGENT_H_
 #define INCLUDE_FLAMEGPU_SIMULATION_AGENTVECTOR_AGENT_H_
 
-/**
- * THIS CLASS SHOULD NOT BE INCLUDED DIRECTLY
+/*
+ * THIS HEADER SHOULD NOT BE INCLUDED DIRECTLY
  * Include flamegpu/simulation/AgentVector.h instead
  * Use AgentVector::CAgent instead of AgentVector_CAgent
  * Use AgentVector::Agent instead of AgentVector_Agent

include/flamegpu/util/cleanup.h

@@ -1,8 +1,8 @@
 #ifndef INCLUDE_FLAMEGPU_UTIL_CLEANUP_H_
 #define INCLUDE_FLAMEGPU_UTIL_CLEANUP_H_
 
-/**
- * Prodvides a utility method to cleanup after flamegpu. Currently for the only implementation (CUDA) this resets all devices.
+/*
+ * Provides a utility method to cleanup after flamegpu. Currently for the only implementation (CUDA) this resets all devices.
  */
 
 namespace flamegpu {

include/flamegpu/util/nvtx.h

@@ -3,12 +3,6 @@
 
 #include <cstdint>
 
-/**
- * Utility namespace for handling of NVTX profiling markers/ranges, uses if constexpr to avoid runtime cost when disabled
- *
- * Macro `FLAMEGPU_USE_NVTX` is defined via CMake to set the member constexpr
- */
-
 // If NVTX is enabled, include header, defined namespace / class and macros.
 #if defined(FLAMEGPU_USE_NVTX)
     // Include the appropriate header if enabled
@@ -27,6 +21,12 @@
 
 namespace flamegpu {
 namespace util {
+
+/**
+ * Utility namespace for handling of NVTX profiling markers/ranges, uses if constexpr to avoid runtime cost when disabled
+ *
+ * Macro `FLAMEGPU_USE_NVTX` is defined via CMake to set the member constexpr
+ */
 namespace nvtx {
 
 /**