Aktulizacja i dopisanie dokumentacji do kodu. Usunięcie zbędnych impo…

…rtów, zmiennych, metod.

src/biathlon/Biathlete.java

@@ -1,5 +1,5 @@
 /**
- * Klasy odpowiedzialne za model symulacji.
+ * Podstawowy pakiet symulacji.
  */
 package biathlon;
 
@@ -9,24 +9,39 @@
 import java.util.LinkedList;
 
 /**
- * Klasa reprezentująca poszczególnych zawodników
+ * Klasa reprezentująca poszczególnych zawodników.
  * 
  * @author Artur Hebda
+ * @see biathlon.core.StaggeredEntity
  */
 public class Biathlete extends biathlon.core.StaggeredEntity {
+
     protected LinkedList<LinkedList<Boolean>> shots;
     protected int currentShootingSessionMisses = 0;
     protected int currentLap = 1;
 
+    /**
+     * @see biathlon.core.StaggeredEntity 
+     */
     public Biathlete(Model owner, String name, boolean showInTrace) {
         super(owner, name, showInTrace);
         shots = new LinkedList();
     }
 
+    /**
+     * Dodaje event na obecnym okrążeniu.
+     * @param event reprezentuje event, którego czas musiał zostać zamrożony dla chwili wystąpienia, np. oddanie strzału 
+     */
     public void addEvent(BiathleteEvent event) {
         eventsByLap.get(currentLap - 1).add(event);
     }
 
+    /**
+     * Generuje trace dla zawodnika z przebiegu całego wyścigu.
+     * Przed wywołaniem tej metody należy wywołać analogiczną metodę
+     * dla punktów pomiaru czasu i strzelnicy (ustalenie pozycji i straty do lidera
+     * na danym punkcie).
+     */
     @Override
     public void generateTrace() {
         LinkedList<BiathleteEvent> events;
@@ -67,7 +82,7 @@ public void beginShootingSession() {
         currentShootingSessionMisses = 0;
     }
 
-    /*
+    /**
      * @return lista list true/false oznaczająca, czy zawodnik trafił w kolejnych strzałach w kolejnych seriach
      */
     public LinkedList<LinkedList<Boolean>> getShotResults() {
@@ -85,7 +100,7 @@ public LinkedList<Boolean> getCurrentShootingSession() {
     /**
      * Zapisuje rezultat danego strzału.
      * 
-     * @param hit true - trafione, false - pudło
+     * @param hit true (trafienie), false (pudło)
      */
     public void saveShotResult(boolean hit) {
         getCurrentShootingSession().add(hit);
@@ -96,7 +111,7 @@ public void saveShotResult(boolean hit) {
 
     /**
      * 
-     * @return ilość spudłowanych strzałów w danej serii 
+     * @return ilość niecelnych strzałów w obecnej / ostatniej serii 
      */
     public int countCurrentShootingSessionMisses() {
         return currentShootingSessionMisses;

src/biathlon/Biathlon.java

@@ -2,7 +2,6 @@
 
 import biathlon.checkpoint.Checkpoint;
 import biathlon.event.BiathleteGenerator;
-import biathlon.report.HTMLFileOutput;
 import desmoj.core.dist.BoolDistBernoulli;
 import desmoj.core.dist.ContDistNormal;
 import desmoj.core.dist.ContDistUniform;
@@ -12,7 +11,6 @@
 import desmoj.core.simulator.TimeInstant;
 import desmoj.core.simulator.TimeOperations;
 import desmoj.core.simulator.TimeSpan;
-import java.util.LinkedList;
 import java.util.concurrent.TimeUnit;
 
 /**
@@ -22,28 +20,66 @@
  * 
  */
 public class Biathlon extends Model {
+    /**
+     * dla jak długiego przedziału czasu generować trace.
+     */
     public static int DURATION_IN_MINUTES = 80;
+
     public static int BIATHLETE_COUNT = 30;
     public static int LAPS = 4;
+
+    /**
+     * długość kary za "pudło" na strzelnicy.
+     */
     public static int MISS_PENALTY_IN_SECONDS = 60;
+
+    /**
+     * odstęp czasowy między startem kolejnych zawodników.
+     */
     public static int STAGGERING_IN_SECONDS = 30;
 
     protected Queue<Biathlete> biathletes;
     protected ShootingArea shootingArea;
     protected Queue<Checkpoint> checkpoints;
-    protected LinkedList<HTMLFileOutput> traces;
+
+    /**
+     * stream generujący rezultaty kolejnych strzałów na strzelnicy.
+     */
     protected BoolDistBernoulli shotDistStream;
+
+    /**
+     * stream generujący czas trwania biegu danego zawodnika do kolejnego punktu pomiaru
+     * czasu.
+     * Zakładamy, że punkty pomiaru czasu są rozmieszczone równomiernie (nie dotyczy
+     * dystansu między biathlon.checkpoint.BeforeShootingArea i biathlon.checkpoint.AfterShootingArea,
+     * gdyż całą strzelnicę traktujemy jak jedno miejsce. 
+     */
     protected ContDistNormal checkpointArrivalTimeInMilliSeconds;
+
+    /**
+     * stream generujący czas oddania strzału przez zawodnika.
+     * brak rozróżnienia na pozycje leżącą i stojacą.
+     */
     protected ContDistUniform shotTimeInMilliSeconds;
+
+    /**
+     * liczba zawodników, którzy ukończyli zawody.
+     * Używana pośrednio w warunku zatrzymania symulacji.
+     */
     protected int finishCount = 0;
-
+
+    /**
+     * @see desmoj.core.simulator.Model
+     */
     public Biathlon(Model owner, String modelName, boolean showInReport, boolean showInTrace) {
         super(owner, modelName, showInReport, showInTrace);
-        traces = new LinkedList();
     }
 
     /**
-     * @param args the command line arguments
+     * Główna metoda, gdzie wszystko bierze swój początek.
+     * Tworzy obiekty, przeprowadza symulacje, generuje trace'y, taka alfa i omega :)
+     * 
+     * @param args ignorowane.
      */
     public static void main(String[] args) {
         Biathlon model = new Biathlon(null, "Biathlon", true, true);
@@ -54,6 +90,7 @@ public static void main(String[] args) {
         TimeInstant stopTime = new TimeInstant(DURATION_IN_MINUTES, TimeUnit.MINUTES);
         experiment.tracePeriod(new TimeInstant(0), stopTime);
 
+        /* warunek zatrzymania symulacji */
         StopCondition stopCondition = new StopCondition(model, "Stop Condition", true, true);
         experiment.stop(stopCondition);
 
@@ -65,7 +102,22 @@ public static void main(String[] args) {
 
     @Override
     public String description() {
-        return "Not supported yet.";
+        return  "Model biegu indywidualnego mężczyzn na 20km w biathlonie. <br />" +
+                "Założenia: <br />" +
+                "Zwycięzca potrzebuje ok. 50 min przy 0-1 pudłach na pokonanie całej trasy <br />" +
+                "Startuje 30 zawodników <br />" +
+                "Każdy zawodnik oddaje po 5 strzałów w 4 seriach <br />" +
+                "Jest jedna strzelnica, na której każdy zawodnik ma swoje stanowisko i może " +
+                    "oddawać strzały zarówno w pozycji stojącej, jak i leżącej (nierozróżnialne) <br />" +
+                "Dotarcie na strzelnicę (punkt pomiaru czasu) jest równoznaczne z rozpoczęciem strzelania <br />" +
+                "Przed opuszczeniem strzelnicy (punkt pomiaru czasu) jest doliczana kara czasowa za chybienia <br />" +
+                "Kara za chybienie to 60 sekund <br />" +
+                "Punkty pomiaru czasu są rozmieszczone w równych odstępach (dla uproszczenia). " +
+                    "Nie dotyczy punktu pomiaru czasu przed i za strzelnicą. Hipotetyczny dystans między nimi jest zerowy <br />" +
+                "Trasa jest podzielona na 4 okrążenia, na każdym zawodnicy w połowie dystansu odwiedzają strzelnicę <br />" +
+                "Czas biegu zawodników między kolejnymi punktami pomiaru czasu można opisać przy użyciu rozkładu normalnego <br />" +
+                "Czas przygotowania i oddania strzału przez zawodników można opisać przy użyciu rozkładu jednostajnego <br />" +
+                "Parametry rozkładów zostały dobrane empirycznie na podstawie wyników zawodów z Canmore (15 lutego 2012).";
     }
 
     @Override
@@ -74,19 +126,19 @@ public void doInitialSchedules() {
     }
 
      /**
-     * Metoda inicjująca symulację. Tworzymy w niej wszystkie niezbędne obiekty,
-     * takie jak strzelnicę, rozkłady prawdopodobieńst, kolejki zawodników 
-     * i punktów pomiarowych
+     * Metoda inicjująca symulację.
      * 
+     * Tworzone w niej są wszystkie niezbędne obiekty, takie jak strzelnicę, rozkłady prawdopodobieństw,
+     * kolejki zawodników i punktów pomiarowych.
      */
     @Override
     public void init() {
         this.shootingArea = new ShootingArea(this, "ShootingArea", true);
         this.checkpoints = new Queue(this, "Checkpoints", true, true);
         this.biathletes = new Queue(this, "Biathletes", true, true);
-        this.shotDistStream = new BoolDistBernoulli(this, "shotDistStream", 0.8, true, true); // probability for hit
-        this.checkpointArrivalTimeInMilliSeconds = new ContDistNormal(this, "checkpointArrivalTimeInMilliSeconds", 185000, 12000, true, true);
-        this.shotTimeInMilliSeconds = new ContDistUniform(this, "shotTimeInMilliSeconds", 2000, 7000, true, true);
+        this.shotDistStream = new BoolDistBernoulli(this, "shotDistStream", 0.8, true, true); // prawdopodobieństwo trafienia
+        this.checkpointArrivalTimeInMilliSeconds = new ContDistNormal(this, "checkpointArrivalTimeInMilliSeconds", 185000, 12000, true, true); // wartość średnia i odchylenie standardowe rozkładu
+        this.shotTimeInMilliSeconds = new ContDistUniform(this, "shotTimeInMilliSeconds", 2000, 7000, true, true); // wartości graniczne rozkładu
 
         biathlon.checkpoint.BeforeShootingArea beforeShootingArea = new biathlon.checkpoint.BeforeShootingArea(this, "Checkpoint before Shooting Area", true);
         beforeShootingArea.setShootingArea(shootingArea);
@@ -102,7 +154,7 @@ public void init() {
         checkpoints.last().setNextCheckpoint(checkpoints.first());
     }
 
-    /*
+    /**
      * Wygenerowanie trace'ów dla punktów pomiaru czasu, strzelnicy i zawodników.
      * Ważne jest, by na końcu generować dla zawodników, gdyż generowanie trace'ów
      * dla punktów pomiaru czasu pozwala ustalić, na której pozycji był zawodnik
@@ -119,46 +171,53 @@ public void generateTraces() {
     }
 
     /**
-     * Losowanie rezultatu danego strzału 
+     * Losowanie rezultatu danego strzału.
      * 
-     * @return true - jesli trafiono, false - jeśli pudło
+     * @return true (trafiono), false (pudło)
      */
     public boolean getShotResult() {
         return shotDistStream.sample();
     }
 
     /**
-     * Oblicza czas przybycia do punktu pomiaru czasu.
+     * Losowanie czasu przybycia do następnego punktu pomiaru czasu.
      * 
-     * @return czas przybycia do punktu pomiaru czasu
+     * @return bezwględny czas przybycia do następnego punktu pomiaru czasu obliczany względem czasu symulacji.
      */
     public TimeInstant getCheckpointArrivalTime() {
         return advanceTime(checkpointArrivalTimeInMilliSeconds.sample(), TimeUnit.MILLISECONDS);
     }
 
     /**
+     * Losowanie długości trwania przygotowania i oddawania strzału przez zawodnika.
      * 
-     * @return czas strzału
+     * @return bezwględny czas oddania strzału obliczany względem czasu symulacji.
      */
     public TimeInstant getShotTime() {
         return advanceTime(shotTimeInMilliSeconds.sample(), TimeUnit.MILLISECONDS);
     }
 
     /**
+     * Sprawdzenie, czy wszyscy zawodnicy dotarli do mety
      * 
-     * @return true - gdy każdy zawodnik ukończył bieg, false - w przeciwnym wypadku 
+     * @return true (wszyscy ukończyli) 
      */
     public boolean haveAllBiathletesFinished() {
         return finishCount == BIATHLETE_COUNT;
     }
 
+    /**
+     * Poinformowanie modelu o dotarciu do mety kolejnego zawodnika.
+     */
     public void incrementFinishCount() {
         finishCount++;
     }
 
     /**
-     * Tworzy i zapisuje w harmonogramie zdarzenie odpowiedzialne za wytworzenie
+     * Tworzy i zapisuje w harmonogramie zdarzenie odpowiedzialne za wygenerowanie
      * i start zawodnika.
+     * Uwzględnia opóźnienie wynikające ze specyfiki wyścigu - każdy zawodnik startuje z pewnym stałym
+     * upóźnieniem względem poprzedniego.
      */
     protected void generateBiathletes() {
         BiathleteGenerator biathleteGenerator;
@@ -171,14 +230,20 @@ protected void generateBiathletes() {
     }
 
     /**
-     * 
+     * Zwraca bezwględny czas symulacji, który będzie po upływie podanego opóźnienia od teraz.
      * @param delay opóźnienie
-     * @return obecny czas przesunięty o delay
+     * @return bezwględny czas symulacji
      */
     public TimeInstant advanceTime(TimeSpan delay) {
         return TimeOperations.add(presentTime(), delay);
     }
 
+    /**
+     * Zwraca bezwględny czas symulacji, który będzie po upływie podanego opóźnienia od teraz.
+     * @param delay opóźnienie w jednostkach bezwględnych
+     * @param unit jednostka referencyjna czasu
+     * @return bezwględny czas symulacji
+     */
     public TimeInstant advanceTime(long delay, TimeUnit unit) {
         return advanceTime(new TimeSpan(delay, unit));
     }
@@ -194,9 +259,13 @@ public Queue<Checkpoint> getCheckpoints() {
     public Queue<Biathlete> getBiathletes() {
         return biathletes;
     }
+
+    public ShootingArea getShootingArea() {
+        return shootingArea;
+    }
 
     /**
-     * Dodaje punkt pomiarowy do kolejki tych puntków.
+     * Dodaje punkt pomiarowy do kolejki.
      * 
      * @param checkpoint punkt pomiaru czasu, który chcemy dodać
      */
@@ -205,8 +274,4 @@ protected void addCheckpoint(Checkpoint checkpoint) {
         lastCheckpoint.setNextCheckpoint(checkpoint);
         checkpoints.insert(checkpoint);
     }
-
-    public ShootingArea getShootingArea() {
-        return shootingArea;
-    }
 }

src/biathlon/ShootingArea.java

@@ -7,9 +7,10 @@
 import java.util.LinkedList;
 
 /**
- * Reprezentuje strzelnicę.
+ * Klasa reprezentująca strzelnicę jako obiekt na trasie.
  * 
  * @author Artur Hebda
+ * @see biathlon.core.Entity
  */
 public class ShootingArea extends biathlon.core.Entity {
     protected AfterShootingArea afterCheckpoint;
@@ -18,12 +19,20 @@ public ShootingArea(Model owner, String name, boolean showInTrace) {
         super(owner, name, showInTrace);
     }
 
+    /**
+     * Zapisuje informację o oddanym strzale i dodaje event do zawodnika.
+     * @param biathlete zawodnik
+     * @param message opis uwzględniający, czy udało się trafić
+     */
     public void storeShot(Biathlete biathlete, String message) {
         BiathleteEvent shot = new BiathleteEvent(biathlete, message);
         eventsByLap.get(biathlete.getCurrentLap() - 1).add(shot);
         biathlete.addEvent(shot);
     }
 
+    /**
+     * Generuje trace dla strzelnicy.
+     */
     @Override
     public void generateTrace() {
         LinkedList<BiathleteEvent> events;
@@ -49,6 +58,14 @@ public void generateTrace() {
         trace.close();
     }
 
+    /**
+     * Ustawia następny punkt kontrolny, będący zaraz za strzelnicą.
+     * Na tym punkcie będą uwzględniane kary za niecelne strzały.
+     * Sygnatura metody wynika z chęci zachowania kompatybilności z innymi obiektami na trasie.
+     * 
+     * @param checkpoint punkt kontrolny za strzelnicą (musi być klasy biathlon.checkpoint.AfterShootingArea).
+     * @see biathlon.checkpoint.AfterShootingArea
+     */
     public void setAfterCheckpoint(Checkpoint checkpoint) {
         this.afterCheckpoint = (AfterShootingArea)checkpoint;
     }