From d33d3e62ba32350bea5d81fc3ce46334b0d4016f Mon Sep 17 00:00:00 2001 From: Agustin Ranieri Date: Thu, 15 Aug 2024 23:38:30 -0300 Subject: [PATCH] Docs: Fix logo url, added dark mode toggle and more stuff --- docs/Doxyfile | 11 +- docs/css/custom.css | 9 +- docs/css/doxygen-awesome.css | 44 +++--- docs/html/header.html | 18 +-- docs/js/doxygen-awesome-darkmode-toggle.js | 157 +++++++++++++++++++++ src/commons/bitarray.h | 7 +- src/commons/collections/dictionary.h | 13 +- src/commons/collections/list.h | 27 ++-- src/commons/collections/queue.h | 11 +- src/commons/config.h | 11 +- src/commons/log.h | 6 +- src/commons/memory.h | 7 +- src/commons/process.h | 9 +- src/commons/string.h | 61 ++++---- src/commons/temporal.h | 11 +- src/commons/txt.h | 7 +- 16 files changed, 313 insertions(+), 96 deletions(-) create mode 100644 docs/js/doxygen-awesome-darkmode-toggle.js diff --git a/docs/Doxyfile b/docs/Doxyfile index eb37b15..df9639a 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -614,7 +614,7 @@ HIDE_COMPOUND_REFERENCE= NO # the files that are included by a file in the documentation of that file. # The default value is: YES. -SHOW_INCLUDE_FILES = YES +SHOW_INCLUDE_FILES = NO # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each # grouped member an include statement to the documentation, telling the reader @@ -1032,7 +1032,7 @@ USE_MDFILE_AS_MAINPAGE = README.md # also VERBATIM_HEADERS is set to NO. # The default value is: NO. -SOURCE_BROWSER = YES +SOURCE_BROWSER = NO # Setting the INLINE_SOURCES tag to YES will include the body of functions, # classes and enums directly into the documentation. @@ -1065,7 +1065,7 @@ REFERENCES_RELATION = NO # link to the documentation. # The default value is: YES. -REFERENCES_LINK_SOURCE = YES +REFERENCES_LINK_SOURCE = NO # If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the # source code will show a tooltip with additional information such as prototype, @@ -1241,7 +1241,8 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = css/custom.css css/doxygen-awesome.css +HTML_EXTRA_STYLESHEET = css/doxygen-awesome.css \ + css/custom.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1251,7 +1252,7 @@ HTML_EXTRA_STYLESHEET = css/custom.css css/doxygen-awesome.css # files will be copied as-is; there are no commands or markers available. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_FILES = +HTML_EXTRA_FILES = js/doxygen-awesome-darkmode-toggle.js # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to diff --git a/docs/css/custom.css b/docs/css/custom.css index f642104..ac0bb0e 100644 --- a/docs/css/custom.css +++ b/docs/css/custom.css @@ -1,8 +1,13 @@ -#projectname, #projectbrief { +#titlearea { color: var(--header-foreground) !important; /* Inherit color from parent */ text-decoration: none; /* Remove underline */ } -#projectname:hover, #projectbrief:hover { +#titlearea:hover { text-decoration: none; /* Ensure no underline on hover */ } + +a[href="#details"], +a[href$="source.html"] { + display: none; /* Hide links to details section and source files */ +} diff --git a/docs/css/doxygen-awesome.css b/docs/css/doxygen-awesome.css index a2715e2..c6ba0c1 100644 --- a/docs/css/doxygen-awesome.css +++ b/docs/css/doxygen-awesome.css @@ -187,7 +187,7 @@ html { html:not(.light-mode) { color-scheme: dark; - --primary-color: #1982d2; + --primary-color: #59a0d6; --primary-dark-color: #86a9c4; --primary-light-color: #4779ac; @@ -206,7 +206,7 @@ html { --code-background: #2a2c2f; --tablehead-background: #2a2c2f; - + --blockquote-background: #222325; --blockquote-foreground: #7e8c92; @@ -214,7 +214,7 @@ html { --warning-color-dark: #f1b602; --warning-color-darker: #ceb670; --note-color: #163750; - --note-color-dark: #1982D2; + --note-color-dark: #59a0d6; --note-color-darker: #dcf0fa; --todo-color: #2a2536; --todo-color-dark: #7661b3; @@ -248,7 +248,7 @@ html { html.dark-mode { color-scheme: dark; - --primary-color: #1982d2; + --primary-color: #59a0d6; --primary-dark-color: #86a9c4; --primary-light-color: #4779ac; @@ -275,7 +275,7 @@ html.dark-mode { --warning-color-dark: #f1b602; --warning-color-darker: #ceb670; --note-color: #163750; - --note-color-dark: #1982D2; + --note-color-dark: #59a0d6; --note-color-darker: #dcf0fa; --todo-color: #2a2536; --todo-color-dark: #7661b3; @@ -896,7 +896,7 @@ div.header { flex-wrap: nowrap; align-items: flex-start; } - + div.contents .textblock { min-width: 200px; flex-grow: 1; @@ -988,21 +988,21 @@ html.dark-mode div.contents .dotgraph iframe h2.groupheader { border-bottom: 0px; color: var(--page-foreground-color); - box-shadow: - 100px 0 var(--page-background-color), + box-shadow: + 100px 0 var(--page-background-color), -100px 0 var(--page-background-color), 100px 0.75px var(--separator-color), -100px 0.75px var(--separator-color), - 500px 0 var(--page-background-color), + 500px 0 var(--page-background-color), -500px 0 var(--page-background-color), 500px 0.75px var(--separator-color), -500px 0.75px var(--separator-color), - 900px 0 var(--page-background-color), + 900px 0 var(--page-background-color), -900px 0 var(--page-background-color), 900px 0.75px var(--separator-color), -900px 0.75px var(--separator-color), 1400px 0 var(--page-background-color), - -1400px 0 var(--page-background-color), + -1400px 0 var(--page-background-color), 1400px 0.75px var(--separator-color), -1400px 0.75px var(--separator-color), 1900px 0 var(--page-background-color), @@ -1173,8 +1173,8 @@ div.toc li a.aboveActive { div.contents .toc.interactive > h3::before { content: ""; - width: 0; - height: 0; + width: 0; + height: 0; border-left: 4px solid transparent; border-right: 4px solid transparent; border-top: 5px solid var(--primary-color); @@ -1870,8 +1870,8 @@ table.memberdecls img[src="closed.png"], table.memberdecls img[src="open.png"], div.dynheader img[src="open.png"], div.dynheader img[src="closed.png"] { - width: 0; - height: 0; + width: 0; + height: 0; border-left: 4px solid transparent; border-right: 4px solid transparent; border-top: 5px solid var(--primary-color); @@ -1889,7 +1889,7 @@ table.memberdecls img { table.memberdecls img[src="closed.png"], div.dynheader img[src="closed.png"] { transform: rotate(-90deg); - + } .compoundTemplParams { @@ -1932,7 +1932,7 @@ div.dynheader img[src="closed.png"] { margin-bottom: calc(0px - var(--page-font-size)); } - table.memberdecls .memItemRight, + table.memberdecls .memItemRight, table.memberdecls .mdescRight, table.memberdecls .memTemplItemRight { border-top: 0; @@ -1997,7 +1997,7 @@ hr { 1400px 0 var(--separator-color), -1400px 0 var(--separator-color), 1900px 0 var(--separator-color), - -1900px 0 var(--separator-color); + -1900px 0 var(--separator-color); } .contents img, .contents .center, .contents center, .contents div.image object { @@ -2120,8 +2120,8 @@ html.dark-mode .iconfopen, html.dark-mode .iconfclosed { background-color: transparent; } -/* - Class Index Doxygen 1.8 +/* + Class Index Doxygen 1.8 */ table.classindex { @@ -2266,7 +2266,7 @@ div.contents .toc::-webkit-scrollbar-thumb, background-color: transparent; border: var(--webkit-scrollbar-padding) solid transparent; border-radius: calc(var(--webkit-scrollbar-padding) + var(--webkit-scrollbar-padding)); - background-clip: padding-box; + background-clip: padding-box; } #nav-tree:hover::-webkit-scrollbar-thumb, @@ -2514,7 +2514,7 @@ h2:hover a.anchorlink, h1:hover a.anchorlink, h3:hover a.anchorlink, h4:hover a. cursor: pointer; box-shadow: 0 1px 0 0 var(--separator-color); position: relative; - + -webkit-tap-highlight-color: transparent; } diff --git a/docs/html/header.html b/docs/html/header.html index ee12664..fb67c63 100644 --- a/docs/html/header.html +++ b/docs/html/header.html @@ -16,27 +16,27 @@ $mathjax $extrastylesheet + +
- + diff --git a/docs/js/doxygen-awesome-darkmode-toggle.js b/docs/js/doxygen-awesome-darkmode-toggle.js new file mode 100644 index 0000000..40fe2d3 --- /dev/null +++ b/docs/js/doxygen-awesome-darkmode-toggle.js @@ -0,0 +1,157 @@ +/** + +Doxygen Awesome +https://github.com/jothepro/doxygen-awesome-css + +MIT License + +Copyright (c) 2021 - 2023 jothepro + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +*/ + +class DoxygenAwesomeDarkModeToggle extends HTMLElement { + // SVG icons from https://fonts.google.com/icons + // Licensed under the Apache 2.0 license: + // https://www.apache.org/licenses/LICENSE-2.0.html + static lightModeIcon = `` + static darkModeIcon = `` + static title = "Toggle Light/Dark Mode" + + static prefersLightModeInDarkModeKey = "prefers-light-mode-in-dark-mode" + static prefersDarkModeInLightModeKey = "prefers-dark-mode-in-light-mode" + + static _staticConstructor = function() { + DoxygenAwesomeDarkModeToggle.enableDarkMode(DoxygenAwesomeDarkModeToggle.userPreference) + // Update the color scheme when the browsers preference changes + // without user interaction on the website. + window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => { + DoxygenAwesomeDarkModeToggle.onSystemPreferenceChanged() + }) + // Update the color scheme when the tab is made visible again. + // It is possible that the appearance was changed in another tab + // while this tab was in the background. + document.addEventListener("visibilitychange", visibilityState => { + if (document.visibilityState === 'visible') { + DoxygenAwesomeDarkModeToggle.onSystemPreferenceChanged() + } + }); + }() + + static init() { + $(function() { + $(document).ready(function() { + const toggleButton = document.createElement('doxygen-awesome-dark-mode-toggle') + toggleButton.title = DoxygenAwesomeDarkModeToggle.title + toggleButton.updateIcon() + + window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => { + toggleButton.updateIcon() + }) + document.addEventListener("visibilitychange", visibilityState => { + if (document.visibilityState === 'visible') { + toggleButton.updateIcon() + } + }); + + $(document).ready(function(){ + document.getElementById("MSearchBox").parentNode.appendChild(toggleButton) + }) + $(window).resize(function(){ + document.getElementById("MSearchBox").parentNode.appendChild(toggleButton) + }) + }) + }) + } + + constructor() { + super(); + this.onclick=this.toggleDarkMode + } + + /** + * @returns `true` for dark-mode, `false` for light-mode system preference + */ + static get systemPreference() { + return window.matchMedia('(prefers-color-scheme: dark)').matches + } + + /** + * @returns `true` for dark-mode, `false` for light-mode user preference + */ + static get userPreference() { + return (!DoxygenAwesomeDarkModeToggle.systemPreference && localStorage.getItem(DoxygenAwesomeDarkModeToggle.prefersDarkModeInLightModeKey)) || + (DoxygenAwesomeDarkModeToggle.systemPreference && !localStorage.getItem(DoxygenAwesomeDarkModeToggle.prefersLightModeInDarkModeKey)) + } + + static set userPreference(userPreference) { + DoxygenAwesomeDarkModeToggle.darkModeEnabled = userPreference + if(!userPreference) { + if(DoxygenAwesomeDarkModeToggle.systemPreference) { + localStorage.setItem(DoxygenAwesomeDarkModeToggle.prefersLightModeInDarkModeKey, true) + } else { + localStorage.removeItem(DoxygenAwesomeDarkModeToggle.prefersDarkModeInLightModeKey) + } + } else { + if(!DoxygenAwesomeDarkModeToggle.systemPreference) { + localStorage.setItem(DoxygenAwesomeDarkModeToggle.prefersDarkModeInLightModeKey, true) + } else { + localStorage.removeItem(DoxygenAwesomeDarkModeToggle.prefersLightModeInDarkModeKey) + } + } + DoxygenAwesomeDarkModeToggle.onUserPreferenceChanged() + } + + static enableDarkMode(enable) { + if(enable) { + DoxygenAwesomeDarkModeToggle.darkModeEnabled = true + document.documentElement.classList.add("dark-mode") + document.documentElement.classList.remove("light-mode") + } else { + DoxygenAwesomeDarkModeToggle.darkModeEnabled = false + document.documentElement.classList.remove("dark-mode") + document.documentElement.classList.add("light-mode") + } + } + + static onSystemPreferenceChanged() { + DoxygenAwesomeDarkModeToggle.darkModeEnabled = DoxygenAwesomeDarkModeToggle.userPreference + DoxygenAwesomeDarkModeToggle.enableDarkMode(DoxygenAwesomeDarkModeToggle.darkModeEnabled) + } + + static onUserPreferenceChanged() { + DoxygenAwesomeDarkModeToggle.enableDarkMode(DoxygenAwesomeDarkModeToggle.darkModeEnabled) + } + + toggleDarkMode() { + DoxygenAwesomeDarkModeToggle.userPreference = !DoxygenAwesomeDarkModeToggle.userPreference + this.updateIcon() + } + + updateIcon() { + if(DoxygenAwesomeDarkModeToggle.darkModeEnabled) { + this.innerHTML = DoxygenAwesomeDarkModeToggle.darkModeIcon + } else { + this.innerHTML = DoxygenAwesomeDarkModeToggle.lightModeIcon + } + } +} + +customElements.define("doxygen-awesome-dark-mode-toggle", DoxygenAwesomeDarkModeToggle); diff --git a/src/commons/bitarray.h b/src/commons/bitarray.h index e0a6d16..012fbd8 100644 --- a/src/commons/bitarray.h +++ b/src/commons/bitarray.h @@ -21,6 +21,11 @@ #include #include + /** + * @file + * @brief `#include ` + */ + /* position of bit within character */ #define BIT_CHAR(bit) ((bit) / CHAR_BIT) @@ -48,7 +53,7 @@ /** * @warning Esta función se encuentra en revisión y probablemente cambie en próximas versiones. - * Usar bitarray_create_with_mode(). + * Usar `bitarray_create_with_mode()`. * * @brief Crea y devuelve un puntero a una estructura t_bitarray con formato LSB_FIRST * diff --git a/src/commons/collections/dictionary.h b/src/commons/collections/dictionary.h index 396e9d2..a217152 100644 --- a/src/commons/collections/dictionary.h +++ b/src/commons/collections/dictionary.h @@ -23,10 +23,15 @@ #include #include "list.h" + /** + * @file + * @brief `#include ` + */ + /** * @struct t_dictionary * @brief Estructura de un diccionario que contiene pares string->puntero. - * Inicializar con dictionary_create(). + * Inicializar con `dictionary_create()`. */ typedef struct { t_hash_element **elements; @@ -38,9 +43,9 @@ /** * @brief Crea el diccionario * @return Devuelve un puntero al diccionario creado, liberable con: - * - dictionary_destroy() si se quiere liberar el diccionario pero no + * - `dictionary_destroy()` si se quiere liberar el diccionario pero no * los elementos que contiene. - * - dictionary_destroy_and_destroy_elements() si se quieren liberar + * - `dictionary_destroy_and_destroy_elements()` si se quieren liberar * el diccionario con los elementos que contiene. */ t_dictionary *dictionary_create(void); @@ -127,7 +132,7 @@ /** * @brief Destruye el diccionario y destruye sus elementos - * @note En caso de recibir un diccionario vacío, se comporta como dictionary_destroy() + * @note En caso de recibir un diccionario vacío, se comporta como `dictionary_destroy()` */ void dictionary_destroy_and_destroy_elements(t_dictionary *, void(*element_destroyer)(void*)); diff --git a/src/commons/collections/list.h b/src/commons/collections/list.h index 548f3b7..3743d61 100755 --- a/src/commons/collections/list.h +++ b/src/commons/collections/list.h @@ -20,9 +20,14 @@ #include "node.h" #include + /** + * @file + * @brief `#include ` + */ + /** * @struct t_list - * @brief Estructura de una lista enlazada. Inicializar con list_create() + * @brief Estructura de una lista enlazada. Inicializar con `list_create()` */ typedef struct { t_link_element *head; @@ -31,7 +36,7 @@ /** * @struct t_list_iterator - * @brief Iterador de listas. Inicializar con list_iterator_create() + * @brief Iterador de listas. Inicializar con `list_iterator_create()` */ typedef struct { t_list *list; @@ -43,9 +48,9 @@ /** * @brief Crea una lista * @return Retorna un puntero a la lista creada, liberable con: - * - list_destroy() si se quiere liberar la lista pero no + * - `list_destroy()` si se quiere liberar la lista pero no * los elementos que contiene. - * - list_destroy_and_destroy_elements() si se quiere liberar + * - `list_destroy_and_destroy_elements()` si se quiere liberar * la lista con los elementos que contiene * * Ejemplo de uso: @@ -108,7 +113,7 @@ /** * @brief Destruye una lista y sus elementos contenidos llamando a la función * `element_destroyer` sobre cada uno de ellos. - * @note En caso de recibir una lista vacía, se comporta como list_destroy(). + * @note En caso de recibir una lista vacía, se comporta como `list_destroy()`. * * Ejemplo de uso: * @code @@ -687,7 +692,7 @@ /** * @brief Quita todos los elementos de la lista y los libera llamando a la * función `element_destroyer` sobre cada uno de ellos - * @note En caso de recibir una lista vacía, se comporta como list_clean(). + * @note En caso de recibir una lista vacía, se comporta como `list_clean()`. * * Ejemplo de uso: * @code @@ -706,7 +711,7 @@ /** * @brief Itera la lista llamando al closure por cada elemento. En caso de * querer modificar la lista durante la iteración, utilizar - * list_iterator_create() para recorrerla externamente. + * `list_iterator_create()` para recorrerla externamente. * * Ejemplo de uso: * @code @@ -1007,8 +1012,8 @@ * @brief Inicializa una iteración externa de la lista. Permite recorrer * la lista y modificarla al mismo tiempo. En caso de * no querer modificar la lista ni romper la iteración, considerar - * utilizar list_iterate(). - * @return Un puntero que debe ser liberado con list_iterator_destroy() + * utilizar `list_iterate()`. + * @return Un puntero que debe ser liberado con `list_iterator_destroy()` * una vez finalizada la iteración. * * Ejemplo de uso: @@ -1034,7 +1039,7 @@ * lo devuelve * @return El elemento actual de la iteración. Pertenecerá a la lista, * por lo que no debe ser liberado por fuera de ésta a menos que - * se lo remueva con list_iterator_remove(). + * se lo remueva con `list_iterator_remove()`. */ void* list_iterator_next(t_list_iterator* iterator); @@ -1053,7 +1058,7 @@ /** * @brief Remueve de la lista al elemento actual de la iteración - * @note El elemento removido es el último devuelto por list_iterator_next() + * @note El elemento removido es el último devuelto por `list_iterator_next()` * y dejará de pertenecer a la lista, por lo que debe ser liberado * una vez que no se lo necesite. */ diff --git a/src/commons/collections/queue.h b/src/commons/collections/queue.h index dba95da..d67579c 100755 --- a/src/commons/collections/queue.h +++ b/src/commons/collections/queue.h @@ -19,9 +19,14 @@ #include "list.h" + /** + * @file + * @brief `#include ` + */ + /** * @struct t_queue - * @brief Estructura que representa una cola. Inicializar con queue_create() + * @brief Estructura que representa una cola. Inicializar con `queue_create()` */ typedef struct { t_list* elements; @@ -30,9 +35,9 @@ /** * @brief Crea una cola * @return Retorna un puntero a la cola creada, liberable con: - * - queue_destroy() si se quiere liberar la cola pero no + * - `queue_destroy()` si se quiere liberar la cola pero no * los elementos que contiene. - * - queue_destroy_and_destroy_elements() si se quiere liberar + * - `queue_destroy_and_destroy_elements()` si se quiere liberar * la cola con los elementos que contiene. */ t_queue *queue_create(void); diff --git a/src/commons/config.h b/src/commons/config.h index abfb57d..6182788 100644 --- a/src/commons/config.h +++ b/src/commons/config.h @@ -19,9 +19,14 @@ #include "collections/dictionary.h" + /** + * @file + * @brief `#include ` + */ + /** * @struct t_config - * @brief Manejo de archivos de configuración. Inicializar con config_create(). + * @brief Manejo de archivos de configuración. Inicializar con `config_create()`. */ typedef struct { char *path; @@ -33,7 +38,7 @@ * @param path Ruta hacia el archivo de configuracion * @return Retorna un puntero hacia la estructura creada, o NULL * en caso de no encontrar el archivo en el path especificado. - * Una vez que se deje de usar, se debe liberar con config_destroy(). + * Una vez que se deje de usar, se debe liberar con `config_destroy()`. */ t_config *config_create(char *path); @@ -67,7 +72,7 @@ /** * @brief Retorna un array con los valores asociados a la key especificada. * @return Devuelve un array de strings terminado en NULL. Debe ser liberado - * con string_array_destroy() una vez que se deje de usar. + * con `string_array_destroy()` una vez que se deje de usar. * * @note En el archivo de configuracion un valor de este tipo debería ser representado * de la siguiente forma [lista_valores_separados_por_coma]. Ejemplo: diff --git a/src/commons/log.h b/src/commons/log.h index 8646bc6..c50f91f 100644 --- a/src/commons/log.h +++ b/src/commons/log.h @@ -20,6 +20,10 @@ #include #include + /** + * @file + * @brief `#include ` + */ typedef enum { LOG_LEVEL_TRACE, //!< Loguea todos los mensajes @@ -49,7 +53,7 @@ * @param is_active_console: Si lo que se loguea debe mostrarse por consola * @param level: El nivel de detalle mínimo a loguear (ver definición de t_log_level) * @return Retorna una instancia de logger, o NULL en caso de error. Debe ser - * liberada con log_destroy() + * liberada con `log_destroy()` * * @note Se debe tener en cuenta que: * - si `file` es NULL, no se imprimirá en ningún archivo diff --git a/src/commons/memory.h b/src/commons/memory.h index f19a37f..dab9cd1 100644 --- a/src/commons/memory.h +++ b/src/commons/memory.h @@ -22,6 +22,11 @@ #include #include "string.h" + /** + * @file + * @brief `#include ` + */ + /* amount of hex columns of dump */ #define HEXDUMP_COLS 16 /* amount of hex columns allow without a separator */ @@ -29,7 +34,7 @@ /** * @brief Devuelve un dump hexadecimal en formato string de una porción de memoria dada - * @return Un string con el dump hexadecimal. Debe ser liberado con free() + * @return Un string con el dump hexadecimal. Debe ser liberado con `free()` */ char *mem_hexstring(void *source, size_t length); diff --git a/src/commons/process.h b/src/commons/process.h index 47d5c61..ddfdeb2 100644 --- a/src/commons/process.h +++ b/src/commons/process.h @@ -17,14 +17,19 @@ #ifndef PROCESS_H_ #define PROCESS_H_ +/** + * @file + * @brief `#include ` + */ + /** * @brief Obtiene el ID del thread actual */ -unsigned int process_get_thread_id(); +unsigned int process_get_thread_id(void); /** * @brief Obtiene el ID del proceso actual */ -unsigned int process_getpid(); +unsigned int process_getpid(void); #endif /* PROCESS_H_ */ diff --git a/src/commons/string.h b/src/commons/string.h index 6c03b7f..7b54d52 100644 --- a/src/commons/string.h +++ b/src/commons/string.h @@ -20,16 +20,21 @@ #include #include + /** + * @file + * @brief `#include ` + */ + /** * @brief Crea un string vacio - * @return El string retornado debe ser liberado con free() + * @return El string retornado debe ser liberado con `free()` */ char* string_new(void); /** * @brief Crea un string en formato decimal a partir de un número * @param[in] number: Número entero a convertir - * @return El string retornado debe ser liberado con free() + * @return El string retornado debe ser liberado con `free()` * * @code * char* numero = string_itoa(123); @@ -41,8 +46,8 @@ /** * @brief Crea un nuevo string a partir de un formato especificado - * @param[in] format: Formato a aplicar, igual que en printf() - * @return El string retornado debe ser liberado con free() + * @param[in] format: Formato a aplicar, igual que en `printf()` + * @return El string retornado debe ser liberado con `free()` * * @code * char* saludo = string_from_format("Hola %s", "mundo"); @@ -55,9 +60,9 @@ /** * @brief Crea un nuevo string a partir de un formato especificado * pasando un `va_list` con los argumentos - * @param[in] format: Formato a aplicar, igual que en vprintf() - * @param[in] arguments: Lista de argumentos a aplicar, igual que en vprintf() - * @return Retorna un string que debe ser liberado con free() + * @param[in] format: Formato a aplicar, igual que en `vprintf()` + * @param[in] arguments: Lista de argumentos a aplicar, igual que en `vprintf()` + * @return Retorna un string que debe ser liberado con `free()` */ char* string_from_vformat(const char* format, va_list arguments); @@ -65,7 +70,7 @@ * @brief Crea un string de longitud `count` con el mismo caracter. * @param[in] ch: Caracter a repetir * @param[in] count: Cantidad de veces a repetir el caracter - * @return El string retornado debe ser liberado con free() + * @return El string retornado debe ser liberado con `free()` * * @code * string_repeat('a', 5) = "aaaaa" @@ -76,7 +81,7 @@ /** * @brief Agrega al primer string el segundo * @param[in,out] original: Puntero al string al que se le va a concatenar el - * segundo. Debe apuntar a un puntero liberable con free() + * segundo. Debe apuntar a un puntero liberable con `free()` * @param[in] string_to_add: String a concatenar. Admite todo tipo de strings * * @code @@ -92,7 +97,7 @@ /** * @brief Agrega al primer string un máximo de n caracteres del segundo. * @param[in,out] original: Puntero al string a modificar. Debe apuntar a un - * string liberable con free() + * string liberable con `free()` * @param[in] string_to_add: String a concatenar. Admite todo tipo de strings * @param[in] n: Cantidad máxima de caracteres a concatenar * @@ -110,8 +115,8 @@ * @brief Concatena al primer string el resultado de aplicar los parametros * al formato especificado * @param[in,out] original: Puntero al string a modificar. Debe apuntar a un - * string liberable con free() - * @param[in] format: Formato a aplicar, igual que en printf() + * string liberable con `free()` + * @param[in] format: Formato a aplicar, igual que en `printf()` * * @code * char *saludo = "HOLA "; @@ -127,7 +132,7 @@ /** * @brief Retorna una copia del string pasado como argumento * @param[in] original: String a duplicar. Admite todo tipo de strings - * @return El string retornado debe ser liberado con free() + * @return El string retornado debe ser liberado con `free()` * * @code * char* copia = string_duplicate("hola"); @@ -192,7 +197,7 @@ /** * @brief Remueve todos los caracteres vacios de la derecha y la izquierda * @param[in,out] text: Puntero al string a modificar. Debe apuntar a un string - * liberable con free() + * liberable con `free()` * * @code * char* heap_string = string_duplicate(" hola "); @@ -207,7 +212,7 @@ /** * @brief Remueve todos los caracteres vacios de la izquierda * @param[in,out] text: Puntero al string a modificar. Debe apuntar a un string - * liberable con free() + * liberable con `free()` * * @code * char* heap_string = string_duplicate(" hola"); @@ -222,7 +227,7 @@ /** * @brief Remueve todos los caracteres vacios de la derecha * @param[in,out] text: Puntero al string a modificar. Debe apuntar a un string - * liberable con free() + * liberable con `free()` * * @code * char* heap_string = string_duplicate("hola "); @@ -300,7 +305,7 @@ * @param[in] text: String a separar. Admite todo tipo de strings * @param[in] separator: Separador a utilizar. Admite todo tipo de strings * @return Retorna un array con cada palabra y en la última posición un NULL. - * Debe ser liberado con string_array_destroy() + * Debe ser liberado con `string_array_destroy()` * * @code * string_split("hola, mundo", ",") => {"hola", " mundo", NULL} @@ -314,7 +319,7 @@ * @param[in] n: Cantidad máxima de veces que se puede separar * @param[in] separator: String separador a utilizar. Admite todo tipo de strings * @return Retorna un array de copias de los caracteres en text y en la última - * posición un NULL. Debe ser liberado con string_array_destroy() + * posición un NULL. Debe ser liberado con `string_array_destroy()` * * @code * string_n_split("hola, mundo, bueno", 2, ",") => ["hola", " mundo, bueno", NULL] @@ -331,7 +336,7 @@ * tipo de strings * @param[in] start: Indice desde el cual se obtiene el substring * @param[in] length: Cantidad de caracteres a obtener - * @return Retorna un nuevo string que debe ser liberado con free() + * @return Retorna un nuevo string que debe ser liberado con `free()` * * @code * string_substring("hola, mundo, bueno", 0, 4) => "hola" @@ -347,7 +352,7 @@ * @param[in] text: String a partir del cual se obtiene el substring. Admite todo * tipo de strings * @param[in] start: Indice desde el cual se obtiene el substring - * @return Retorna un nuevo string que debe ser liberado con free() + * @return Retorna un nuevo string que debe ser liberado con `free()` */ char* string_substring_from(char *text, int start); @@ -356,7 +361,7 @@ * @param[in] text: String a partir del cual se obtiene el substring. Admite todo * tipo de strings * @param[in] length: Cantidad de caracteres a obtener - * @return Retorna un nuevo string que debe ser liberado con free() + * @return Retorna un nuevo string que debe ser liberado con `free()` */ char* string_substring_until(char *text, int length); @@ -371,7 +376,7 @@ * @brief Retorna un array de strings a partir de un string formateado como array * @param[in] text: String a convertir. Admite todo tipo de strings * @return Retorna un array de copias de los caracteres en text y en la última - * posición un NULL. Debe ser liberado con string_array_destroy() + * posición un NULL. Debe ser liberado con `string_array_destroy()` * * @code * char* array_string = "[1,2,3,4]" @@ -384,7 +389,7 @@ * @brief Retorna el texto invertido. No se maneja el caso de NULL, * si se pasa NULL su comportamiento no esta determinado. * @param[in] text: String a invertir. Admite todo tipo de strings - * @return Retorna un nuevo string que debe ser liberado con free() + * @return Retorna un nuevo string que debe ser liberado con `free()` * * @code * char* original = "boo"; @@ -399,7 +404,7 @@ * @param[in] text: String a modificar. Admite todo tipo de strings * @param[in] substring: Substring a reemplazar. Admite todo tipo de strings * @param[in] replacement: String a insertar. Admite todo tipo de strings - * @return Retorna un nuevo string que debe ser liberado con free() + * @return Retorna un nuevo string que debe ser liberado con `free()` * * @code * char* original = "hello"; @@ -419,9 +424,9 @@ /** * @brief Crea un array de strings vacio - * @return El array retornado debe ser liberado con string_array_destroy() + * @return El array retornado debe ser liberado con `string_array_destroy()` */ - char** string_array_new(); + char** string_array_new(void); /** * @brief Destruye un array con sus strings @@ -464,7 +469,7 @@ * @param[in] pos: Posición del string a reemplazar * @param[in] text: Nuevo string a insertar. Debe ser liberable con free(), pero * pasa a formar parte del array, por lo que no debe ser liberado - * @return El string reemplazado. Debe ser liberado con free() + * @return El string reemplazado. Debe ser liberado con `free()` */ char* string_array_replace(char** array, int pos, char* text); @@ -473,7 +478,7 @@ * @param[in,out] array: Array a modificar. Debe apuntar a un array de strings * terminado en NULL * @return El string quitado. Deja de pertenecer al array, por lo que debe ser - * liberado con free() + * liberado con `free()` */ char* string_array_pop(char** array); diff --git a/src/commons/temporal.h b/src/commons/temporal.h index 3530405..dc16a09 100644 --- a/src/commons/temporal.h +++ b/src/commons/temporal.h @@ -19,6 +19,11 @@ #include #include + /** + * @file + * @brief `#include ` + */ + /** * @enum t_temporal_status Estado del cronómetro */ @@ -29,7 +34,7 @@ /** * @struct t_temporal - * @brief Manejo de tiempo con cronómetro. Inicializar con temporal_create(). + * @brief Manejo de tiempo con cronómetro. Inicializar con `temporal_create()`. */ typedef struct { struct timespec current; @@ -39,7 +44,7 @@ /** * @brief Retorna un string con la hora actual con el formato recibido por parámetro. - * @return El string retornado debe ser liberado con free() al dejar de usarse. + * @return El string retornado debe ser liberado con `free()` al dejar de usarse. * * @code * temporal_get_string_time("%d/%m/%y") => "30/09/20" @@ -51,7 +56,7 @@ /** * @brief Crea una variable temporal e inicia su cronómetro. - * @return La variable temporal creada debe ser liberada con temporal_destroy(). + * @return La variable temporal creada debe ser liberada con `temporal_destroy()`. */ t_temporal* temporal_create(void); diff --git a/src/commons/txt.h b/src/commons/txt.h index 1f8e0de..cb285f6 100644 --- a/src/commons/txt.h +++ b/src/commons/txt.h @@ -19,9 +19,14 @@ #include +/** + * @file + * @brief `#include ` + */ + /** * @brief Abre un archivo para agregarle contenido al final -* @note El mismo se debe cerrar con txt_close_file() +* @note El mismo se debe cerrar con `txt_close_file()` */ FILE* txt_open_for_append(char* path);