docs: improve util docs

Doxyfile

@@ -12,6 +12,7 @@ CALL_GRAPH             = YES
 HAVE_DOT               = YES
 EXTRACT_ALL            = YES
 USE_MATHJAX            = YES
+EXTRACT_STATIC         = YES
 PLANTUML_JAR_PATH      = $(PLANTUML_JAR_PATH)
 PLANTUML_CFG_FILE      =
 PLANTUML_INCLUDE_PATH  =

src/pre/pre_date.h

@@ -1,5 +1,5 @@
 /**
- * @link https://stackoverflow.com/questions/11697820/how-to-use-date-and-time-predefined-macros-in-as-two-integers-then-stri
+ * @li https://stackoverflow.com/questions/11697820/how-to-use-date-and-time-predefined-macros-in-as-two-integers-then-stri
  */
 #ifndef H_PRE_DATE_TBC
 #define H_PRE_DATE_TBC

src/sys/sys_nes_output.c

@@ -11,29 +11,29 @@ static void sys_nes_output_init(void);
 
 /**
  * @brief startup PPU, palete, scroll, sprites, nametable...
- * @link https://www.nesdev.org/wiki/PPU_registers
- * @link https://www.nesdev.org/wiki/PPU_palettes
- * @link https://www.nesdev.org/wiki/PPU_scrolling
- * @link https://www.nesdev.org/wiki/PPU_OAM
+ * @li https://www.nesdev.org/wiki/PPU_registers
+ * @li https://www.nesdev.org/wiki/PPU_palettes
+ * @li https://www.nesdev.org/wiki/PPU_scrolling
+ * @li https://www.nesdev.org/wiki/PPU_OAM
  */
 static void sys_nes_output_init()
 {
-    /** init PPU */
+    /* init PPU */
     *((unsigned char*) 0x2000) = 0b10101000;
 
-    /** init palette */
+    /* init palette */
     *((unsigned char*) 0x2006) = 0x3F;
     *((unsigned char*) 0x2006) = 0x00;
-    *((unsigned char*) 0x2007) = 0x0F; /**< color 0: black */
-    *((unsigned char*) 0x2007) = 0x30; /**< color 1: white */
-    *((unsigned char*) 0x2007) = 0x30; /**< color 2: white */
-    *((unsigned char*) 0x2007) = 0x30; /**< color 3: white */
+    *((unsigned char*) 0x2007) = 0x0F; /** @note color 0: black */
+    *((unsigned char*) 0x2007) = 0x30; /** @note color 1: white */
+    *((unsigned char*) 0x2007) = 0x30; /** @note color 2: white */
+    *((unsigned char*) 0x2007) = 0x30; /** @note color 3: white */
 
-    /** reset scroll */
+    /* reset scroll */
     *((unsigned char*) 0x2005) = 0x00;
     *((unsigned char*) 0x2005) = 0x00;
 
-    /** hide all sprites */
+    /* hide all sprites */
     cursor_tty.vram_pack[0] = 0x41;
     *((unsigned char*) 0x2003) = 0x00;
     while(--cursor_tty.vram_pack[0]) {
@@ -43,7 +43,7 @@ static void sys_nes_output_init()
         *((unsigned char*) 0x2004) = 0xf0;
     }
 
-    /** clear screen */
+    /* clear screen */
     cursor_tty.vram_address = 0x2000;
     *((unsigned char*) 0x2006) = cursor_tty.vram_pack[1];
     *((unsigned char*) 0x2006) = cursor_tty.vram_pack[0];
@@ -53,28 +53,28 @@ static void sys_nes_output_init()
     }
     while(cursor_tty.vram_address <= (0x2400 - 0x60));
 
