Docs: Improved headers (#188)

* config, log, memory, string, temporal, y txt agregados * docs: Quito código de la página principal * Todo medianamente documentado * Listas recontra documentadas, Abrazo * Otro día indentaré como corresponde * Dije que luego indento como se debe * Boeeeeeee * Así está el temporal chicos? * Agrego al pingu * Improve config.h header * Muevo list_add() para arriba * Update log.h * Update list.h * Update temporal.h --------- Co-authored-by: f-and <[email protected]>
sisoputnfrba · Aug 15, 2024 · 13f8356 · 13f8356
1 parent efa64b9
commit 13f8356
Show file tree

Hide file tree

Showing 12 changed files with 1,252 additions and 278 deletions.
diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -51,7 +51,7 @@ PROJECT_BRIEF          = "TADs de uso común en aplicaciones desarrolladas en C"
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           =
+PROJECT_LOGO           = "./favicon-32x32.png"
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
@@ -158,7 +158,7 @@ INLINE_INHERITED_MEMB  = NO
 # shortest path that makes the file name unique will be used
 # The default value is: YES.
 
-FULL_PATH_NAMES        = YES
+FULL_PATH_NAMES        = NO
 
 # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
 # Stripping is only done if one of the specified strings matches the left-hand
@@ -1082,7 +1082,7 @@ SOURCE_BROWSER         = YES
 # classes and enums directly into the documentation.
 # The default value is: NO.
 
-INLINE_SOURCES         = YES
+INLINE_SOURCES         = NO
 
 # Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any
 # special comment blocks from generated source code fragments. Normal C, C++ and

diff --git a/docs/favicon-32x32.png b/docs/favicon-32x32.png
diff --git a/src/commons/collections/dictionary.h b/src/commons/collections/dictionary.h
@@ -35,95 +35,114 @@
 	} t_dictionary;
 
 	/**
-	* @brief Crea el diccionario
-	* @relates t_dictionary
-	*/
-	t_dictionary *dictionary_create();
-
-	/**
-	* @brief Inserta un nuevo par (key->element) al diccionario, en caso de ya existir la key actualiza el elemento.
-	* @relates t_dictionary
-	*
-	* @warning Tener en cuenta que esto no va a liberar la memoria del `element` original.
-	*/
-	void 		  dictionary_put(t_dictionary *, char *key, void *element);
+	 * @brief Crea el diccionario
+	 * @return Devuelve un puntero al diccionario creado, liberable con:
+	 *         - dictionary_destroy() si se quiere liberar el diccionario pero no
+	 *           los elementos que contiene.
+	 *         - dictionary_destroy_and_destroy_elements() si se quieren liberar
+	 *           el diccionario con los elementos que contiene.
+	 * @relates t_dictionary
+	 */
+	t_dictionary *dictionary_create(void);
+
+	/**
+	 * @brief Inserta un nuevo par (key->element) al diccionario, en caso de ya
+	 *        existir la key actualiza el elemento.
+	 * @param[in] key La clave del elemento. Una copia de la clave será almacenada
+	 *                en el diccionario, por lo que no se afectará a la original.
+	 * @param[in] element El elemento a insertar. Este elemento pasará a pertenecer
+	 *            al diccionario, por lo que no debe ser liberado por fuera de éste.
+	 * @relates t_dictionary
+	 *
+	 * @warning Tener en cuenta que esto no va a liberar la memoria del `element` original.
+	 */
+	void          dictionary_put(t_dictionary *, char *key, void *element);
 
 	/**
-	* @brief Obtiene el elemento asociado a la key.
-	* @relates t_dictionary
-	*/
-	void 		 *dictionary_get(t_dictionary *, char *key);
+	 * @brief Obtiene el elemento asociado a la key.
+	 * @return Devuelve un puntero perteneciente al diccionario, o NULL si no existe.
+	 *         Este puntero no debe ser liberado por fuera del diccionario.
+	 * @relates t_dictionary
+	 */
+	void         *dictionary_get(t_dictionary *, char *key);
 
 	/**
-	* @brief Remueve un elemento del diccionario y lo retorna.
-	* @relates t_dictionary
-	*/
-	void 		 *dictionary_remove(t_dictionary *, char *key);
+	 * @brief Remueve un elemento del diccionario y lo retorna.
+	 * @return Devuelve un puntero al elemento removido, o NULL si no existe.
+	 *         Al haberse removido, debe ser liberado por fuera del diccionario en
+	 *         caso de ser necesario.
+	 * @relates t_dictionary
+	 */
+	void         *dictionary_remove(t_dictionary *, char *key);
 
 	/**
-	* @brief Remueve un elemento del diccionario y lo destruye.
-	* @relates t_dictionary
-	*/
-	void 		  dictionary_remove_and_destroy(t_dictionary *, char *, void(*element_destroyer)(void*));
+	 * @brief Remueve un elemento del diccionario y lo destruye llamando a la función
+	 *        `element_destroyer` pasada por parámetro.
+	 * @relates t_dictionary
+	 */
+	void          dictionary_remove_and_destroy(t_dictionary *, char *, void(*element_destroyer)(void*));
 
 	/**
-	* @brief Aplica closure a todos los elementos del diccionario.
-	* @relates t_dictionary
-	*/
-	void 		  dictionary_iterator(t_dictionary *, void(*closure)(char* key, void* element));
+	 * @brief Aplica `closure` a todos los elementos del diccionario.
+	 * @relates t_dictionary
+	 */
+	void          dictionary_iterator(t_dictionary *, void(*closure)(char* key, void* element));
 
 	/**
-	* @brief Quita todos los elementos del diccionario
-	* @relates t_dictionary
-	*/
-	void 		  dictionary_clean(t_dictionary *);
+	 * @brief Quita todos los elementos del diccionario sin liberarlos, dejando el
+	 *        diccionario vacío.
+	 * @relates t_dictionary
+	 */
+	void          dictionary_clean(t_dictionary *);
 
 	/**
-	* @brief Quita todos los elementos del diccionario y los destruye
-	* @relates t_dictionary
-	*/
-	void 		  dictionary_clean_and_destroy_elements(t_dictionary *, void(*element_destroyer)(void*));
+	 * @brief Quita todos los elementos del diccionario y los destruye, dejando el
+	 *        diccionario vacío.
+	 * @relates t_dictionary
+	 */
+	void          dictionary_clean_and_destroy_elements(t_dictionary *, void(*element_destroyer)(void*));
 
 	/**
-	* @brief Retorna true si key se encuentra en el diccionario
-	* @relates t_dictionary
-	*/
-	bool 		  dictionary_has_key(t_dictionary *, char* key);
+	 * @brief Retorna true si `key` se encuentra en el diccionario
+	 * @relates t_dictionary
+	 */
+	bool          dictionary_has_key(t_dictionary *, char* key);
 
 	/**
-	* @brief Retorna true si el diccionario está vacío
-	* @relates t_dictionary
-	*/
-	bool 		  dictionary_is_empty(t_dictionary *);
+	 * @brief Retorna true si el diccionario está vacío
+	 * @relates t_dictionary
+	 */
+	bool          dictionary_is_empty(t_dictionary *);
 
 	/**
-	* @brief Retorna la cantidad de elementos del diccionario
-	* @relates t_dictionary
-	*/
-	int 		  dictionary_size(t_dictionary *);
+	 * @brief Retorna la cantidad de elementos del diccionario
+	 * @relates t_dictionary
+	 */
+	int           dictionary_size(t_dictionary *);
 
 	/**
-	* @brief Retorna todas las keys en una lista
-	* @relates t_dictionary
-	*/
-	t_list 		  *dictionary_keys(t_dictionary *self);
+	 * @brief Retorna todas las keys en una lista
+	 * @relates t_dictionary
+	 */
+	t_list       *dictionary_keys(t_dictionary *self);
 
 	/**
-	* @brief Retorna todos los elementos en una lista
-	* @relates t_dictionary
-	*/
-	t_list 		  *dictionary_elements(t_dictionary *self);
+	 * @brief Retorna todos los elementos en una lista
+	 * @relates t_dictionary
+	 */
+	t_list       *dictionary_elements(t_dictionary *self);
 
 	/**
-	* @brief Destruye el diccionario
-	* @relates t_dictionary
-	*/
-	void 		  dictionary_destroy(t_dictionary *);
+	 * @brief Destruye el diccionario
+	 * @relates t_dictionary
+	 */
+	void          dictionary_destroy(t_dictionary *);
 
 	/**
-	* @brief Destruye el diccionario y destruye sus elementos
-	* @relates t_dictionary
-	*/
-	void 		  dictionary_destroy_and_destroy_elements(t_dictionary *, void(*element_destroyer)(void*));
+	 * @brief Destruye el diccionario y destruye sus elementos
+	 * @note En caso de recibir un diccionario vacío, se comporta como dictionary_destroy()
+	 * @relates t_dictionary
+	 */
+	void          dictionary_destroy_and_destroy_elements(t_dictionary *, void(*element_destroyer)(void*));
 
 #endif /* DICTIONARY_H_ */