From f4285753effa04b01f6392cec8171f4f2871af93 Mon Sep 17 00:00:00 2001
From: Alex Bilger <alexbilger0@gmail.com>
Date: Wed, 17 Dec 2025 16:18:24 +0100
Subject: [PATCH] [Helper] Minor improvements in AdvancedTimer

---
 .../Helper/src/sofa/helper/AdvancedTimer.cpp  |  4 +--
 .../Helper/src/sofa/helper/AdvancedTimer.h    | 34 ++++++++++++++++++-
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/Sofa/framework/Helper/src/sofa/helper/AdvancedTimer.cpp b/Sofa/framework/Helper/src/sofa/helper/AdvancedTimer.cpp
index 44bb9d7fada..7d79c4c6613 100644
--- a/Sofa/framework/Helper/src/sofa/helper/AdvancedTimer.cpp
+++ b/Sofa/framework/Helper/src/sofa/helper/AdvancedTimer.cpp
@@ -242,7 +242,7 @@ void AdvancedTimer::end(IdTimer id, std::ostream& result)
     }
     if (id != curTimer.top())
     {
-        msg_error("AdvancedTimer::end") << "timer[" << id << "] does not correspond to last call to begin(" << curTimer.top() << ")" ;
+        msg_error("AdvancedTimer") << "Trying to end the timer \"" << id << "\" but the last call to 'begin' was for timer \"" << curTimer.top() << "\"";
         return;
     }
     type::vector<Record>* curRecords = getCurRecords();
@@ -286,7 +286,7 @@ void AdvancedTimer::end(IdTimer id)
     }
     if (id != curTimer.top())
     {
-        msg_error("AdvancedTimer::end") << "timer[" << id << "] does not correspond to last call to begin(" << curTimer.top() << ")" ;
+        msg_error("AdvancedTimer") << "Trying to end the timer \"" << id << "\" but the last call to 'begin' was for timer \"" << curTimer.top() << "\"";
         return;
     }
 
diff --git a/Sofa/framework/Helper/src/sofa/helper/AdvancedTimer.h b/Sofa/framework/Helper/src/sofa/helper/AdvancedTimer.h
index d97fbb2d405..d8311cbe772 100644
--- a/Sofa/framework/Helper/src/sofa/helper/AdvancedTimer.h
+++ b/Sofa/framework/Helper/src/sofa/helper/AdvancedTimer.h
@@ -127,8 +127,40 @@ namespace sofa::helper
 class Record
 {
 public:
+    /**
+     * @brief High-resolution timestamp of the timer event in clock ticks
+     *
+     * This timestamp records the number of clock ticks since some reference point (not absolute time).
+     *
+     * **Important usage note**: When converting to seconds, you should only use time differences (e.g., `time2 - time1`).
+     * Absolute values of this type cannot be directly converted to seconds without knowing the reference point.
+     */
     sofa::helper::system::thread::ctime_t time;
-    enum Type { RNONE, RBEGIN, REND, RSTEP_BEGIN, RSTEP_END, RSTEP, RVAL_SET, RVAL_ADD } type;
+
+    /**
+     * @enum Record::Type
+     * @brief Type of record in the timer data.
+     *
+     * This enum defines the different types of records that can be stored in the timer data stream.
+     * Each record type represents a specific timing operation or value tracking operation.
+     *
+     * @note The values are used to distinguish between different types of timer operations and value tracking operations.
+     *
+     * @{
+     */
+    enum Type {
+        RNONE,     ///< No record (used for initialization)
+        RBEGIN,    ///< Begin timer operation (e.g., when a timer starts)
+        REND,      ///< End timer operation (e.g., when a timer stops)
+        RSTEP_BEGIN,  ///< Begin of a step operation (e.g., when a step starts)
+        RSTEP_END,    ///< End of a step operation (e.g., when a step ends)
+        RSTEP,        ///< Step operation (e.g., when a step is executed)
+        RVAL_SET,     ///< Set a value operation (e.g., when a value is set)
+        RVAL_ADD      ///< Add to a value operation (e.g., when a value is added)
+    };
+    /// @}
+
+    Type type;
     std::string label;
     unsigned int id;
     unsigned int obj;