-    /** reset cursor position */
+    /* reset cursor position */
     cursor_tty.vram_address = 0x2020;
     *((unsigned char*) 0x2006) = cursor_tty.vram_pack[1];
     *((unsigned char*) 0x2006) = cursor_tty.vram_pack[0];
 }
 
 /**
  * @brief stream text in entire TV screen
- * @link https://www.nesdev.org/wiki/PPU_memory_map
- * @link https://www.nesdev.org/wiki/PPU_nametables
- * @link https://www.nesdev.org/wiki/PPU_registers
- * @link https://www.nesdev.org/wiki/NMI_thread
- * @link https://www.nesdev.org/wiki/NMI
+ * @li https://www.nesdev.org/wiki/PPU_memory_map
+ * @li https://www.nesdev.org/wiki/PPU_nametables
+ * @li https://www.nesdev.org/wiki/PPU_registers
+ * @li https://www.nesdev.org/wiki/NMI_thread
+ * @li https://www.nesdev.org/wiki/NMI
  */
 void sys_nes_output(tbc_app_st *const self)
 {
-    /** interator */
+    /* interator */
     static tbc_u8_t* buffer;
     static tbc_u8_t index;
     static tbc_u8_t tile;
 
-    /** reset */
+    /* reset */
     if(self->cache_l3.fixbuf.size < 0) {
         buffer = self->cache_l3.buffer.storage;
         self->cache_l3.fixbuf.size = -self->cache_l3.fixbuf.size;
@@ -83,81 +83,81 @@ void sys_nes_output(tbc_app_st *const self)
     }
     index = 0;
 
-    /** first put */
+    /* first put */
     if (cursor_tty.vram_address == 0) {
         sys_nes_output_init();
     }
 
-    /** wait nmi */
+    /* wait nmi */
     while(*((signed char*) 0x2002) > 0) {
         continue;
     }
 
-    /** turn off PPU */
+    /* turn off PPU */
     *((unsigned char*) 0x2001) = 0b00000000;
 
-    /** update nametable cursor position */
+    /* update nametable cursor position */
     *((unsigned char*) 0x2006) = cursor_tty.vram_pack[1];
     *((unsigned char*) 0x2006) = cursor_tty.vram_pack[0];
 
-    /** streamming */
+    /* streamming */
     while(1) {
-        /** cache tile to improve perfomance */
+        /* cache tile to improve perfomance */
         tile = buffer[index];
         ++index;
 
-        /** end of of max size*/
+        /* end of of max size*/
         if (index > self->cache_l3.fixbuf.size) {
             break;
         }
 
-        /** terminator */
+        /* terminator */
         if (tile == '\0') {
             break;
         }
 
-        /** special char: carrier return */
+        /* special char: carrier return */
         if (tile == '\r') {
-            /** ignore */
+            /* ignore */
             continue;
         }
 
-        /** 0x60 is three lines to end screen */
+        /* 0x60 is three lines to end screen */
         if (cursor_tty.vram_address >= (0x2400 - 0x60)) {
             sys_nes_output_init();
             index = 0;
             continue;
         }
 
-        /** special char: tab */
+        /* special char: tab */
         if (tile == '\t') {
             /** 
-             * tabulation
-             * @joke I really don't know how it works!
+             * @par joke
+             * I really don't know how this @b tabulation works!
              */
             cursor_tty.vram_address |= 7;
             *((unsigned char*) 0x2006) = cursor_tty.vram_pack[1];
             *((unsigned char*) 0x2006) = cursor_tty.vram_pack[0];
             continue;
         }
 
-        /** special char: break line */
+        /* special char: break line */
         if (tile == '\n') {
-            /** line feed */
+            /* line feed */
             cursor_tty.vram_address += 32;
-            /** carrier return */
+            /* carrier return */
             cursor_tty.vram_address &= 0xffe0;
-            /** update cursor position into the nametable */
+            /* update cursor position into the nametable */
             *((unsigned char*) 0x2006) = cursor_tty.vram_pack[1];
             *((unsigned char*) 0x2006) = cursor_tty.vram_pack[0];
             continue;
         }
 
-        /** put character to PPU */
+        /* put character to PPU */
         *((unsigned char*) 0x2007) = tile;
         ++cursor_tty.vram_address;
     }
 
-    /** turn on PPU*/
+    /* turn on PPU*/
     *((unsigned char*) 0x2001) = 0b00011110;
 }

src/util/util_args.c

