Docs added.

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/AdditionAwareAgentSource.java

@@ -3,6 +3,15 @@
 import org.matsim.core.mobsim.framework.AgentSource;
 import org.matsim.core.mobsim.qsim.QSim;
 
+/**
+ * This interface has been introduced to allow creation/modification of the
+ * MATSim agent source before the simulation is started. When simulation is
+ * started then the QSim instance is created and as such it needs to be passed
+ * to the agent source before it is used.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public interface AdditionAwareAgentSource extends AgentSource {
 	public void agentSourceAdded(QSim qSim);
 }

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/Constants.java

@@ -1,5 +1,11 @@
 package cz.cuni.mff.d3s.deeco.simulation.matsim;
 
+/**
+ * Constants holder.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ *
+ */
 public class Constants {
 	public static final int MILLIS_IN_SECOND = 1000;
 }

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/JDEECoAgent.java

@@ -14,8 +14,14 @@
 import org.matsim.core.mobsim.qsim.qnetsimengine.QVehicle;
 import org.matsim.core.utils.geometry.CoordImpl;
 
-import cz.cuni.mff.d3s.deeco.logging.Log;
-
+/**
+ * JDEECo agent implementation. The agent is used by the
+ * {@link JDEECoWithinDayMobsimListener} to steer the MATSim simulation,
+ * according to the state of the JDEECo component.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public class JDEECoAgent implements MobsimDriverAgent {
 
 	private MobsimVehicle vehicle;
@@ -90,7 +96,7 @@ public String getMode() {
 	public State getState() {
 		return this.state;
 	}
-	
+
 	public void setActivityType(String value) {
 		this.activityType = value;
 	}

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/JDEECoAgentProvider.java

@@ -2,6 +2,13 @@
 
 import java.util.Collection;
 
+/**
+ * The interface is used by the {@link JDEECoWithinDayMobsimListener} instance
+ * to retrieve simulated jDEECo agents.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public interface JDEECoAgentProvider {
 	public Collection<JDEECoAgent> getAgents();
 }

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/JDEECoAgentSource.java

@@ -11,19 +11,26 @@
 
 import cz.cuni.mff.d3s.deeco.logging.Log;
 
-public class JDEECoAgentSource implements AdditionAwareAgentSource, JDEECoAgentProvider {
+/**
+ * JDEECo agent source, which is used by MATSim to retrieve agents that need to
+ * be simulated.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
+public class JDEECoAgentSource implements AdditionAwareAgentSource,
+		JDEECoAgentProvider {
 	private QSim qSim;
 	private final List<JDEECoAgent> agents;
 
-
 	public JDEECoAgentSource() {
 		this.agents = new LinkedList<JDEECoAgent>();
 	}
-	
+
 	public void agentSourceAdded(QSim qSim) {
 		this.qSim = qSim;
 	}
-	
+
 	public void addAgent(JDEECoAgent agent) {
 		agents.add(agent);
 	}

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/JDEECoMobsimFactory.java

@@ -12,6 +12,13 @@
 import org.matsim.core.mobsim.qsim.qnetsimengine.DefaultQSimEngineFactory;
 import org.matsim.core.mobsim.qsim.qnetsimengine.QNetsimEngine;
 
+/**
+ * Mobisim engine factory. It is the configuration point for the MATSim
+ * simulation to let it know, which agent source, listeners etc... to use.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public class JDEECoMobsimFactory implements MobsimFactory {
 
 	private final JDEECoWithinDayMobsimListener listener;

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/JDEECoWithinDayMobsimListener.java

@@ -9,6 +9,16 @@
 
 import cz.cuni.mff.d3s.deeco.logging.Log;
 
+/**
+ * 
+ * This class represents the interface (on the MATSim side) between jDEECo and
+ * MATSim. It's notifyMobsimBeforeSimStep is executed before each simulation
+ * step and data exchange between MATSim and jDEECo happens via the exchanger
+ * instance.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public class JDEECoWithinDayMobsimListener implements
 		MobsimBeforeSimStepListener {
 
@@ -35,9 +45,11 @@ public void notifyMobsimBeforeSimStep(MobsimBeforeSimStepEvent event) {
 				matSimOutputs.put(agent.getId().toString(), matSimOutput);
 			}
 			// Exchange data (Rendezvous)
-			//Log.w("MATSim Before data exchange at " + event.getSimulationTime());
+			// Log.w("MATSim Before data exchange at " +
+			// event.getSimulationTime());
 			Map<String, ?> matSimInputs = exchanger.exchange(matSimOutputs);
-			//Log.w("MATSim After data exchange at " + event.getSimulationTime());
+			// Log.w("MATSim After data exchange at " +
+			// event.getSimulationTime());
 			// Update jDEECo agents next link id
 			if (matSimInputs != null && !matSimInputs.isEmpty()) {
 				MATSimInput mData;

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/MATSimDataProvider.java

@@ -2,6 +2,12 @@
 
 import java.util.Map;
 
+/**
+ * Interface for MATSim data i.e. the data that is for the MATSim side.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public interface MATSimDataProvider {
 	public Map<String, ?> getMATSimData();
 }

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/MATSimDataReceiver.java

@@ -2,6 +2,12 @@
 
 import java.util.Map;
 
+/**
+ * Interface for MATSim data retrieval. This data comes from MATSim side.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public interface MATSimDataReceiver {
 	public void setMATSimData(Map<String, ?> data);
 }

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/MATSimInput.java

@@ -5,12 +5,18 @@
 
 import org.matsim.api.core.v01.Id;
 
+/**
+ * Data that is needed by MATSim to execute the simulation.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public class MATSimInput {
 	public Id destination;
 	public double activityEndTime;
 	public List<Id> route;
 	public String activityType;
-	
+
 	public MATSimInput clone() {
 		MATSimInput result = new MATSimInput();
 		result.activityEndTime = activityEndTime;

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/MATSimOMNetCoordinatesTranslator.java

@@ -5,6 +5,16 @@
 import org.matsim.api.core.v01.network.Node;
 import org.matsim.core.utils.geometry.CoordImpl;
 
+/**
+ * Because the coordinates in MATSim are given in meters in large numbers, this
+ * class takes care to translate coordinates from MATSim to OMNet, which are
+ * much smaller.
+ * 
+ * 
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public class MATSimOMNetCoordinatesTranslator {
 
 	private final double OMNetSizeX;

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/MATSimOMNetSimulation.java

@@ -18,6 +18,12 @@
 import cz.cuni.mff.d3s.deeco.simulation.omnet.OMNetSimulation;
 import cz.cuni.mff.d3s.deeco.simulation.task.SimulationStepTask;
 
+/**
+ * Main simulation class.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ *
+ */
 public class MATSimOMNetSimulation extends OMNetSimulation implements SimulationStepListener {
 
 	private final Exchanger<Map<String, ?>> exchanger;

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/MATSimOMNetSimulationRuntimeBuilder.java

@@ -11,24 +11,35 @@
 import cz.cuni.mff.d3s.deeco.simulation.omnet.OMNetSimulationRuntimeBuilder;
 import cz.cuni.mff.d3s.deeco.simulation.task.SimulationStepTask;
 
+/**
+ * MATSim-OMNet simulation builder. An additional functionality of this class is
+ * to register the simulation step task at one (i.e. the first) scheduler.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public class MATSimOMNetSimulationRuntimeBuilder extends
 		OMNetSimulationRuntimeBuilder {
 	private boolean simulationTaskRegistered = false;
-
-	public RuntimeFramework build(SimulationHost host, MATSimOMNetSimulation simulation, RuntimeMetadata model, Collection<DirectRecipientSelector> recipientSelectors, DirectGossipStrategy directGossipStrategy) {
-		RuntimeFramework result = super.build(host, simulation, model, recipientSelectors, directGossipStrategy);
+
+	public RuntimeFramework build(SimulationHost host,
+			MATSimOMNetSimulation simulation, RuntimeMetadata model,
+			Collection<DirectRecipientSelector> recipientSelectors,
+			DirectGossipStrategy directGossipStrategy) {
+		RuntimeFramework result = super.build(host, simulation, model,
+				recipientSelectors, directGossipStrategy);
 		if (!simulationTaskRegistered && result != null) {
 			Scheduler scheduler = result.getScheduler();
 			// Set up the simulation step task
-			SimulationStepTask simulationStepTask = new SimulationStepTask(scheduler, 
-					simulation);
-			
+			SimulationStepTask simulationStepTask = new SimulationStepTask(
+					scheduler, simulation);
+
 			// Add simulation step task to the scheduler
 			scheduler.addTask(simulationStepTask);
-			
+
 			simulationTaskRegistered = true;
 		}
 		return result;
 	}
-	
+
 }

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/MATSimOutput.java

@@ -3,6 +3,12 @@
 import org.matsim.api.core.v01.Coord;
 import org.matsim.api.core.v01.Id;
 
+/**
+ * Data coming from MATSim.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ *
+ */
 public class MATSimOutput {
 	public Id currentLinkId;
 	public Coord estPosition;

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/MATSimPreloadingControler.java

@@ -2,6 +2,15 @@
 
 import org.matsim.core.controler.Controler;
 
+/**
+ * This is an extension of the MATSim controller that allows for scenario data
+ * preloading. Normally the scenario is loaded when the simulation starts. As
+ * data such as population, map is necessary beforehand this class has been
+ * introduced.
+ * 
+ * @author Michal Kit <kit@d3s.mff.cuni.cz>
+ * 
+ */
 public class MATSimPreloadingControler extends Controler {
 
 	public MATSimPreloadingControler(String configFileName) {

jdeeco-simulation/src/cz/cuni/mff/d3s/deeco/simulation/matsim/MATSimRouter.java

@@ -29,13 +29,16 @@
 import org.matsim.pt.router.TransitRouterImplFactory;
 
 /**
+ * MATSim router. The class reuses the functionality available already in
+ * MATSim.
+ * 
  * @author Michal Kit <kit@d3s.mff.cuni.cz>
- *
+ * 
  */
 public class MATSimRouter {
-	
+
 	public static int DEFAULT_LINK_PARKING_CAPACITY = 3;
-	
+
 	private final Controler controler;
 	private final TripRouterFactory tripRouterFactory;
 
@@ -59,13 +62,13 @@ public String routeRandomly(Id currentLinkId) {
 		int idx = MatsimRandom.getRandom().nextInt(outLinks.length);
 		return outLinks[idx].toString();
 	}
-	
+
 	public Link findLinkById(Id id) {
 		return controler.getNetwork().getLinks().get(id);
 	}
-	
+
 	public int getLinkParkingCapacity(Id linkId) {
-		//TODO: Needs to be changed
+		// TODO: Needs to be changed
 		return DEFAULT_LINK_PARKING_CAPACITY;
 	}
 
@@ -118,14 +121,13 @@ public List<Id> route(Link linkFrom, Link linkTo, double departureTime,
 		Leg leg = (Leg) legs.get(0);
 		return ((NetworkRoute) leg.getRoute()).getLinkIds();
 	}
-
-	public List<Id> route(Id from, Id to, double departureTime,
-			Person person) {
+
+	public List<Id> route(Id from, Id to, double departureTime, Person person) {
 		Link fromLink = controler.getNetwork().getLinks().get(from);
 		Link toLink = controler.getNetwork().getLinks().get(to);
 		return route(fromLink, toLink, departureTime, person);
 	}
-	
+
 	public List<Id> getAdjacentLinks(Id linkId) {
 		Link link = controler.getNetwork().getLinks().get(linkId);
 		if (link == null)