refactor: improve and document all modules and Readme.md

This is a major refactoring and documentation effort that touches every module in the project.

- **Exhaustive In-Code Documentation:** Every module script in the `modules/` directory has been updated with detailed comments. This includes header descriptions, explanations for each function, and justifications for complex logic. This greatly improves the maintainability and readability of the code.

- **Code Robustness and Optimization:** Several modules have been refactored to be more robust and efficient. This includes:
  - Optimizing package installations by grouping them into a single `pacman` command.
  - Improving dependency checks.
  - Standardizing the use of helper functions from `common.sh`.
  - Making network operations more resilient.

- **Comprehensive `Readme.md` Update:** The main `Readme.md` has been rewritten to be a complete and professional guide to the project. It now includes:
  - A clear and detailed description of each module.
  - Information on what each module installs and how it works.
  - Instructions for installing the required Nerd Font for `oh-my-posh`.
  - An updated structure that is easier to navigate.

modules/common.sh

@@ -1,53 +1,85 @@
 #!/usr/bin/env bash
 # ===============================================================
-# common.sh - Funciones comunes para los módulos
+# common.sh - Funciones y variables comunes para los módulos
+# ===============================================================
+#
+# Este script define un conjunto de funciones y variables de utilidad
+# que son compartidas por todos los módulos de instalación. El objetivo
+# es estandarizar tareas comunes como mostrar mensajes, manejar
+# paquetes, crear copias de seguridad y gestionar el helper de AUR.
+#
+# No debe ser ejecutado directamente, sino incluido (`source`) por
+# otros scripts.
+#
 # ===============================================================
 
-# Colores para output
+# --- Definición de Colores ---
+# Se definen códigos de escape ANSI para dar formato y color a la
+# salida en la terminal, mejorando la legibilidad.
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 MAGENTA='\033[0;35m'
 CYAN='\033[0;36m'
-NC='\033[0m' # No Color
+NC='\033[0m' # No Color (resetea el formato)
 BOLD='\033[1m'
 
-# Funciones de logging
+# --- Funciones de Logging ---
+# Proporcionan una manera estandarizada de mostrar mensajes al
+# usuario, con diferentes niveles de severidad (info, éxito,
+# advertencia, error) y formato.
+
+# Función interna para limpiar la línea del spinner si está activo.
 _maybe_clear_spinner() {
     if declare -F spinner_clear_line >/dev/null; then
         spinner_clear_line
     fi
 }
 
+# Muestra un mensaje informativo.
 log_info() {
     _maybe_clear_spinner
     echo -e "${BLUE}▶${NC} ${BOLD}$1${NC}"
 }
 
+# Muestra un mensaje de éxito.
 log_success() {
     _maybe_clear_spinner
     echo -e "${GREEN}✓${NC} ${GREEN}$1${NC}"
 }
 
+# Muestra un mensaje de advertencia.
 log_warning() {
     _maybe_clear_spinner
     echo -e "${YELLOW}⚠${NC} ${YELLOW}$1${NC}"
 }
 
+# Muestra un mensaje de error.
 log_error() {
     _maybe_clear_spinner
     echo -e "${RED}✗${NC} ${RED}$1${NC}"
 }
 
+# Muestra un separador visual para marcar el inicio de un paso importante.
 log_step() {
     echo -e "\n${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
     echo -e "${CYAN}${BOLD}  $1${NC}"
     echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n"
 }
 
