feat: ajout commentaire package car

src/model/car/State.java

@@ -2,88 +2,171 @@ package model.car;
 
 import java.util.List;
 
+/**
+ * {@code State} représente l'état dynamique d'un véhicule.
+ *
+ * <p>
+ * Chaque état définit :
+ * <ul>
+ *   <li>la consommation de carburant par tour</li>
+ *   <li>l'intervalle de déplacement possible</li>
+ *   <li>le comportement lors d'une accélération ou décélération</li>
+ *   <li>le comportement spécifique en cas de dégâts</li>
+ * </ul>
+ *
+ * <p>
+ * Ce design correspond au <strong>State Pattern</strong> :
+ * le comportement du véhicule varie selon son état courant
+ * sans avoir recours à des conditions {@code if / switch}.
+ */
 public enum State {
+
     /**
-     * L'état NORMAL du Vehicule avance selon un chiffre au alentour de 1 à 6 cases
-     * par tour. Il consomme 2 unités de carburant à chaque tour. Si l'on
-     * accelere, il passe à l'état BOOST. Si on Rallenti, il passe à l'état LOW.
+     * État NORMAL du véhicule.
+     *
+     * <p>
+     * Le véhicule avance d'un nombre aléatoire de cases
+     * compris entre 1 et 6 inclus.
+     * Il consomme 2 unités de carburant par tour.
+     *
+     * <p>
+     * Transitions possibles :
+     * <ul>
+     *   <li>accélération → {@link #BOOST}</li>
+     *   <li>décélération → {@link #LOW}</li>
+     * </ul>
      */
     NORMAL(2, 1, 6) {
+        @Override
         public State accelerate() {
             return BOOST;
         }
 
+        @Override
         public State decelerate() {
             return LOW;
         }
     },
 
     /**
-     * L'état BOOST du Vehicule avance selon un chiffre au alentour de 5 à 10 cases
-     * par tour. Il consomme 5 unités de carburant à chaque tour. Si l'on
-     * accelere, il reste sur son état et indique un message sur le tableau de bord.
-     * Si on Rallenti, il passe à l'état LOW.
+     * État BOOST du véhicule.
+     *
+     * <p>
+     * Le véhicule avance rapidement (entre 5 et 10 cases).
+     * Il consomme 5 unités de carburant par tour.
+     *
+     * <p>
+     * Transitions possibles :
+     * <ul>
+     *   <li>accélération → reste en {@link #BOOST}</li>
+     *   <li>décélération → {@link #NORMAL}</li>
+     * </ul>
      */
     BOOST(5, 5, 10) {
+        @Override
         public State accelerate() {
             return this;
         }
 
+        @Override
         public State decelerate() {
             return NORMAL;
         }
     },
 
     /**
-     * L'état LOW du Vehicule avance selon un chiffre au alentour de 1 à 3 cases
-     * par tour. Il consomme 1 unités de carburant à chaque tour. Si l'on
-     * accelere, il passe à l'état NORMAL. Si on Rallenti, il passe à l'état
-     * STOPPED.
+     * État LOW du véhicule.
+     *
+     * <p>
+     * Le véhicule avance lentement (entre 1 et 3 cases).
+     * Il consomme 1 unité de carburant par tour.
+     *
+     * <p>
+     * Transitions possibles :
+     * <ul>
+     *   <li>accélération → {@link #NORMAL}</li>
+     *   <li>décélération → {@link #STOPPED}</li>
+     * </ul>
      */
     LOW(1, 1, 3) {
+        @Override
         public State accelerate() {
             return NORMAL;
         }
 
+        @Override
         public State decelerate() {
             return STOPPED;
         }
     },
 
     /**
-     * L'état STOPPED du Vehicule n'avance pas. Il consomme aucune unités de
-     * carburant à chaque tour. Si l'on
-     * accelere, il passe à l'état LOW. Si on Rallenti, il reste sur son état et
-     * indique un message sur le tableau de bord.
+     * État STOPPED du véhicule.
+     *
+     * <p>
+     * Le véhicule est à l'arrêt :
+     * <ul>
+     *   <li>il n'avance pas</li>
+     *   <li>il ne consomme pas de carburant</li>
+     * </ul>
+     *
+     * <p>
+     * Transitions possibles :
+     * <ul>
+     *   <li>accélération → {@link #LOW}</li>
+     *   <li>décélération → reste en {@link #STOPPED}</li>
+     * </ul>
      */
     STOPPED(0, 0, 0) {
+        @Override
         public State accelerate() {
             return LOW;
         }
 
+        @Override
         public State decelerate() {
             return this;
         }
 
+        /**
+         * Un véhicule arrêté ne se déplace pas.
+         */
         @Override
         public int move(int pos, int jump) {
             return pos;
         }
 
+        /**
+         * Un véhicule arrêté ne consomme pas de carburant.
+         */
         @Override
         public int fuelConsumption(int fuel) {
             return fuel;
         }
     },
+
     /**
-     * L'état STOPPED du Vehicule n'avance pas. Il consomme aucune unités de
-     * carburant à chaque tour. Il reste immobile.
+     * État DAMAGED du véhicule.
+     *
+     * <p>
+     * Le véhicule est endommagé :
+     * <ul>
+     *   <li>il ne se déplace pas</li>
+     *   <li>il ne consomme pas de carburant</li>
+     *   <li>il ignore les accélérations et décélérations</li>
+     * </ul>
+     *
+     * <p>
+     * Cet état est temporaire : après réparation,
+     * le véhicule repasse à l'état {@link #LOW}.
      */
     DAMAGED(0, 0, 0) {
+        @Override
         public State accelerate() {
             return this;
         }
 
+        @Override
         public State decelerate() {
             return this;
         }
@@ -108,39 +191,92 @@ public enum State {
             return LOW;
         }
     };
-    // @formatter:on
 
+    /* ==========================================================
+     * Attributs communs à tous les états
+     * ========================================================== */
+
+    /** Consommation de carburant par tour */
     public final int FUELCOST;
+
+    /** Borne maximale (exclusive) de déplacement */
     public final int MAX;
+
+    /** Borne minimale (inclusive) de déplacement */
     public final int MIN;
 
+    /**
+     * Constructeur interne des états.
+     *
+     * @param fuelCost consommation par tour
+     * @param min déplacement minimal
+     * @param max déplacement maximal (inclus)
+     */
     private State(int fuelCost, int min, int max) {
         this.FUELCOST = fuelCost;
-        this.MAX = max + 1;
         this.MIN = min;
+        this.MAX = max + 1;
     }
 
+    /**
+     * Retourne l'intervalle de déplacement possible pour cet état.
+     *
+     * @return liste contenant [MIN, MAX[
+     */
     public List<Integer> getInterval() {
         return List.of(MIN, MAX);
     }
 
+    /**
+     * Applique la consommation de carburant.
+     *
+     * @param fuel carburant actuel
+     * @return carburant restant
+     */
     public int fuelConsumption(int fuel) {
         return fuel - FUELCOST;
     }
 
+    /**
+     * Calcule la nouvelle position du véhicule.
+     *
+     * @param pos position actuelle
+     * @param jump déplacement calculé
+     * @return nouvelle position
+     */
     public int move(int pos, int jump) {
         return pos + jump;
     }
 
+    /**
+     * Indique si l'état correspond à un véhicule endommagé.
+     *
+     * @return {@code true} si endommagé, sinon {@code false}
+     */
     public boolean isDamaged() {
         return false;
     }
 
+    /**
+     * État à appliquer lorsque les dégâts sont réparés.
+     *
+     * @return nouvel état après réparation
+     */
     public State onDamageEnd() {
         return this;
     }
 
+    /**
+     * Transition lors d'une accélération.
+     *
+     * @return le nouvel état
+     */
     public abstract State accelerate();
 
+    /**
+     * Transition lors d'une décélération.
+     *
+     * @return le nouvel état
+     */
     public abstract State decelerate();
 }