From dc17a704aa31f9d13b006e7ca92fd85b27017c22 Mon Sep 17 00:00:00 2001
From: fcorno <fulvio.corno@polito.it>
Date: Wed, 3 Jun 2015 14:41:13 +0200
Subject: [PATCH] aggiunta documentazione

---
 src/it/polito/tdp/babs/model/Model.java     | 21 ++++++++++++++++++++
 src/it/polito/tdp/babs/model/Simulator.java | 22 ++++++++++++++++++++-
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/src/it/polito/tdp/babs/model/Model.java b/src/it/polito/tdp/babs/model/Model.java
index cc4b400..5ac61fb 100644
--- a/src/it/polito/tdp/babs/model/Model.java
+++ b/src/it/polito/tdp/babs/model/Model.java
@@ -31,12 +31,22 @@ public void loadStations() {
 		stations = dao.getAllStations() ; 
 	}
 
+	/**
+	 * Carica tutti e soli i trip della giornata specificata
+	 * @param day giorno da caricare
+	 * @return numero di trip caricati
+	 */
 	public int loadTripsOfTheDay(LocalDate day) {
 		BabsDAO dao = new BabsDAO() ;
 		tripsOfTheDay = dao.getTripsOfDay(day) ;
 		return tripsOfTheDay.size() ;
 	}
 	
+	/** 
+	 * Conta il numero di trip, nel giorno corrente, che partono dalla stazione specificata
+	 * @param depart stazione di partenza
+	 * @return numero di trip
+	 */
 	public int countDepartingTrips(Station depart) {
 		int count=0 ;
 		for(Trip t : tripsOfTheDay) {
@@ -47,6 +57,11 @@ public int countDepartingTrips(Station depart) {
 		return count ;
 	}
 
+	/** 
+	 * Conta il numero di trip, nel giorno corrente, che rientrano nella stazione specificata
+	 * @param arrival stazione di arrivo
+	 * @return numero di trip
+	 */
 	public int countArrivingTrips(Station arrival) {
 		int count=0 ;
 		for(Trip t : tripsOfTheDay) {
@@ -57,6 +72,12 @@ public int countArrivingTrips(Station arrival) {
 		return count ;
 	}
 
+	/**
+	 * Dato l'ID di una Station, trova l'oggetto Station corrispondente nella lista del modello.
+	 * Nota: potrebbe essere ottimizzato costruendo una mappa ID->Station
+	 * @param stationID identificavo numerico di una stazione
+	 * @return oggetto Station corrispondente, oppure null se non esiste
+	 */
 	public Station getStationByID(int stationID) {
 		for(Station s: stations) {
 			if( s.getStationID()==stationID)
diff --git a/src/it/polito/tdp/babs/model/Simulator.java b/src/it/polito/tdp/babs/model/Simulator.java
index 9040ddf..16e3191 100644
--- a/src/it/polito/tdp/babs/model/Simulator.java
+++ b/src/it/polito/tdp/babs/model/Simulator.java
@@ -13,6 +13,12 @@ private enum BikeEvent {
 		PICK, DROP
 	};
 
+	/**
+	 * Evento simulato: la PRESA o il RIENTRO di una bicicletta
+	 * 
+	 * @author Fulvio Corno
+	 *
+	 */
 	private class SimEvent implements Comparable<SimEvent> {
 		private BikeEvent type;
 		private LocalDateTime time;
@@ -50,15 +56,23 @@ public Trip getTrip() {
 		}
 	}
 
+	// La coda di simulazione
 	private PriorityQueue<SimEvent> queue = new PriorityQueue<Simulator.SimEvent>();
 
 	private double K; // percentuale di riempimento iniziale
 
+	// Numero di biciclette in ciascuna stazione
 	private Map<Station, Integer> occupancy;
 
+	// Risultati della simulazione
 	private int failedPicks;
 	private int failedDrops;
 
+	/**
+	 * Inizializza un nuovo simulatore per il calcolo di prese/rientri falliti
+	 * @param K rapporto di occupazione (tra 0.0 ed 1.1)
+	 * @param model il modello
+	 */
 	public Simulator(double K, Model model) {
 		this.K = K;
 		this.model = model ;
@@ -66,7 +80,7 @@ public Simulator(double K, Model model) {
 		// Calcola l'occupazione iniziale (K% dei posti disponibili)
 		occupancy = new HashMap<>();
 		for (Station s : model.getStations()) {
-			int bikes = (int) (s.getDockCount() * K);
+			int bikes = (int) (s.getDockCount() * this.K);
 			occupancy.put(s, bikes);
 		}
 
@@ -80,6 +94,11 @@ public Simulator(double K, Model model) {
 		failedPicks = 0;
 	}
 
+	/**
+	 * Esegue la simulazione
+	 * 
+	 * @return numero di eventi simulati
+	 */
 	public int run() {
 		
 		int events = 0 ;
@@ -102,6 +121,7 @@ public int run() {
 					occupancy.put(s, occupancy.get(s) - 1);
 					queue.add(new SimEvent(BikeEvent.DROP, t.getEndDate(),
 							model.getStationByID(t.getEndStationID()), t));
+					// nota: se la PRESA non riesce, allora NON bisogna schedulare il rientro
 				}
 
 				break;