From 0229468cc560a82cca90426ce3f498872c949935 Mon Sep 17 00:00:00 2001
From: Sergio Valor <jaildesigner@gmail.com>
Date: Mon, 20 Apr 2026 12:28:17 +0200
Subject: [PATCH] =?UTF-8?q?docs(core/audio):=20unificar=20comentaris=20a?=
 =?UTF-8?q?=20catal=C3=A0=20(INCONS-03)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Els comentaris d'audio.hpp i audio.cpp barrejaven castellà i català —
"Reproduce la música", "Detener", "Estado de la música"... conviven amb
"Reproduir", "Aturar", "Estat". Unifico tot a català, incloent-hi:

  - Comentaris d'includes ("Para X" → "Per a X").
  - Secció headers ("// --- Configuración general ---" → "// --- Configuració
    general ---").
  - Descripcions de mètodes i membres.
  - Comentaris de l'enum Group/MusicState.

Els comentaris que ja estaven en català (els afegits a la mateixa
auditoria i els preexistents) no es toquen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/audit-core-audio.md    |   2 +-
 source/core/audio/audio.cpp |  32 ++++++------
 source/core/audio/audio.hpp | 100 ++++++++++++++++++------------------
 3 files changed, 67 insertions(+), 67 deletions(-)

diff --git a/docs/audit-core-audio.md b/docs/audit-core-audio.md
index 8fecae9..0f5d44e 100644
--- a/docs/audit-core-audio.md
+++ b/docs/audit-core-audio.md
@@ -72,7 +72,7 @@ Los IDs se mantienen estables una vez asignados. Cada entrada apunta al(los) fic
 |----|---------------|----------|-----------|--------|-------|
 | INCONS-01 | `audio.cpp:128,135,142,149,172,180` | Métodos `const` que mutan globals de `Ja` (const miente) | Importante | DONE | `const` tret de 6 mètodes (`playSound` x2, `stopAllSounds`, `fadeOutMusic`, `setSoundVolume`, `setMusicVolume`). `effectiveVolume` es queda `const` (pur sobre membres). Cap caller extern via `const Audio*` |
 | INCONS-02 | `audio.hpp:44-48` + `jail_audio.hpp:44-50` | Dos `MusicState` paralelos + `getRealMusicState` como puente | Importante | DONE | Eliminat `music_.state` (cache) i `getRealMusicState`. `getMusicState()` consulta Ja::* directament i projecta INVALID/DISABLED → STOPPED. La font de veritat passa a ser Ja. `update()` ja no necessita sincronització |
-| INCONS-03 | `audio.cpp` varios | Comentarios mezclan catalán y español | Menor | PENDING | Unificar a catalán |
+| INCONS-03 | `audio.cpp` varios | Comentarios mezclan catalán y español | Menor | DONE | Tots els comentaris en castellà passats a català (incloent-hi els dels enums, constants, `--- Secció ---`, includes `Per a ...`, variables membre). Resta els comentaris en català que ja hi eren |
 | INCONS-04 | `audio.hpp:70,78` | `playMusic` `loop=-1` vs `playSound` `loop=0` | Menor | WONTFIX | Convención razonable (música loop / sonido one-shot); documentar |
 | INCONS-05 | `audio.hpp:102-105` | 4 formas de enable/disable sound (API redundante) + divergencia con `Ja::enableSound` | Importante | DONE (parcial) | 4 variants no-arg eliminades. La divergència amb `Ja::enableSound/enableMusic` es manté: Audio silencia per gain, Ja pararia els canals; la decisió es posposa a COUP-01 |
 
diff --git a/source/core/audio/audio.cpp b/source/core/audio/audio.cpp
index 445b801..c393dc6 100644
--- a/source/core/audio/audio.cpp
+++ b/source/core/audio/audio.cpp
@@ -1,9 +1,9 @@
 #include "core/audio/audio.hpp"
 
-#include <SDL3/SDL.h>  // Para SDL_GetError, SDL_Init
+#include <SDL3/SDL.h>  // Per a SDL_GetError, SDL_Init
 
-#include <algorithm>  // Para clamp
-#include <cstdio>     // Para std::fprintf
+#include <algorithm>  // Per a clamp
+#include <cstdio>     // Per a std::fprintf
 
 // Implementació de stb_vorbis (ha d'anar ABANS d'incloure jail_audio.hpp).
 // clang-format off
@@ -20,9 +20,9 @@
 #undef PLAYBACK_RIGHT
 // clang-format on
 
-#include "core/audio/audio_adapter.hpp"  // Para AudioResource::getMusic/getSound
-#include "core/audio/jail_audio.hpp"     // Para Ja::* (engine jailgames)
-#include "utils/defaults.hpp"            // Para Defaults::Audio::FREQUENCY
+#include "core/audio/audio_adapter.hpp"  // Per a AudioResource::getMusic/getSound
+#include "core/audio/jail_audio.hpp"     // Per a Ja::* (motor jailgames)
+#include "utils/defaults.hpp"            // Per a Defaults::Audio::FREQUENCY
 
 // Invariant compile-time: tots els valors d'Audio::Group han de cabre als slots
 // de volum per grup que manté l'engine. Si s'afegeix una nova entrada a Group
@@ -36,10 +36,10 @@ std::unique_ptr<Audio> Audio::instance;
 // Inicialitza la instància única del singleton amb la configuració rebuda
 void Audio::init(const Config& config) { Audio::instance = std::unique_ptr<Audio>(new Audio(config)); }
 
-// Libera la instancia
+// Allibera la instància
 void Audio::destroy() { Audio::instance.reset(); }
 
-// Obtiene la instancia
+// Obté la instància
 auto Audio::get() -> Audio* { return Audio::instance.get(); }
 
 // Constructor
@@ -51,13 +51,13 @@ Audio::~Audio() {
     Ja::quit();
 }
 
-// Método principal: l'estat de la música el manté Ja (única font de veritat),
+// Mètode principal: l'estat de la música el manté Ja (única font de veritat),
 // per tant no cal cap sincronització aquí.
 void Audio::update() {
     Ja::update();
 }
 
-// Reproduce la música por nombre (con crossfade opcional)
+// Reprodueix la música per nom (amb crossfade opcional)
 void Audio::playMusic(const std::string& name, const int loop, const int crossfade_ms) {
     const bool NEW_LOOP = (loop != 0);
 
@@ -75,7 +75,7 @@ void Audio::playMusic(const std::string& name, const int loop, const int crossfa
     music_.name = name;
 }
 
-// Reproduce la música por puntero (con crossfade opcional)
+// Reprodueix la música per punter (amb crossfade opcional)
 void Audio::playMusic(Ja::Music* music, const int loop, const int crossfade_ms) {
     if (!music_enabled_ || music == nullptr) { return; }
 
@@ -128,7 +128,7 @@ void Audio::stopMusic() {
     }
 }
 
-// Reproduce un sonido por nombre
+// Reprodueix un so per nom
 // NOLINTNEXTLINE(readability-make-member-function-const) — muta globals de Ja::channels
 void Audio::playSound(const std::string& name, Group group) {
     if (sound_enabled_) {
@@ -136,7 +136,7 @@ void Audio::playSound(const std::string& name, Group group) {
     }
 }
 
-// Reproduce un sonido por puntero directo
+// Reprodueix un so per punter directe
 // NOLINTNEXTLINE(readability-make-member-function-const) — muta globals de Ja::channels
 void Audio::playSound(Ja::Sound* sound, Group group) {
     if (sound_enabled_ && sound != nullptr) {
@@ -144,7 +144,7 @@ void Audio::playSound(Ja::Sound* sound, Group group) {
     }
 }
 
-// Detiene todos los sonidos
+// Atura tots els sons
 // NOLINTNEXTLINE(readability-make-member-function-const) — muta globals de Ja::channels
 void Audio::stopAllSounds() {
     if (sound_enabled_) {
@@ -152,7 +152,7 @@ void Audio::stopAllSounds() {
     }
 }
 
-// Realiza un fundido de salida de la música
+// Fa una fosa de sortida de la música
 // NOLINTNEXTLINE(readability-make-member-function-const) — muta Ja::outgoing_music/incoming_fade
 void Audio::fadeOutMusic(int milliseconds) {
     if (music_enabled_ && getMusicState() == MusicState::PLAYING) {
@@ -197,7 +197,7 @@ void Audio::setMusicVolume(float music_volume) {
     Ja::setMusicVolume(effectiveVolume(music_volume, music_enabled_));
 }
 
-// Aplica una nova configuració (substitueix la cache i reaplica enables/volums)
+// Aplica una nova configuració (substitueix la config cachejada i reaplica enables/volums)
 void Audio::applySettings(const Config& config) {
     config_ = config;
     sound_enabled_ = config_.sound_enabled;
diff --git a/source/core/audio/audio.hpp b/source/core/audio/audio.hpp
index 6f0e6cc..4d21c2f 100644
--- a/source/core/audio/audio.hpp
+++ b/source/core/audio/audio.hpp
@@ -1,10 +1,10 @@
 #pragma once
 
-#include <cmath>    // Para std::lround
-#include <cstdint>  // Para int8_t, uint8_t
-#include <memory>   // Para std::unique_ptr
-#include <string>   // Para string
-#include <utility>  // Para move
+#include <cmath>    // Per a std::lround
+#include <cstdint>  // Per a int8_t, uint8_t
+#include <memory>   // Per a std::unique_ptr
+#include <string>   // Per a string
+#include <utility>  // Per a move
 
 // Forward-declares per no incloure core/audio/jail_audio.hpp al header (conté
 // l'engine complet de streaming amb stb_vorbis).
@@ -13,7 +13,7 @@ namespace Ja {
     struct Sound;
 }  // namespace Ja
 
-// --- Clase Audio: gestor de audio (singleton) ---
+// --- Classe Audio: gestor d'àudio (singleton) ---
 // Port del subsistema d'àudio del projecte ../aee, desacoblat d'Options:
 // la configuració entra per la struct Audio::Config a init()/applySettings(),
 // en lloc de llegir directament Options::audio. Això deixa audio.cpp independent
@@ -36,49 +36,49 @@ class Audio {
 
     // --- Enums ---
     enum class Group : std::int8_t {
-        ALL = -1,      // Todos los grupos
-        GAME = 0,      // Sonidos del juego
-        INTERFACE = 1  // Sonidos de la interfaz
+        ALL = -1,      // Tots els grups
+        GAME = 0,      // Sons del joc
+        INTERFACE = 1  // Sons de la interfície
     };
 
     enum class MusicState : std::uint8_t {
-        PLAYING,  // Reproduciendo música
+        PLAYING,  // Reproduint música
         PAUSED,   // Música pausada
-        STOPPED,  // Música detenida
+        STOPPED,  // Música aturada
     };
 
-    // --- Constantes ---
-    static constexpr float MAX_VOLUME = 1.0F;  // Volumen máximo (float 0..1)
-    static constexpr float MIN_VOLUME = 0.0F;  // Volumen mínimo (float 0..1)
+    // --- Constants ---
+    static constexpr float MAX_VOLUME = 1.0F;  // Volum màxim (float 0..1)
+    static constexpr float MIN_VOLUME = 0.0F;  // Volum mínim (float 0..1)
 
     // --- Singleton ---
     static void init(const Config& config);  // Inicialitza amb la configuració rebuda
-    static void destroy();                   // Libera el objeto Audio
-    static auto get() -> Audio*;             // Obtiene el puntero al objeto Audio
+    static void destroy();                   // Allibera l'objecte Audio
+    static auto get() -> Audio*;             // Obté el punter a l'objecte Audio
     ~Audio();                                // Destructor (públic per a std::unique_ptr)
-    Audio(const Audio&) = delete;            // Evitar copia
+    Audio(const Audio&) = delete;            // Evitar còpia
     Audio(Audio&&) = delete;
-    auto operator=(const Audio&) -> Audio& = delete;  // Evitar asignación
+    auto operator=(const Audio&) -> Audio& = delete;  // Evitar assignació
     auto operator=(Audio&&) -> Audio& = delete;
 
-    static void update();  // Actualización del sistema de audio
+    static void update();  // Actualització del sistema d'àudio
 
     // --- Control de música ---
-    void playMusic(const std::string& name, int loop = -1, int crossfade_ms = 0);  // Reproducir música por nombre (con crossfade opcional)
-    void playMusic(Ja::Music* music, int loop = -1, int crossfade_ms = 0);         // Reproducir música por puntero (con crossfade opcional)
-    void pauseMusic();                                                             // Pausar reproducción de música
+    void playMusic(const std::string& name, int loop = -1, int crossfade_ms = 0);  // Reproduir música per nom (amb crossfade opcional)
+    void playMusic(Ja::Music* music, int loop = -1, int crossfade_ms = 0);         // Reproduir música per punter (amb crossfade opcional)
+    void pauseMusic();                                                             // Pausar la reproducció de música
     void resumeMusic();                                                            // Continua la música pausada
-    void stopMusic();                                                              // Detener completamente la música
-    void fadeOutMusic(int milliseconds);                                           // Fundido de salida de la música (muta globals de Ja)
+    void stopMusic();                                                              // Aturar completament la música
+    void fadeOutMusic(int milliseconds);                                           // Fosa de sortida de la música (muta globals de Ja)
 
-    // --- Control de sonidos ---
-    void playSound(const std::string& name, Group group = Group::GAME);  // Reproducir sonido puntual por nombre (muta globals de Ja)
-    void playSound(Ja::Sound* sound, Group group = Group::GAME);         // Reproducir sonido puntual por puntero (muta globals de Ja)
-    void stopAllSounds();                                                // Detener todos los sonidos (muta globals de Ja)
+    // --- Control de sons ---
+    void playSound(const std::string& name, Group group = Group::GAME);  // Reproduir so puntual per nom (muta globals de Ja)
+    void playSound(Ja::Sound* sound, Group group = Group::GAME);         // Reproduir so puntual per punter (muta globals de Ja)
+    void stopAllSounds();                                                // Aturar tots els sons (muta globals de Ja)
 
-    // --- Control de volumen (API interna: float 0.0..1.0) ---
-    void setSoundVolume(float volume, Group group = Group::ALL);  // Ajustar volumen de efectos
-    void setMusicVolume(float volume);                            // Ajustar volumen de música
+    // --- Control de volum (API interna: float 0.0..1.0) ---
+    void setSoundVolume(float volume, Group group = Group::ALL);  // Ajusta el volum dels efectes
+    void setMusicVolume(float volume);                            // Ajusta el volum de la música
 
     // --- Helpers de conversió per a la capa de presentació ---
     // UI (menús, notificacions) manega enters 0..100; internament viu float 0..1.
@@ -90,20 +90,20 @@ class Audio {
         return static_cast<float>(percent) / 100.0F;
     }
 
-    // --- Configuración general ---
-    void enable(bool value);                     // Establecer estado general (reaplica volums)
-    void toggleEnabled() { enable(!enabled_); }  // Alternar estado general (reaplica volums)
+    // --- Configuració general ---
+    void enable(bool value);                     // Estableix l'estat general (reaplica volums)
+    void toggleEnabled() { enable(!enabled_); }  // Alterna l'estat general (reaplica volums)
     void applySettings(const Config& config);    // Aplica una nova configuració
 
-    // --- Configuración de sonidos ---
-    void enableSound(bool value);                         // Establecer estado de sonidos (reaplica volum)
-    void toggleSound() { enableSound(!sound_enabled_); }  // Alternar estado de sonidos (reaplica volum)
+    // --- Configuració de sons ---
+    void enableSound(bool value);                         // Estableix l'estat dels sons (reaplica volum)
+    void toggleSound() { enableSound(!sound_enabled_); }  // Alterna l'estat dels sons (reaplica volum)
 
-    // --- Configuración de música ---
-    void enableMusic(bool value);                         // Establecer estado de música (reaplica volum)
-    void toggleMusic() { enableMusic(!music_enabled_); }  // Alternar estado de música (reaplica volum)
+    // --- Configuració de música ---
+    void enableMusic(bool value);                         // Estableix l'estat de la música (reaplica volum)
+    void toggleMusic() { enableMusic(!music_enabled_); }  // Alterna l'estat de la música (reaplica volum)
 
-    // --- Consultas de estado ---
+    // --- Consultes d'estat ---
     [[nodiscard]] auto isEnabled() const -> bool { return enabled_; }
     [[nodiscard]] auto isSoundEnabled() const -> bool { return sound_enabled_; }
     [[nodiscard]] auto isMusicEnabled() const -> bool { return music_enabled_; }
@@ -111,24 +111,24 @@ class Audio {
     [[nodiscard]] auto getCurrentMusicName() const -> const std::string& { return music_.name; }
 
    private:
-    // --- Tipos anidados ---
+    // --- Tipus anidats ---
     struct Music {
-        std::string name;  // Última pista de música reproducida (buida si es va passar per punter sense filename)
+        std::string name;  // Última pista de música reproduïda (buida si es va passar per punter sense filename)
         bool loop{false};  // Si el play actual és en bucle
     };
 
-    // --- Métodos ---
+    // --- Mètodes ---
     explicit Audio(const Config& config);                                                   // Constructor privat: rep la config
-    void initSDLAudio();                                                                    // Inicializa SDL Audio
+    void initSDLAudio();                                                                    // Inicialitza SDL Audio
     void playMusicInternal(Ja::Music* music, int loop, int crossfade_ms);                   // Camí comú dels dos overloads de playMusic
     [[nodiscard]] auto effectiveVolume(float volume, bool channel_enabled) const -> float;  // Gate master+channel: 0 si algun està off, clamp 0..1 altrament
 
-    // --- Variables miembro ---
+    // --- Variables membre ---
     static std::unique_ptr<Audio> instance;  // Instància única d'Audio
 
     Config config_{};           // Configuració injectada (volums, enables)
-    Music music_;               // Estado de la música
-    bool enabled_{true};        // Estado general del audio
-    bool sound_enabled_{true};  // Estado de los efectos de sonido
-    bool music_enabled_{true};  // Estado de la música
+    Music music_;               // Estat de la música
+    bool enabled_{true};        // Estat general de l'àudio
+    bool sound_enabled_{true};  // Estat dels efectes de so
+    bool music_enabled_{true};  // Estat de la música
 };