@@ -1,20 +1,36 @@
+/**
+ * @file util_args.c
+ *
+ * @brief Argument / Parameters Interpreter Utility
+ *
+ * @author Rodrigo Dornelles
+ *
+ * @details
+ * This file provides a utility for interpreting arguments passed through
+ * the command-line interface (CLI) quickly and objectively.
+ *
+ * @copyright
+ * It is distributed under the GNU Affero General Public
+ * License (AGPL) version 3 or any later version. For more details, please
+ * refer to https://www.gnu.org/licenses/
+ */
+
 #include "util_args.h"
 #include "types/types_null.h"
 
 /**
  * @brief verify if exist a flag
  * @details can be use has @c -h or @c -v for help or version.
+ * @par Extended Backus-Naur Form
+ * @startebnf
+ * single_flag = "-", "a-zA-Z" (* any key *);
+ * @endebnf
  * @param[in] argc number of arguments
  * @param[in] argv array of arguments
  * @param[in] key single char flag
  * @return pointer to argument
  * @retval NULL when not found
- * @startebnf
- * single_flag
- *  = "-"
- *  , "a-zA-Z" (* any key *)
- *  ;
- * @endebnf
+ *
  */
 char* util_args_has(int argc, char** argv, char key) {
     char* ret = NULL;
@@ -36,18 +52,15 @@ char* util_args_has(int argc, char** argv, char key) {
 /**
  * @brief get value of a compound flag
  * @details can be use has @c -o @c value for ouput some file.
+ * @par Extended Backus-Naur Form
+ * @startebnf
+ * composite_flag = "-", "a-zA-Z" (* any key *), text (* cannot start with "-" *);
+ * @endebnf
  * @param[in] argc number of arguments
  * @param[in] argv array of arguments
  * @param[in] key single char flag
  * @return pointer to argument
  * @retval NULL when not found
- * @startebnf
- * composite_flag
- *  = "-"
- *  , "a-zA-Z" (* any key *)
- *  , text (* cannot start with "-" *)
- *  ;
- * @endebnf
  */
 char* util_args_get(int argc, char** argv, char key) {
     char* ret = NULL;

src/util/util_dsl.c

@@ -1,53 +1,31 @@
 /**
- * @internal
- *  ___________  _____   _
- * |____ | ___ \/  __ \ | |
- *     / / |_/ /| /  \/ | | __ _ _ __   __ _ _   _  __ _  __ _  ___
- *     \ \ ___ \| |     | |/ _` | '_ \ / _` | | | |/ _` |/ _` |/ _ \
- * .___/ / |_/ /| \__/\ | | (_| | | | | (_| | |_| | (_| | (_| |  __/
- * \____/\____/  \____/ |_|\__,_|_| |_|\__, |\__,_|\__,_|\__, |\___|
- *                                     __/ |             __/ |
- *                                    |___/             |___/
- * @endinternal
  * @file util_dsl.c
  *
- * @short
- * domain specific language utility
+ * @brief Domain-Specific Language (DSL) Utility
  *
- * @brief
- * Utility for writing simple language lexers without precedence tracking
+ * @author Rodrigo Dornelles
+ *
+ * @details
+ * This file provides a utility for creating simple language lexers without
+ * precedence tracking.
  *
  * @copyright
- * Low-level language, tiny virtual machine, intermediate representation,     \n
- * embeddable, easy for beginners. (Friendly Punched cards)                   \n
- *                                                                            \n
- * Copyright (C) 2020 Rodrigo Dornelles.                                      \n
- *                                                                            \n
- * This program is free software: you can redistribute it and/or modify       \n
- * it under the terms of the GNU Affero General Public License as published   \n
- * by the Free Software Foundation, either version 3 of the License,          \n
- * or any later version.                                                      \n
- *                                                                            \n
- * This program is distributed in the hope that it will be useful,            \n
- * but WITHOUT ANY WARRANTY; without even the implied warranty of             \n
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the              \n
- * GNU Affero General Public License for more details.                        \n
- *                                                                            \n
- * You should have received a copy of the GNU Affero General Public License   \n
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.     \n
+ * It is distributed under the GNU Affero General Public
+ * License (AGPL) version 3 or any later version. For more details, please
+ * refer to https://www.gnu.org/licenses/
  */
 
 #include <stdbool.h>
 #include "util_dsl.h"
 #include "types/types_null.h"
 
 /**
- * @short parameter divider
+ * @brief extract tokens fom string
  * @details Just like a @c split in  @b JS and @b Python or 
- * @c `explode` in @c PHP, this function separates the string text
+ * @c explode in @c PHP, this function separates the string text
  * according to the space between keywords giving a maximum number of tokens.
  * @param[out] dest array of tokens
- * @param[out] dest array of token sizes
+ * @param[out] destn array of token sizes
  * @param[in] src string
  * @param[in] dn number of pointers
  * @param[in] sn lenght of string
@@ -140,7 +118,7 @@ tbc_i8_t util_dsl_split(char** dest, tbc_u8_t* destn, char* src, tbc_u8_t dn, tb
 }
 
 /**
- * @brief line mark
+ * @brief extract line from string
  * @details receives a text and marks the beginning of how many characters it has,
  * where the comments begin and where they end.
  * 
@@ -239,14 +217,15 @@ tbc_i8_t util_dsl_line(char **beg, char **mid, char **end, char *src, tbc_u8_t s
 }
 
 /**
- * @short keyword to opcode
- * @brief @par find opcode value given a list of keywords
+ * @short keyword index from string
+ * @brief find opcode value given a list of keywords
  * @details binary search optimized for 4-letter keywords in an array
  * that contains a sorted key and a 2-byte (16bit) value.
+ * @todo use string instead struct
  * @note this function is case unsensitive.
  * @note this function has operation complexity @f$O(log (n))@f$.
  * @note this function has endless optimization.
- * @todo this function has old processors optimization.
+ * @note this function has old processors optimization.
  * @param[in] src string source
  * @param[in] kl keyword list @b (array) of @c tbc_keyword_st
  * @param[in] kn keyword size @b (bytes)