Improving doxygen doc

lains · May 15, 2024 · 29c8769 · 29c8769
1 parent 88438ea
commit 29c8769
Showing 1 changed file with 35 additions and 21 deletions.
diff --git a/include/TIC/DatasetView.h b/include/TIC/DatasetView.h
@@ -18,11 +18,14 @@ namespace TIC {
 class Horodate {
 public:
 /* Types */
+    /**
+     * @brief A season (in TIC terminology): winter/summer period
+     */
     typedef enum {
-        Unknown = 0,
-        Winter, /* Winter */
-        Summer, /* Summer */
-        Malformed,
+        Unknown = 0, /*!< Unknown, unspecified season */
+        Winter, /*!< Winter */
+        Summer, /*!< Summer */
+        Malformed, /*!< Malformed season data */
     } Season;
 /* Constants */
     STATIC_CONSTEXPR unsigned int HORODATE_SIZE = 13; /*!< Size for a horodate tag (in bytes) */
@@ -75,7 +78,7 @@ class Horodate {
 public:
 /* Attributes */
     bool isValid; /*!< Does this instance contain a valid horodate? */
-    Season season; /*!< */
+    Season season; /*!< The season (in TIC terminology): winter/summer period */
     bool degradedTime; /*!< The horodate was generated by a device with a degraded realtime-clock */
     uint16_t year;
     uint8_t month;
@@ -88,16 +91,19 @@ class Horodate {
 class DatasetView {
 public:
 /* Types */
+    /**
+     * @brief A category resulting of the analysis of a dataset
+     */
     typedef enum {
-        Malformed = 0, /* Malformed dataset */
-        WrongCRC,
-        ValidHistorical, /* Default TIC on newly installed meters */
-        ValidStandard,
+        Malformed = 0, /*!< Malformed dataset */
+        WrongCRC, /*!< The CRC for this dataset is incorrect */
+        ValidHistorical, /*!< Dataset compliant with historical TIC format (this is the default TIC on meters) */
+        ValidStandard, /*!< Dataset compliant with standard TIC format */
     } DatasetType;
 
 /* Constants */
-    STATIC_CONSTEXPR uint8_t _HT = 0x09; /* Horizontal tab */
-    STATIC_CONSTEXPR uint8_t _SP = 0x20; /* Space */
+    STATIC_CONSTEXPR uint8_t _HT = 0x09; /*!< Horizontal tab */
+    STATIC_CONSTEXPR uint8_t _SP = 0x20; /*!< Space */
 
 /* Methods */
     /**
@@ -115,15 +121,6 @@ class DatasetView {
      */
     bool isValid() const;
 
-    /**
-     * @brief Compute a unsigned int value from a dataset value buffer
-     * 
-     * @param buf A pointer to the dataset value buffer
-     * @param cnt The number of digits in @p buf
-     * @return The decoded unsigned int value, or -1 in case of errors
-     */
-    static uint32_t uint32FromValueBuffer(const uint8_t* buf, unsigned int cnt);
-
     /**
      * @brief Check if the current data label matches the one provided as argument
      * 
@@ -141,10 +138,27 @@ class DatasetView {
     uint32_t dataToUint32() const;
 
 
-private:
+protected:
+    /**
+     * @brief Compute a TIC label+data CRC
+     * 
+     * @param[in] bytes The buffer on which to compute the CRC
+     * @param count The number of bytes to use in buffer @p bytes
+     * 
+     * @return An 8-bit TIC CRC
+     */
     static uint8_t computeCRC(const uint8_t* bytes, unsigned int count);
 
 public:
+    /**
+     * @brief Compute a unsigned int value from a dataset value buffer
+     * 
+     * @param buf A pointer to the dataset value buffer
+     * @param cnt The number of digits in @p buf
+     * @return The decoded unsigned int value, or -1 in case of errors
+     */
+    static uint32_t uint32FromValueBuffer(const uint8_t* buf, unsigned int cnt);
+
 /* Attributes */
     DatasetType decodedType;  /*!< What is the resulting type of the parsed dataset? */
     const uint8_t* labelBuffer; /*!< A pointer to the label buffer */