Documentation: add documentation for number parser

trilitech · Feb 15, 2024 · 3f39889 · 3f39889
1 parent 9ff9067
commit 3f39889
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 7 deletions.
diff --git a/app/src/parser/num_parser.h b/app/src/parser/num_parser.h
@@ -19,14 +19,55 @@
 
 #include "parser_state.h"
 
-void             tz_parse_num_state_init(tz_num_parser_buffer *buffers,
-                                         tz_num_parser_regs   *regs);
+/**
+ * @brief Initialize a num state buffer and a num state regs
+ *
+ * @param buffers: the number parser buffers
+ * @param regs: the number parser register
+ */
+void tz_parse_num_state_init(tz_num_parser_buffer *buffers,
+                             tz_num_parser_regs   *regs);
+
+/**
+ * @brief Parse one byte
+ *
+ * @param buffers: the number parser buffers
+ * @param regs: the number parser register
+ * @param b: the byte to parse
+ * @param natural: if the number to read is natural
+ * @return tz_parser_result: the parser result
+ */
 tz_parser_result tz_parse_num_step(tz_num_parser_buffer *buffers,
                                    tz_num_parser_regs *regs, uint8_t b,
                                    bool natural);
+
+/**
+ * @brief Parse one byte to read an integer
+ *
+ * @param buffers: the number parser buffers
+ * @param regs: the number parser register
+ * @param b: the byte to parse
+ * @return tz_parser_result: the parser result
+ */
 tz_parser_result tz_parse_int_step(tz_num_parser_buffer *buffers,
                                    tz_num_parser_regs *regs, uint8_t b);
+
+/**
+ * @brief Parse one byte to read a natural number
+ *
+ * @param buffers: the number parser buffers
+ * @param regs: the number parser register
+ * @param b: the byte to parse
+ * @return tz_parser_result: the parser result
+ */
 tz_parser_result tz_parse_nat_step(tz_num_parser_buffer *buffers,
                                    tz_num_parser_regs *regs, uint8_t b);
 
+/**
+ * @brief format a buffer to mutez number
+ *
+ * @param in: the intput buffer
+ * @param out: the output number
+ * @return bool: success
+ */
 bool tz_string_to_mutez(const char *in, uint64_t *out);
diff --git a/app/src/parser/num_state.h b/app/src/parser/num_state.h
@@ -18,14 +18,23 @@
 
 #include "formatting.h"
 
+/**
+ * @brief This struct represents the register for the parser of number
+ *
+ */
 typedef struct {
-    uint16_t size;
-    uint8_t  sign : 1, stop : 1;
+    uint16_t size;      /// the size of the number
+    uint8_t  sign : 1;  /// the sign ot the number
+    uint8_t  stop : 1;  /// the number as been fully parsed
 } tz_num_parser_regs;
 
-#define TZ_NUM_BUFFER_SIZE 256
+#define TZ_NUM_BUFFER_SIZE 256  /// The size of the number buffer
 
+/**
+ * @brief This struct represents the output buffers for the parser of number
+ *
+ */
 typedef struct {
-    uint8_t bytes[TZ_NUM_BUFFER_SIZE / 8];
-    char    decimal[TZ_DECIMAL_BUFFER_SIZE(TZ_NUM_BUFFER_SIZE / 8)];
+    uint8_t bytes[TZ_NUM_BUFFER_SIZE / 8];                         /// bytes
+    char decimal[TZ_DECIMAL_BUFFER_SIZE(TZ_NUM_BUFFER_SIZE / 8)];  /// decimal
 } tz_num_parser_buffer;