un poquito de documentación

app/src/main/java/com/rodalc/amarracos/main/MainActivity.kt

@@ -16,6 +16,9 @@ import com.rodalc.amarracos.mus.PantallaMus
 import com.rodalc.amarracos.pocha.PantallaPocha
 import com.rodalc.amarracos.ui.theme.AmarracosTheme
 
+/**
+ * Punto de inicio de la aplicación
+ */
 class MainActivity : ComponentActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
@@ -33,6 +36,10 @@ class MainActivity : ComponentActivity() {
     }
 }
 
+
+/**
+ * Función que gestiona el controlador para la navegación entre pantallas.
+ */
 @Composable
 fun MyApp() {
     val navController = rememberNavController()
@@ -47,7 +54,13 @@ fun MyApp() {
     }
 }
 
-@Preview(showBackground = true, widthDp = 640, heightDp = 360)
+/**
+ * Función auxiliar para Preview
+ */
+@Preview(
+    showBackground = true,
+    device = "id:pixel", backgroundColor = 0xFFFFFFFF
+)
 @Composable
 fun GreetingPreview() {
     AmarracosTheme {

app/src/main/java/com/rodalc/amarracos/main/PantallaInicio.kt

@@ -21,6 +21,11 @@ import androidx.navigation.NavController
 import androidx.navigation.compose.rememberNavController
 import com.rodalc.amarracos.ui.theme.AmarracosTheme
 
+/**
+ * Primera pantalla de la aplicación, contiene el menú para navegar por ella.
+ *
+ * @param navController El controlador usado para cambiar entre pantallas.
+ */
 @Composable
 fun PantallaInicio(navController: NavController) {
 
@@ -30,14 +35,14 @@ fun PantallaInicio(navController: NavController) {
         horizontalAlignment = Alignment.CenterHorizontally
     ) {
         Spacer(modifier = Modifier.weight(1f))
+
         Box(
             modifier = Modifier
         ) {
             Text(
                 text = "Amarracos",
                 fontSize = 21.sp,
                 textAlign = TextAlign.Center
-
             )
         }
         Spacer(modifier = Modifier.weight(1f))
@@ -77,7 +82,13 @@ fun PantallaInicio(navController: NavController) {
     }
 }
 
-@Preview(showBackground = true, widthDp = 640, heightDp = 360)
+/**
+ * Función auxiliar para Preview
+ */
+@Preview(
+    showBackground = true,
+    device = "id:pixel", backgroundColor = 0xFFFFFFFF
+)
 @Composable
 fun InicioPreview() {
     val navController = rememberNavController()

app/src/main/java/com/rodalc/amarracos/main/PantallaVacia.kt

@@ -5,6 +5,7 @@ import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.navigation.NavController
 
+// PANTALLA AUXILIAR, VA A SER APISONADA
 @Composable
 fun PantallaVacia(navController: NavController) {
     Button(onClick = { navController.navigate("pantallaInicial") }) {

app/src/main/java/com/rodalc/amarracos/mus/General.kt

@@ -29,6 +29,13 @@ import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import androidx.compose.ui.window.Dialog
 
+/**
+ * Muestra un recuadro con puntos.
+ *
+ * @param puntos Los puntos.
+ * @param pareja El nombre de la pareja.
+ * @param juegos Los juegos ganados por la pareja.
+ */
 @Composable
 fun MarcadorPuntos(puntos: Int, pareja: String, juegos: Int) {
     Column {
@@ -47,6 +54,13 @@ fun MarcadorPuntos(puntos: Int, pareja: String, juegos: Int) {
     }
 }
 
+/**
+ * Mesaje a mostrar cuando una pareja alcanza el máximo de puntos.
+ *
+ * @param juego La partida.
+ * @param ronda La ronda.
+ * @param ganador El ganador de la partida.
+ */
 @Composable
 fun Ganan(
     juego: MutableState<Partida>,
@@ -79,9 +93,15 @@ fun Ganan(
             }
         }
     }
-
 }
 
+/**
+ * Mensaje a mostrar durante un órdago visto.
+ *
+ * @param juego La partida.
+ * @param ronda La ronda.
+ * @param dialog Una lambda.
+ */
 @Composable
 fun Ordago(juego: MutableState<Partida>, ronda: MutableState<Ronda>, dialog: (Boolean) -> Unit) {
     Box(modifier = Modifier) {
@@ -120,6 +140,12 @@ fun Ordago(juego: MutableState<Partida>, ronda: MutableState<Ronda>, dialog: (Bo
     }
 }
 
+/**
+ * Muestra la cuadrícula de envites.
+ *
+ * @param juego La partida.
+ * @param ronda La ronda actual (para resaltarla)
+ */
 @Composable
 fun Envites(juego: MutableState<Partida>, ronda: Ronda) {
     Column {
@@ -139,6 +165,12 @@ fun Envites(juego: MutableState<Partida>, ronda: Ronda) {
     }
 }
 
+/**
+ * La caja de texto con el valor de los envites.
+ *
+ * @param value El valor del envite.
+ * @param focus Si está resaltada o no.
+ */
 @Composable
 fun CajaEnvite(value: Int, focus: Boolean) {
     Box(
@@ -154,6 +186,12 @@ fun CajaEnvite(value: Int, focus: Boolean) {
 
 }
 
+/**
+ * Función para realizar el conteo de puntos tras la ronda.
+ *
+ * @param juego La partida.
+ * @param salir Una lambda para finalizar.
+ */
 @Composable
 fun Conteo(juego: MutableState<Partida>, salir: (Ronda) -> Unit) {
     var dialogPares by remember { mutableStateOf(false) }
@@ -271,6 +309,12 @@ fun Conteo(juego: MutableState<Partida>, salir: (Ronda) -> Unit) {
     }
 }
 
+/**
+ * Funcionalidad específica para contar los puntos de pares.
+ *
+ * @param juego La partida.
+ * @param dialog Un lambda para salir.
+ */
 @Composable
 fun PuntosPares(juego: MutableState<Partida>, dialog: (Boolean) -> Unit) {
     var pares1: Pares by remember { mutableStateOf(Pares.NADA) }
@@ -369,6 +413,12 @@ fun PuntosPares(juego: MutableState<Partida>, dialog: (Boolean) -> Unit) {
     }
 }
 
+/**
+ * Funcionalidad específica para contar los puntos de juego.
+ *
+ * @param juego La partida.
+ * @param dialog Un lambda para salir.
+ */
 @Composable
 fun PuntosJuego(juego: MutableState<Partida>, dialog: (Boolean) -> Unit) {
     var juego1: Juego by remember { mutableStateOf(Juego.NADA) }

app/src/main/java/com/rodalc/amarracos/mus/PantallaMus.kt

@@ -20,7 +20,13 @@ import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.window.Dialog
 
-@Preview(showBackground = true, widthDp = 640, heightDp = 360)
+/**
+ * Gestiona la pantalla del mus.
+ */
+@Preview(
+    showBackground = true,
+    device = "spec:parent=pixel,orientation=landscape", backgroundColor = 0xFFFFFFFF
+)
 @Composable
 fun PantallaMus() {
     val juego = remember { mutableStateOf(Partida()) }
@@ -124,6 +130,9 @@ fun PantallaMus() {
     }
 }
 
+/**
+ * Se encarga de mostrar los botones de las distintas rondas.
+ */
 @Composable
 fun BototesJuego(
     juego: MutableState<Partida>,
@@ -158,6 +167,9 @@ fun BototesJuego(
     }
 }
 
+/**
+ * Muestra los botones del envite no visto.
+ */
 @Composable
 fun BotonesEnviteNoVisto(
     juego: MutableState<Partida>,
@@ -175,6 +187,9 @@ fun BotonesEnviteNoVisto(
     }
 }
 
+/**
+ * Gestiona los envites.
+ */
 @Composable
 fun Envite(
     juego: MutableState<Partida>,

app/src/main/java/com/rodalc/amarracos/pocha/Jugador.kt

@@ -1,8 +1,22 @@
 package com.rodalc.amarracos.pocha
 
+import com.rodalc.amarracos.pocha.Ronda.APUESTAS
+import com.rodalc.amarracos.pocha.Ronda.CONTEO
+import com.rodalc.amarracos.pocha.Ronda.NOMBRES
 import kotlinx.serialization.Serializable
 
 
+/**
+ * Representa un jugador de la pocha, con información relevante como ID, nombre, puntos, apuesta y victorias.
+ *
+ * @property id Identificador único del jugador.
+ * @property nombre Nombre del jugador.
+ * @property puntos Puntos acumulados por el jugador.
+ * @property apuesta Apuesta realizada por el jugador en la ronda actual.
+ * @property victoria Número de manos ganadas en la ronda actual.
+ *
+ * @see Ronda
+ */
 @Serializable
 data class Jugador(
     val id: Int,
@@ -13,6 +27,13 @@ data class Jugador(
 ) {
 }
 
+/**
+ * Define las rondas del juego.
+ *
+ * @property NOMBRES Ronda donde los jugadores ingresan sus nombres.
+ * @property APUESTAS Ronda donde los jugadores realizan sus apuestas.
+ * @property CONTEO Ronda final donde se cuenta el resultado.
+ */
 enum class Ronda {
     NOMBRES,
     APUESTAS,

app/src/main/java/com/rodalc/amarracos/pocha/PantallaPocha.kt

@@ -200,7 +200,7 @@ fun PantallaPocha() {
                         if (state == Ronda.CONTEO) {
                             state = Ronda.APUESTAS
                         } else {
-                            jugadores = undoStack.pop()!!
+                            jugadores = undoStack.pop() ?: jugadores
                             state = Ronda.CONTEO
                         }
 

app/src/main/java/com/rodalc/amarracos/pocha/Utils.kt

@@ -3,9 +3,20 @@ package com.rodalc.amarracos.pocha
 import android.content.Context
 import android.widget.Toast
 
+/**
+ * Un objeto que limita la frecuencia de mostrar toasts en la aplicación.
+ *
+ * Este objeto asegura que los toasts no se muestren con demasiada frecuencia, limitando la frecuencia a un toast por segundo.
+ */
 object ToastRateLimiter {
     private var lastToastTime = 0L
 
+    /**
+     * Muestra un toast con un mensaje específico si ha pasado más de un segundo desde el último toast.
+     *
+     * @param context El contexto de la aplicación o actividad.
+     * @param message El mensaje a mostrar en el toast.
+     */
     fun showToast(context: Context, message: String) {
         val currentTime = System.currentTimeMillis()
         if (currentTime - lastToastTime > 1000) { // Check if more than 1 second has passed

app/src/main/java/com/rodalc/amarracos/storage/StateSaver.kt

@@ -7,25 +7,55 @@ import kotlinx.serialization.json.Json
 import java.io.FileNotFoundException
 import java.io.IOException
 
+/**
+ * Un objeto que proporciona métodos para guardar y cargar el estado de un juego.
+ *
+ * Este objeto se encarga de manejar la persistencia de datos de los jugadores en un archivo JSON.
+ * De momento solo tiene un archivo, para la pocha. En el futuro se generalizará.
+ */
 object StateSaver {
     private var filename = "pocha.json"
 
+    /**
+     * Verifica si el archivo de estado existe en el contexto dado.
+     *
+     * @param context El contexto de la aplicación o actividad.
+     * @return true si el archivo existe, false en caso contrario.
+     */
     fun fileExist(context: Context): Boolean {
         val file = context.getFileStreamPath(filename)
         return file != null && file.exists()
     }
 
+    /**
+     * Elimina el archivo de estado en el contexto dado.
+     *
+     * @param context El contexto de la aplicación o actividad.
+     * @return true si el archivo se eliminó con éxito, false en caso contrario.
+     */
     fun deleteFile(context: Context): Boolean {
         return context.deleteFile(filename)
     }
 
+    /**
+     * Guarda el estado de los jugadores en un archivo JSON.
+     *
+     * @param context El contexto de la aplicación o actividad.
+     * @param jugadores La lista de jugadores a guardar.
+     */
     fun savePocha(context: Context, jugadores: List<Jugador>) {
         val json = Json.encodeToString(jugadores)
         context.openFileOutput(filename, Context.MODE_PRIVATE).use {
             it.write(json.toByteArray())
         }
     }
 
+    /**
+     * Carga el estado de los jugadores desde un archivo JSON.
+     *
+     * @param context El contexto de la aplicación o actividad.
+     * @return La lista de jugadores cargados, o una lista vacía si el archivo no existe o hay un error al leerlo.
+     */
     fun loadPocha(context: Context): List<Jugador> {
         var jugadores: List<Jugador>? = null