-# Función para crear una copia de seguridad de un archivo o directorio
-# Uso: backup_file "/ruta/al/archivo"
+# --- Funciones de Utilidad ---
+
+# ---------------------------------------------------------------
+# backup_file(path)
+# ---------------------------------------------------------------
+# Crea una copia de seguridad de un archivo o directorio existente.
+# Añade una marca de tiempo al nombre del backup para evitar
+# sobrescribir copias anteriores.
+#
+# Parámetros:
+#   $1 - Ruta al archivo o directorio a respaldar.
+# ---------------------------------------------------------------
 backup_file() {
     local path_to_backup="$1"
     if [[ -e "$path_to_backup" ]]; then
@@ -64,17 +96,29 @@ backup_file() {
     return 0
 }
 
-# Función para verificar si un comando existe
+# ---------------------------------------------------------------
+# command_exists(command)
+# ---------------------------------------------------------------
+# Verifica si un comando está disponible en el PATH del sistema.
+#
+# Parámetros:
+#   $1 - Nombre del comando a verificar.
+# ---------------------------------------------------------------
 command_exists() {
     command -v "$1" >/dev/null 2>&1
 }
 
-# Función para verificar e instalar un paquete con pacman
-# Uso: check_and_install_pkg "nombre-del-paquete"
+# ---------------------------------------------------------------
+# check_and_install_pkg(package_name)
+# ---------------------------------------------------------------
+# Comprueba si un paquete ya está instalado con pacman. Si no lo
+# está, intenta instalarlo.
+#
+# Parámetros:
+#   $1 - Nombre del paquete a instalar.
+# ---------------------------------------------------------------
 check_and_install_pkg() {
     local pkg_name="$1"
-    # pacman -T es una forma de verificar sin instalar, pero no funciona bien con grupos.
-    # pacman -Q es más fiable para paquetes individuales.
     if ! pacman -Q "$pkg_name" &>/dev/null; then
         log_info "Instalando ${pkg_name}..."
         if sudo pacman -S --noconfirm --needed "$pkg_name"; then
@@ -89,8 +133,13 @@ check_and_install_pkg() {
     return 0
 }
 
-
-# Función para instalar helper AUR si no existe
+# ---------------------------------------------------------------
+# ensure_aur_helper()
+# ---------------------------------------------------------------
+# Asegura que un helper de AUR (yay o paru) esté instalado.
+# Si no encuentra ninguno, procede a instalar `yay-bin` desde AUR.
+# Devuelve el nombre del helper encontrado o instalado.
+# ---------------------------------------------------------------
 ensure_aur_helper() {
     if command_exists yay; then
         echo "yay"
@@ -100,6 +149,7 @@ ensure_aur_helper() {
         return 0
     else
         log_warning "No se detectó yay ni paru. Instalando yay..."
+        # Instala `yay-bin` para evitar compilarlo desde cero, lo que es más rápido.
         cd /tmp
         git clone https://aur.archlinux.org/yay-bin.git
         cd yay-bin
@@ -109,6 +159,17 @@ ensure_aur_helper() {
     fi
 }
 
+# ---------------------------------------------------------------
+# aur_install_packages(packages...)
+# ---------------------------------------------------------------
+# Instala una lista de paquetes desde el AUR.
+#
+# Utiliza el helper de AUR (yay o paru) que encuentre o instale.
+# Pasa los flags necesarios para una instalación no interactiva.
+#
+# Parámetros:
+#   $@ - Lista de nombres de paquetes de AUR a instalar.
+# ---------------------------------------------------------------
 aur_install_packages() {
     local packages=("$@")
     if [[ ${#packages[@]} -eq 0 ]]; then
@@ -155,7 +216,12 @@ aur_install_packages() {
     return $status
 }
 
-# Función para actualizar sistema
+# ---------------------------------------------------------------
+# update_system()
+# ---------------------------------------------------------------
+# Sincroniza los repositorios y actualiza todos los paquetes del
+# sistema usando `pacman`.
+# ---------------------------------------------------------------
 update_system() {
     log_step "Actualizando sistema"
     log_info "Sincronizando repositorios y actualizando paquetes..."
@@ -163,10 +229,16 @@ update_system() {
     log_success "Sistema actualizado"
 }
 
-# Función para limpiar paquetes huérfanos
+# ---------------------------------------------------------------
+# cleanup_orphans()
+# ---------------------------------------------------------------
+# Elimina paquetes que fueron instalados como dependencias pero
+# que ya no son requeridos por ningún paquete.
+# ---------------------------------------------------------------
 cleanup_orphans() {
     log_step "Limpieza de paquetes huérfanos"
     log_info "Buscando paquetes huérfanos..."
+    # El `|| true` evita que el script falle si no se encuentran huérfanos.
     sudo pacman -Rns $(pacman -Qtdq) --noconfirm 2>/dev/null || true
     log_success "Limpieza completada"
 }