diff --git a/src/example/randomants/Ant.java b/src/example/randomants/Ant.java
index 5f64c9961e5fa31dc4080e2764d4cef8a6952433..5cbc79580b4d2bbb0608e78213d19d57d51f190c 100644
--- a/src/example/randomants/Ant.java
+++ b/src/example/randomants/Ant.java
@@ -7,48 +7,61 @@ import mas.ui.drawables.DrawableImage;
import java.util.Random;
+/**
+ * An ant.
+ */
public class Ant extends Agent {
+ /**
+ * Number of ants.
+ */
private static int numberOfAnts = 0;
+ /**
+ * id of the ant.
+ */
public int id;
/**
- * X coordinate of the ant in the world
+ * X coordinate of the ant in the world.
*/
public double dx;
/**
- * Y coordinate of the ant in the world
+ * Y coordinate of the ant in the world.
*/
public double dy;
public boolean mustDie = false;
/**
- * Angle in radians
+ * Angle in radians.
*/
private double angle = Math.random() * Math.PI * 2;
private DrawableImage image;
- TwoDContinuosGrid environnement;
+ TwoDContinuosGrid environment;
/**
- * Constructor of the ant
+ * Constructor of the ant.
*
+ * @param _id
+ * Id of the ant
* @param startX
* Initial X coordinate
* @param startY
* Initial Y coordinate
+ * @param _environment
+ * environment of the ant
*/
- public Ant(int _id, double startX, double startY, TwoDContinuosGrid _environnement) {
+ public Ant(int _id, double startX, double startY, TwoDContinuosGrid _environment) {
numberOfAnts++;
id = _id;
dx = startX;
dy = startY;
- environnement = _environnement;
+ environment = _environment;
image = VUI.get().createImage(dx, dy, "src/example/randomants/ressources/ant.png");
}
/**
- * Move in a random direction
+ * Move in a random direction.
*/
@Override
public void decide() {
@@ -57,14 +70,14 @@ public class Ant extends Agent {
angle += random * 0.1;
dx += Math.cos(angle);
dy += Math.sin(angle);
- while (dx >= environnement.getWidth() / 2)
- dx -= environnement.getWidth();
- while (dy >= environnement.getHeight() / 2)
- dy -= environnement.getHeight();
- while (dx < -environnement.getWidth() / 2)
- dx += environnement.getWidth();
- while (dy < -environnement.getHeight() / 2)
- dy += environnement.getHeight();
+ while (dx >= environment.getWidth() / 2)
+ dx -= environment.getWidth();
+ while (dy >= environment.getHeight() / 2)
+ dy -= environment.getHeight();
+ while (dx < -environment.getWidth() / 2)
+ dx += environment.getWidth();
+ while (dy < -environment.getHeight() / 2)
+ dy += environment.getHeight();
}
@Override
@@ -78,7 +91,7 @@ public class Ant extends Agent {
image.setAngle(angle);
if (new Random().nextDouble() < 0.001) {
- scheduler.addCyclable(new Ant(id * 10,dx, dy, environnement));
+ scheduler.addCyclable(new Ant(id * 10,dx, dy, environment));
}
if (new Random().nextDouble() < 0.001) {
diff --git a/src/example/randomants/AntHill.java b/src/example/randomants/AntHill.java
index 771a2134d1f2a63a092be2ce6ac50759c3e37ff9..672842cf4fe2e03d4f16380d19c3f2567e7ead25 100644
--- a/src/example/randomants/AntHill.java
+++ b/src/example/randomants/AntHill.java
@@ -6,13 +6,27 @@ import mas.ui.drawables.DrawableString;
import java.awt.*;
+/**
+ * This class creates the VUI for the experience.
+ */
public class AntHill {
+ /**
+ * Displayable that shows the current number of ants.
+ */
public DrawableString antsCountLabel;
- public AntHill(int _weight, int _height){
-
- DrawableRectangle d = VUI.get().createRectangle(0, 0, _weight, _height);
+ /**
+ * Constructor of the AntHill.
+ *
+ * @param _width
+ * width of the world
+ * @param _height
+ * height of the world
+ */
+ public AntHill(int _width, int _height){
+
+ DrawableRectangle d = VUI.get().createRectangle(0, 0, _width, _height);
d.setStrokeOnly();
VUI.get().createRectangle(90, 20, 180, 40).setColor(new Color(0.9f, 0.9f, 0.9f, 0.8f)).setFixed().setLayer(5);
@@ -21,10 +35,21 @@ public class AntHill {
antsCountLabel = (DrawableString) VUI.get().createString(45, 25, "Ants count").setFixed().setLayer(10);
}
+ /**
+ * Getter of the antsCountLabel
+ *
+ * @return a DrawableString with the current number of ants
+ */
public DrawableString getAntsCountLabel() {
return antsCountLabel;
}
+ /**
+ * Setter of the antsCountLabel
+ *
+ * @param _antsCountLabel
+ * The DrawableString with the current number of Ants
+ */
public void setAntsCountLabel(DrawableString _antsCountLabel) {
antsCountLabel = _antsCountLabel;
}
diff --git a/src/mas/core/Agent.java b/src/mas/core/Agent.java
index 3980769f8388ac557552f4ab20652b4e14d201e1..7afaba6edf962d432880234491e5f93aeb3326af 100644
--- a/src/mas/core/Agent.java
+++ b/src/mas/core/Agent.java
@@ -1,5 +1,8 @@
package mas.core;
+/**
+ * An implementation of a threeStepCyclable agent.
+ */
public class Agent implements ThreeStepCyclable{
/**
diff --git a/src/mas/core/Cyclable.java b/src/mas/core/Cyclable.java
index ac6ed97d60eb60fd388c40f9dec062246a79b132..1d88af61dd417753e3a8dd0073badee051dd2f82 100644
--- a/src/mas/core/Cyclable.java
+++ b/src/mas/core/Cyclable.java
@@ -18,7 +18,10 @@ public interface Cyclable {
boolean terminate();
/**
- * Set the scheduler in which the cyclable is going to be scheduled.
+ * Settter for the scheduler
+ *
+ * @param _scheduler
+ * The scheduler in which the cyclable is going to be scheduled.
*/
void setScheduler(Schedulable _scheduler);
}
diff --git a/src/mas/core/Schedulable.java b/src/mas/core/Schedulable.java
index 3712675e11dab9a276117b75087e22db4f9ed4f7..1d88b13009c9b3d727677b85c2d2b569b9ac3832 100644
--- a/src/mas/core/Schedulable.java
+++ b/src/mas/core/Schedulable.java
@@ -1,11 +1,14 @@
package mas.core;
/**
- * A schedulable object can be controlled by a scheduler.
+ * A schedulable object.
*
*/
public interface Schedulable {
+ /**
+ * Default sleep time
+ */
public static final int DEFAULT_SLEEP = 0;
/**
@@ -30,6 +33,9 @@ public interface Schedulable {
/**
* Add a Cyclable object to the scheduler and starts their cycle as soon as possible.
+ *
+ * @param cyclable
+ * The cyclable to add
*/
void addCyclable(Cyclable cyclable);
@@ -37,7 +43,7 @@ public interface Schedulable {
/**
* This method allows the scheduler to stop on certain conditions.
*
- * @return whether or not the scheduler must stop.
+ * @return whether the scheduler must stop.
*/
boolean stopCondition();
diff --git a/src/mas/environment/TwoDContinuosGrid.java b/src/mas/environment/TwoDContinuosGrid.java
index 13f164513fb38c8f7a1fbfc08ea9a736d6ccfa1e..8ae9bdeac00d7b912bb8f51bef2d61e99c7a1cdf 100644
--- a/src/mas/environment/TwoDContinuosGrid.java
+++ b/src/mas/environment/TwoDContinuosGrid.java
@@ -1,22 +1,38 @@
package mas.environment;
/**
- * TODO
+ * A 2 dimensions continuous grid.
*/
public class TwoDContinuosGrid {
private int width;
private int height;
+ /**
+ * Constructor of TwoDContinuosGrid.
+ *
+ * @param _width
+ * width of the environment
+ * @param _height
+ * height of the environment
+ */
public TwoDContinuosGrid(int _width, int _height){
height = _height;
width = _width;
}
+ /**
+ * Getter of height.
+ * @return the height of the grid
+ */
public int getHeight() {
return height;
}
+ /**
+ * Getter of width.
+ * @return the width of the grid
+ */
public int getWidth() {
return width;
}
diff --git a/src/mas/implementation/schedulers/AsyncCycling.java b/src/mas/implementation/schedulers/AsyncCycling.java
index fd3f15ba97d99e806df9ee214aabd6f803f8191f..3e0941add4e6b9a927b9d443538287ac387b747f 100644
--- a/src/mas/implementation/schedulers/AsyncCycling.java
+++ b/src/mas/implementation/schedulers/AsyncCycling.java
@@ -8,7 +8,7 @@ import java.util.Set;
import java.util.concurrent.*;
/**
- * The AsyncCycling scheduler schedules tasks asynchronously using a {@link java.util.concurrent.ThreadPoolExecutor}.
+ * The AsyncCycling scheduler schedules tasks asynchronously using a {@link PausableThreadPoolExecutor}.
*
* @author David Antunes
*/
diff --git a/src/mas/implementation/schedulers/FairPosCycling.java b/src/mas/implementation/schedulers/FairPosCycling.java
index 44bb30597c668a82b8f84ae890f584ef7cc1b652..16d52846b61756c60b3f623cb6e767a8e0965ca1 100644
--- a/src/mas/implementation/schedulers/FairPosCycling.java
+++ b/src/mas/implementation/schedulers/FairPosCycling.java
@@ -27,12 +27,21 @@ public class FairPosCycling implements Schedulable {
}
-
+ /**
+ * Getter for the sleep time.
+ *
+ * @return the current time elapsed between each system's cycle
+ */
public int getSleep() {
return 0;
}
-
+ /**
+ * Setter for the sleep time.
+ *
+ * @param sleep
+ * The time between each system's cycle
+ */
public void setSleep(int sleep) {
}
diff --git a/src/mas/implementation/schedulers/PausableThreadPoolExecutor.java b/src/mas/implementation/schedulers/PausableThreadPoolExecutor.java
index cc2dc64728922ccd82c73c1b2a4c8b1367737139..4664ece11392e2d0f9ee49ea8f9c72203cce5f73 100644
--- a/src/mas/implementation/schedulers/PausableThreadPoolExecutor.java
+++ b/src/mas/implementation/schedulers/PausableThreadPoolExecutor.java
@@ -16,7 +16,7 @@ public class PausableThreadPoolExecutor extends ThreadPoolExecutor {
private Condition condition;
/**
- * @see {@link ThreadPoolExecutor#ThreadPoolExecutor(int, int, long, TimeUnit, BlockingQueue)}
+ * {@link ThreadPoolExecutor#ThreadPoolExecutor(int, int, long, TimeUnit, BlockingQueue)}
*/
public PausableThreadPoolExecutor() {
super(0, Integer.MAX_VALUE, 60L, TimeUnit.SECONDS, new SynchronousQueue<Runnable>());
@@ -27,7 +27,7 @@ public class PausableThreadPoolExecutor extends ThreadPoolExecutor {
/**
* @param thread The thread being executed
* @param runnable The runnable task
- * @see {@link ThreadPoolExecutor#beforeExecute(Thread, Runnable)}
+ * {@link ThreadPoolExecutor#beforeExecute(Thread, Runnable)}
*/
@Override
protected void beforeExecute(Thread thread, Runnable runnable) {
@@ -42,10 +42,20 @@ public class PausableThreadPoolExecutor extends ThreadPoolExecutor {
}
}
+ /**
+ * This method says whether the scheduler is running
+ *
+ * @return whether the scheduler is running
+ */
public boolean isRunning() {
return !isPaused;
}
+ /**
+ * This method says whether the scheduler is stopped
+ *
+ * @return whether the scheduler is stopped
+ */
public boolean isPaused() {
return isPaused;
}
diff --git a/src/mas/implementation/schedulers/variations/ThreeStepCycling.java b/src/mas/implementation/schedulers/variations/ThreeStepCycling.java
index 47300516887071b4c5c8318d2c0f89ebf64f36e8..46bd4f17e6c8d4bc5150f79fad3c6f08e350bf0b 100644
--- a/src/mas/implementation/schedulers/variations/ThreeStepCycling.java
+++ b/src/mas/implementation/schedulers/variations/ThreeStepCycling.java
@@ -16,12 +16,32 @@ import java.util.concurrent.CountDownLatch;
public class ThreeStepCycling extends FairCycling {
+ /**
+ * The cyclable objects handled by the scheduler.
+ */
protected Set<ThreeStepCyclable> threeStepCyclables = new LinkedHashSet<>();
+
+ /**
+ * The cyclables that must be added in the next cycle.
+ */
protected Queue<ThreeStepCyclable> pendingToAddThreeStepCyclabes = new ConcurrentLinkedQueue<>();
+ /**
+ * Object that synchronize each cyclable every system's cycle for the perception phase.
+ */
protected CountDownLatch perceptionLatch;
+
+ /**
+ * Object that synchronize each cyclable every system's cycle for the decision phase.
+ */
protected CountDownLatch decicionLatch;
+ /**
+ * Constructor which set the initial cyclables.
+ *
+ * @param _threeStepCyclables
+ * The corresponding cyclables
+ */
public ThreeStepCycling(ThreeStepCyclable... _threeStepCyclables){
for(ThreeStepCyclable threeStepCyclable : _threeStepCyclables){
addThreeStepCyclable(threeStepCyclable);
@@ -78,11 +98,20 @@ public class ThreeStepCycling extends FairCycling {
pendingToAddThreeStepCyclabes.clear();
}
+ /**
+ * Add a threeStepCyclable object to the scheduler and starts their cycle as soon as possible.
+ *
+ * @param threeStepCyclable
+ * The cyclable to add
+ */
public void addThreeStepCyclable(ThreeStepCyclable threeStepCyclable){
threeStepCyclable.setScheduler(this);
pendingToAddThreeStepCyclabes.add(threeStepCyclable);
}
+ /**
+ * This method synchronize every cyclable in the perception phase.
+ */
protected void waitPerception(){
perceptionLatch.countDown();
@@ -93,13 +122,16 @@ public class ThreeStepCycling extends FairCycling {
}
}
- protected void waitDecision(){
- decicionLatch.countDown();
+ /**
+ * This method synchronize every cyclable in the decision phase.
+ */
+ protected void waitDecision(){
+ decicionLatch.countDown();
- try {
- decicionLatch.await();
- } catch (InterruptedException e) {
- throw new RuntimeException(e);
- }
- }
+ try {
+ decicionLatch.await();
+ } catch (InterruptedException e) {
+ throw new RuntimeException(e);
+ }
+ }
}
diff --git a/src/mas/implementation/schedulers/variations/TwoDCycling.java b/src/mas/implementation/schedulers/variations/TwoDCycling.java
index 0a886d2736dfb8b7a5ce036d532a2baa2b24f633..2520eb36a4127a80b4ec8f1f0ccf852a77c8eab5 100644
--- a/src/mas/implementation/schedulers/variations/TwoDCycling.java
+++ b/src/mas/implementation/schedulers/variations/TwoDCycling.java
@@ -8,6 +8,9 @@ import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.util.function.Consumer;
+/**
+ * Extension of the {@link FairCycling} scheduler made to be used with a GUI.
+ */
public class TwoDCycling extends FairCycling {
/**
@@ -43,6 +46,12 @@ public class TwoDCycling extends FairCycling {
}
+ /**
+ * Constructor which set the initial cyclables.
+ *
+ * @param _cyclables
+ * The corresponding cyclables
+ */
public TwoDCycling(Cyclable... _cyclables){
super(_cyclables);
}
@@ -69,7 +78,9 @@ public class TwoDCycling extends FairCycling {
}
}
-
+ /**
+ * Method that performs only one system cycle.
+ */
public void doOneCycle() {
executor.execute(() -> {
step();
@@ -83,6 +94,12 @@ public class TwoDCycling extends FairCycling {
});
}
+ /**
+ * Method that launches or resumes the scheduler with a certain sleep time.
+ *
+ * @param _sleep
+ * The sleep of the scheduler
+ */
public void startWithSleep(int _sleep){
setSleep(_sleep);
@@ -97,7 +114,11 @@ public class TwoDCycling extends FairCycling {
}
}
-
+ /**
+ * This method says whether the scheduler is running
+ *
+ * @return whether the scheduler is running
+ */
public boolean isRunning() {
return state == State.RUNNING;
}