Merge pull request #78 from manoelcampos/master

A comprehensive review and improvement of the entire project documentation

.gitignore

+/modules/cloudsim/target/
+/modules/cloudsim-examples/target/
+ 

modules/cloudsim-examples/src/main/java/org/cloudbus/cloudsim/examples/CloudSimExample1.java

@@ -119,7 +119,10 @@ public class CloudSimExample1 {
 			long outputSize = 300;
 			UtilizationModel utilizationModel = new UtilizationModelFull();
 
-			Cloudlet cloudlet = new Cloudlet(id, length, pesNumber, fileSize, outputSize, utilizationModel, utilizationModel, utilizationModel);
+			Cloudlet cloudlet = 
+                                new Cloudlet(id, length, pesNumber, fileSize, 
+                                        outputSize, utilizationModel, utilizationModel, 
+                                        utilizationModel);
 			cloudlet.setUserId(brokerId);
 			cloudlet.setVmId(vmid);
 

modules/cloudsim-examples/src/main/java/org/cloudbus/cloudsim/examples/network/NetworkExample4.java

@@ -119,8 +119,8 @@ public class NetworkExample4 {
 			//Sixth step: configure network
 
 			//maps CloudSim entities to BRITE entities
-			NetworkTopology.addLink(datacenter0.getId(),broker.getId(),10.0,10);
-
+			NetworkTopology.addLink(datacenter0.getId(), broker.getId(),10.0,10);
+                        
 			// Seventh step: Starts the simulation
 			CloudSim.startSimulation();
 

modules/cloudsim/pom.xml

@@ -65,9 +65,16 @@
 			</configuration>
 		</plugin>
 	</plugins>
-  </build>  
-
-  <reporting>
+  </build>
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-math3</artifactId>
+            <version>3.4.1</version>
+            <type>jar</type>
+        </dependency>
+    </dependencies>
+    <reporting>
 	<plugins>
 	  <plugin>
 		<groupId>org.apache.maven.plugins</groupId>

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/CloudletScheduler.java

@@ -10,12 +10,15 @@ package org.cloudbus.cloudsim;
 
 import java.util.ArrayList;
 import java.util.List;
+import org.cloudbus.cloudsim.network.datacenter.NetworkCloudletSpaceSharedScheduler;
 
 
 /**
  * CloudletScheduler is an abstract class that represents the policy of scheduling performed by a
- * virtual machine. So, classes extending this must execute Cloudlets. Also, the interface for
+ * virtual machine to run its {@link Cloudlet Cloudlets}. 
+ * So, classes extending this must execute Cloudlets. Also, the interface for
  * cloudlet management is also implemented in this class.
+ * Each VM has to have its own instance of a CloudletScheduler.
  * 
  * @author Rodrigo N. Calheiros
  * @author Anton Beloglazov
@@ -26,27 +29,27 @@ public abstract class CloudletScheduler {
 	/** The previous time. */
 	private double previousTime;
 
-	/** The current mips share. */
+	/** The list of current mips share available for the VM using the scheduler. */
 	private List<Double> currentMipsShare;
 
-	/** The cloudlet waiting list. */
+	/** The list of cloudlet waiting to be executed on the VM. */
 	protected List<? extends ResCloudlet> cloudletWaitingList;
 
-	/** The cloudlet exec list. */
+	/** The list of cloudlets being executed on the VM. */
 	protected List<? extends ResCloudlet> cloudletExecList;
 
-	/** The cloudlet paused list. */
+	/** The list of paused cloudlets. */
 	protected List<? extends ResCloudlet> cloudletPausedList;
 
-	/** The cloudlet finished list. */
+	/** The list of finished cloudlets. */
 	protected List<? extends ResCloudlet> cloudletFinishedList;
 
-	/** The cloudlet failed list. */
+	/** The list of failed cloudlets. */
 	protected List<? extends ResCloudlet> cloudletFailedList;
 
 	/**
-	 * Creates a new CloudletScheduler object. This method must be invoked before starting the
-	 * actual simulation.
+	 * Creates a new CloudletScheduler object. 
+         * A CloudletScheduler must be created before starting the actual simulation.
 	 * 
 	 * @pre $none
 	 * @post $none
@@ -64,9 +67,9 @@ public abstract class CloudletScheduler {
 	 * Updates the processing of cloudlets running under management of this scheduler.
 	 * 
 	 * @param currentTime current simulation time
-	 * @param mipsShare array with MIPS share of each processor available to the scheduler
-	 * @return time predicted completion time of the earliest finishing cloudlet, or 0 if there is no
-	 *         next events
+	 * @param mipsShare list with MIPS share of each Pe available to the scheduler
+	 * @return the predicted completion time of the earliest finishing cloudlet, 
+         * or 0 if there is no next events
 	 * @pre currentTime >= 0
 	 * @post $none
 	 */
@@ -75,7 +78,7 @@ public abstract class CloudletScheduler {
 	/**
 	 * Receives an cloudlet to be executed in the VM managed by this scheduler.
 	 * 
-	 * @param gl the submited cloudlet
+	 * @param gl the submited cloudlet (@todo it's a strange param name)
 	 * @param fileTransferTime time required to move the required files from the SAN to the VM
 	 * @return expected finish time of this cloudlet, or 0 if it is in a waiting queue
 	 * @pre gl != null
@@ -96,7 +99,7 @@ public abstract class CloudletScheduler {
 	/**
 	 * Cancels execution of a cloudlet.
 	 * 
-	 * @param clId ID of the cloudlet being cancealed
+	 * @param clId ID of the cloudlet being canceled
 	 * @return the canceled cloudlet, $null if not found
 	 * @pre $none
 	 * @post $none
@@ -139,31 +142,34 @@ public abstract class CloudletScheduler {
 	 * @return status of the cloudlet, -1 if cloudlet not found
 	 * @pre $none
 	 * @post $none
+         * 
+         * @todo cloudlet status should be an enum
 	 */
 	public abstract int getCloudletStatus(int clId);
 
 	/**
-	 * Informs about completion of some cloudlet in the VM managed by this scheduler.
+	 * Informs if there is any cloudlet that finished to execute in the VM managed by this scheduler.
 	 * 
 	 * @return $true if there is at least one finished cloudlet; $false otherwise
 	 * @pre $none
 	 * @post $none
+         * @todo the method name would be isThereFinishedCloudlets to be clearer
 	 */
 	public abstract boolean isFinishedCloudlets();
 
 	/**
-	 * Returns the next cloudlet in the finished list, $null if this list is empty.
+	 * Returns the next cloudlet in the finished list.
 	 * 
-	 * @return a finished cloudlet
+	 * @return a finished cloudlet or $null if the respective list is empty
 	 * @pre $none
 	 * @post $none
 	 */
 	public abstract Cloudlet getNextFinishedCloudlet();
 
 	/**
-	 * Returns the number of cloudlets runnning in the virtual machine.
+	 * Returns the number of cloudlets running in the virtual machine.
 	 * 
-	 * @return number of cloudlets runnning
+	 * @return number of cloudlets running
 	 * @pre $none
 	 * @post $none
 	 */
@@ -179,9 +185,10 @@ public abstract class CloudletScheduler {
 	public abstract Cloudlet migrateCloudlet();
 
 	/**
-	 * Get utilization created by all cloudlets.
+	 * Gets total CPU utilization percentage of all cloudlets, according to CPU UtilizationModel of 
+         * each one.
 	 * 
-	 * @param time the time
+	 * @param time the time to get the current CPU utilization
 	 * @return total utilization
 	 */
 	public abstract double getTotalUtilizationOfCpu(double time);
@@ -194,20 +201,29 @@ public abstract class CloudletScheduler {
 	public abstract List<Double> getCurrentRequestedMips();
 
 	/**
-	 * Gets the total current mips for the Cloudlet.
+	 * Gets the total current available mips for the Cloudlet.
 	 * 
 	 * @param rcl the rcl
 	 * @param mipsShare the mips share
 	 * @return the total current mips
+         * @todo In fact, this method is returning different data depending 
+         * of the subclass. It is expected that the way the method use to compute
+         * the resulting value can be different in every subclass,
+         * but is not supposed that each subclass returns a complete different 
+         * result for the same method of the superclass.
+         * In some class such as {@link NetworkCloudletSpaceSharedScheduler},
+         * the method returns the average MIPS for the available PEs,
+         * in other classes such as {@link CloudletSchedulerDynamicWorkload} it returns
+         * the MIPS' sum of all PEs.
 	 */
 	public abstract double getTotalCurrentAvailableMipsForCloudlet(ResCloudlet rcl, List<Double> mipsShare);
 
 	/**
-	 * Gets the total current requested mips for cloudlet.
+	 * Gets the total current requested mips for a given cloudlet.
 	 * 
 	 * @param rcl the rcl
 	 * @param time the time
-	 * @return the total current requested mips for cloudlet
+	 * @return the total current requested mips for the given cloudlet
 	 */
 	public abstract double getTotalCurrentRequestedMipsForCloudlet(ResCloudlet rcl, double time);
 

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/CloudletSchedulerDynamicWorkload.java

@@ -16,56 +16,66 @@ import org.cloudbus.cloudsim.core.CloudSim;
 
 /**
  * CloudletSchedulerDynamicWorkload implements a policy of scheduling performed by a virtual machine
- * assuming that there is just one cloudlet which is working as an online service.
+ * to run its {@link Cloudlet Cloudlets}, 
+ * assuming there is just one cloudlet which is working as an online service.
+ * It extends a TimeShared policy, but in fact, considering that there is just
+ * one cloudlet for the VM using this scheduler, the cloudlet will not
+ * compete for CPU with other ones.
+ * Each VM has to have its own instance of a CloudletScheduler.
  * 
  * @author Anton Beloglazov
  * @since CloudSim Toolkit 2.0
+ * @todo The name of the class doesn't represent its goal. A clearer name would be
+ * CloudletSchedulerSingleService as its Test Suite
  */
 public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShared {
 
-	/** The mips. */
+	/** The individual MIPS capacity of each PE allocated to the VM using the scheduler,
+         * considering that all PEs have the same capacity. 
+         * @todo Despite of the class considers that all PEs have the same capacity,
+         * it accepts a list of PEs with different MIPS at the method 
+         * {@link #updateVmProcessing(double, java.util.List) }
+         */
 	private double mips;
 
-	/** The number of PEs. */
+	/** The number of PEs allocated to the VM using the scheduler. */
 	private int numberOfPes;
 
-	/** The total mips. */
+	/** The total MIPS considering all PEs. */
 	private double totalMips;
 
-	/** The under allocated mips. */
+	/** The under allocated MIPS. */
 	private Map<String, Double> underAllocatedMips;
 
-	/** The cache previous time. */
+	/** The cache of the previous time when the {@link #getCurrentRequestedMips()} was called. */
 	private double cachePreviousTime;
 
-	/** The cache current requested mips. */
+	/** The cache of the last current requested MIPS. 
+         * @see  #getCurrentRequestedMips() 
+         */
 	private List<Double> cacheCurrentRequestedMips;
 
 	/**
-	 * Instantiates a new vM scheduler time shared.
+	 * Instantiates a new VM scheduler
 	 * 
-	 * @param mips the mips
-	 * @param numberOfPes the pes number
+	 * @param mips The individual MIPS capacity of each PE allocated to the VM using the scheduler,
+         * considering that all PEs have the same capacity.
+	 * @param numberOfPes The number of PEs allocated to the VM using the scheduler.
 	 */
 	public CloudletSchedulerDynamicWorkload(double mips, int numberOfPes) {
 		super();
 		setMips(mips);
 		setNumberOfPes(numberOfPes);
+                /*@todo There shouldn't be a setter to total mips, considering
+                that it is computed from number of PEs and mips.
+                If the number of pes of mips is set any time after here,
+                the total mips will be wrong. Just the getTotalMips is enough,
+                and it have to compute there the total, instead of storing into an attribute.*/
 		setTotalMips(getNumberOfPes() * getMips());
 		setUnderAllocatedMips(new HashMap<String, Double>());
 		setCachePreviousTime(-1);
 	}
 
-	/**
-	 * Updates the processing of cloudlets running under management of this scheduler.
-	 * 
-	 * @param currentTime current simulation time
-	 * @param mipsShare array with MIPS share of each Pe available to the scheduler
-	 * @return time predicted completion time of the earliest finishing cloudlet, or 0 if there is
-	 *         no next events
-	 * @pre currentTime >= 0
-	 * @post $none
-	 */
 	@Override
 	public double updateVmProcessing(double currentTime, List<Double> mipsShare) {
 		setCurrentMipsShare(mipsShare);
@@ -106,28 +116,11 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 		return nextEvent;
 	}
 
-	/**
-	 * Receives an cloudlet to be executed in the VM managed by this scheduler.
-	 * 
-	 * @param cl the cl
-	 * @return predicted completion time
-	 * @pre _gl != null
-	 * @post $none
-	 */
 	@Override
 	public double cloudletSubmit(Cloudlet cl) {
 		return cloudletSubmit(cl, 0);
 	}
 
-	/**
-	 * Receives an cloudlet to be executed in the VM managed by this scheduler.
-	 * 
-	 * @param cl the cl
-	 * @param fileTransferTime the file transfer time
-	 * @return predicted completion time
-	 * @pre _gl != null
-	 * @post $none
-	 */
 	@Override
 	public double cloudletSubmit(Cloudlet cl, double fileTransferTime) {
 		ResCloudlet rcl = new ResCloudlet(cl);
@@ -141,13 +134,6 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 		return getEstimatedFinishTime(rcl, getPreviousTime());
 	}
 
-	/**
-	 * Processes a finished cloudlet.
-	 * 
-	 * @param rcl finished cloudlet
-	 * @pre rgl != $null
-	 * @post $none
-	 */
 	@Override
 	public void cloudletFinish(ResCloudlet rcl) {
 		rcl.setCloudletStatus(Cloudlet.SUCCESS);
@@ -155,12 +141,6 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 		getCloudletFinishedList().add(rcl);
 	}
 
-	/**
-	 * Get utilization created by all cloudlets.
-	 * 
-	 * @param time the time
-	 * @return total utilization
-	 */
 	@Override
 	public double getTotalUtilizationOfCpu(double time) {
 		double totalUtilization = 0;
@@ -170,11 +150,6 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 		return totalUtilization;
 	}
 
-	/**
-	 * Gets the current mips.
-	 * 
-	 * @return the current mips
-	 */
 	@Override
 	public List<Double> getCurrentRequestedMips() {
 		if (getCachePreviousTime() == getPreviousTime()) {
@@ -194,25 +169,11 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 		return currentMips;
 	}
 
-	/**
-	 * Gets the current mips.
-	 * 
-	 * @param rcl the rcl
-	 * @param time the time
-	 * @return the current mips
-	 */
 	@Override
 	public double getTotalCurrentRequestedMipsForCloudlet(ResCloudlet rcl, double time) {
 		return rcl.getCloudlet().getUtilizationOfCpu(time) * getTotalMips();
 	}
 
-	/**
-	 * Gets the total current mips for the clouddlet.
-	 * 
-	 * @param rcl the rcl
-	 * @param mipsShare the mips share
-	 * @return the total current mips
-	 */
 	@Override
 	public double getTotalCurrentAvailableMipsForCloudlet(ResCloudlet rcl, List<Double> mipsShare) {
 		double totalCurrentMips = 0.0;
@@ -229,13 +190,6 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 		return totalCurrentMips;
 	}
 
-	/**
-	 * Gets the current mips.
-	 * 
-	 * @param rcl the rcl
-	 * @param time the time
-	 * @return the current mips
-	 */
 	@Override
 	public double getTotalCurrentAllocatedMipsForCloudlet(ResCloudlet rcl, double time) {
 		double totalCurrentRequestedMips = getTotalCurrentRequestedMipsForCloudlet(rcl, time);
@@ -251,6 +205,8 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 	 * 
 	 * @param rcl the rgl
 	 * @param mips the mips
+         * @todo It is not clear the goal of this method. The related test case
+         * doesn't make it clear too. The method doesn't appear to be used anywhere.
 	 */
 	public void updateUnderAllocatedMipsForCloudlet(ResCloudlet rcl, double mips) {
 		if (getUnderAllocatedMips().containsKey(rcl.getUid())) {
@@ -260,9 +216,9 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 	}
 
 	/**
-	 * Get estimated cloudlet completion time.
+	 * Get the estimated completion time of a given cloudlet.
 	 * 
-	 * @param rcl the rcl
+	 * @param rcl the cloudlet
 	 * @param time the time
 	 * @return the estimated finish time
 	 */
@@ -272,7 +228,8 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 	}
 
 	/**
-	 * Gets the total current mips.
+	 * Gets the total current mips available for the VM using the scheduler.
+         * The total is computed from the {@link #getCurrentMipsShare()}
 	 * 
 	 * @return the total current mips
 	 */
@@ -357,7 +314,7 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 	}
 
 	/**
-	 * Gets the cache previous time.
+	 * Gets the cache of previous time.
 	 * 
 	 * @return the cache previous time
 	 */
@@ -366,7 +323,7 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 	}
 
 	/**
-	 * Sets the cache previous time.
+	 * Sets the cache of previous time.
 	 * 
 	 * @param cachePreviousTime the new cache previous time
 	 */
@@ -375,7 +332,7 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 	}
 
 	/**
-	 * Gets the cache current requested mips.
+	 * Gets the cache of current requested mips.
 	 * 
 	 * @return the cache current requested mips
 	 */
@@ -384,7 +341,7 @@ public class CloudletSchedulerDynamicWorkload extends CloudletSchedulerTimeShare
 	}
 
 	/**
-	 * Sets the cache current requested mips.
+	 * Sets the cache of current requested mips.
 	 * 
 	 * @param cacheCurrentRequestedMips the new cache current requested mips
 	 */

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/CloudletSchedulerSpaceShared.java

@@ -14,8 +14,9 @@ import java.util.List;
 import org.cloudbus.cloudsim.core.CloudSim;
 
 /**
- * CloudletSchedulerSpaceShared implements a policy of scheduling performed by a virtual machine. It
- * consider that there will be only one cloudlet per VM. Other cloudlets will be in a waiting list.
+ * CloudletSchedulerSpaceShared implements a policy of scheduling performed by a virtual machine
+ * to run its {@link Cloudlet Cloudlets}.
+ * It consider there will be only one cloudlet per VM. Other cloudlets will be in a waiting list.
  * We consider that file transfer from cloudlets waiting happens before cloudlet execution. I.e.,
  * even though cloudlets must wait for CPU, data transfer happens as soon as cloudlets are
  * submitted.
@@ -25,11 +26,12 @@ import org.cloudbus.cloudsim.core.CloudSim;
  * @since CloudSim Toolkit 1.0
  */
 public class CloudletSchedulerSpaceShared extends CloudletScheduler {
-
-	/** The current CPUs. */
+	/** The number of PEs currently available for the VM using the scheduler,
+         * according to the mips share provided to it by
+         * {@link #updateVmProcessing(double, java.util.List)} method. */
 	protected int currentCpus;
 
-	/** The used PEs. */
+	/** The number of used PEs. */
 	protected int usedPes;
 
 	/**
@@ -45,16 +47,6 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		currentCpus = 0;
 	}
 
-	/**
-	 * Updates the processing of cloudlets running under management of this scheduler.
-	 * 
-	 * @param currentTime current simulation time
-	 * @param mipsShare array with MIPS share of each processor available to the scheduler
-	 * @return time predicted completion time of the earliest finishing cloudlet, or 0 if there is
-	 *         no next events
-	 * @pre currentTime >= 0
-	 * @post $none
-	 */
 	@Override
 	public double updateVmProcessing(double currentTime, List<Double> mipsShare) {
 		setCurrentMipsShare(mipsShare);
@@ -73,7 +65,8 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 
 		// each machine in the exec list has the same amount of cpu
 		for (ResCloudlet rcl : getCloudletExecList()) {
-			rcl.updateCloudletFinishedSoFar((long) (capacity * timeSpam * rcl.getNumberOfPes() * Consts.MILLION));
+			rcl.updateCloudletFinishedSoFar(
+                                (long) (capacity * timeSpam * rcl.getNumberOfPes() * Consts.MILLION));
 		}
 
 		// no more cloudlets in this scheduler
@@ -131,14 +124,6 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		return nextEvent;
 	}
 
-	/**
-	 * Cancels execution of a cloudlet.
-	 * 
-	 * @param cloudletId ID of the cloudlet being cancealed
-	 * @return the canceled cloudlet, $null if not found
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public Cloudlet cloudletCancel(int cloudletId) {
 		// First, looks in the finished queue
@@ -183,14 +168,6 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 
 	}
 
-	/**
-	 * Pauses execution of a cloudlet.
-	 * 
-	 * @param cloudletId ID of the cloudlet being paused
-	 * @return $true if cloudlet paused, $false otherwise
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public boolean cloudletPause(int cloudletId) {
 		boolean found = false;
@@ -245,13 +222,6 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		return false;
 	}
 
-	/**
-	 * Processes a finished cloudlet.
-	 * 
-	 * @param rcl finished cloudlet
-	 * @pre rgl != $null
-	 * @post $none
-	 */
 	@Override
 	public void cloudletFinish(ResCloudlet rcl) {
 		rcl.setCloudletStatus(Cloudlet.SUCCESS);
@@ -260,14 +230,6 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		usedPes -= rcl.getNumberOfPes();
 	}
 
-	/**
-	 * Resumes execution of a paused cloudlet.
-	 * 
-	 * @param cloudletId ID of the cloudlet being resumed
-	 * @return $true if the cloudlet was resumed, $false otherwise
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public double cloudletResume(int cloudletId) {
 		boolean found = false;
@@ -334,15 +296,6 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 
 	}
 
-	/**
-	 * Receives an cloudlet to be executed in the VM managed by this scheduler.
-	 * 
-	 * @param cloudlet the submited cloudlet
-	 * @param fileTransferTime time required to move the required files from the SAN to the VM
-	 * @return expected finish time of this cloudlet, or 0 if it is in the waiting queue
-	 * @pre gl != null
-	 * @post $none
-	 */
 	@Override
 	public double cloudletSubmit(Cloudlet cloudlet, double fileTransferTime) {
 		// it can go to the exec list
@@ -383,23 +336,11 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		return cloudlet.getCloudletLength() / capacity;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.CloudletScheduler#cloudletSubmit(cloudsim.Cloudlet)
-	 */
 	@Override
 	public double cloudletSubmit(Cloudlet cloudlet) {
 		return cloudletSubmit(cloudlet, 0.0);
 	}
 
-	/**
-	 * Gets the status of a cloudlet.
-	 * 
-	 * @param cloudletId ID of the cloudlet
-	 * @return status of the cloudlet, -1 if cloudlet not found
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public int getCloudletStatus(int cloudletId) {
 		for (ResCloudlet rcl : getCloudletExecList()) {
@@ -423,12 +364,6 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		return -1;
 	}
 
-	/**
-	 * Get utilization created by all cloudlets.
-	 * 
-	 * @param time the time
-	 * @return total utilization
-	 */
 	@Override
 	public double getTotalUtilizationOfCpu(double time) {
 		double totalUtilization = 0;
@@ -438,25 +373,11 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		return totalUtilization;
 	}
 
-	/**
-	 * Informs about completion of some cloudlet in the VM managed by this scheduler.
-	 * 
-	 * @return $true if there is at least one finished cloudlet; $false otherwise
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public boolean isFinishedCloudlets() {
 		return getCloudletFinishedList().size() > 0;
 	}
 
-	/**
-	 * Returns the next cloudlet in the finished list, $null if this list is empty.
-	 * 
-	 * @return a finished cloudlet
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public Cloudlet getNextFinishedCloudlet() {
 		if (getCloudletFinishedList().size() > 0) {
@@ -465,24 +386,19 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		return null;
 	}
 
-	/**
-	 * Returns the number of cloudlets runnning in the virtual machine.
-	 * 
-	 * @return number of cloudlets runnning
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public int runningCloudlets() {
 		return getCloudletExecList().size();
 	}
 
 	/**
-	 * Returns one cloudlet to migrate to another vm.
+	 * Returns the first cloudlet to migrate to another VM.
 	 * 
-	 * @return one running cloudlet
+	 * @return the first running cloudlet
 	 * @pre $none
 	 * @post $none
+         * 
+         * @todo it doesn't check if the list is empty
 	 */
 	@Override
 	public Cloudlet migrateCloudlet() {
@@ -493,10 +409,6 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		return cl;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see org.cloudbus.cloudsim.CloudletScheduler#getCurrentRequestedMips()
-	 */
 	@Override
 	public List<Double> getCurrentRequestedMips() {
 		List<Double> mipsShare = new ArrayList<Double>();
@@ -508,14 +420,9 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		return mipsShare;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see
-	 * org.cloudbus.cloudsim.CloudletScheduler#getTotalCurrentAvailableMipsForCloudlet(org.cloudbus
-	 * .cloudsim.ResCloudlet, java.util.List)
-	 */
 	@Override
 	public double getTotalCurrentAvailableMipsForCloudlet(ResCloudlet rcl, List<Double> mipsShare) {
+                /*@todo The param rcl is not being used.*/
 		double capacity = 0.0;
 		int cpus = 0;
 		for (Double mips : mipsShare) { // count the cpus available to the vmm
@@ -529,38 +436,30 @@ public class CloudletSchedulerSpaceShared extends CloudletScheduler {
 		return capacity;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see
-	 * org.cloudbus.cloudsim.CloudletScheduler#getTotalCurrentAllocatedMipsForCloudlet(org.cloudbus
-	 * .cloudsim.ResCloudlet, double)
-	 */
 	@Override
-	public double getTotalCurrentAllocatedMipsForCloudlet(ResCloudlet rcl, double time) {
+	public double getTotalCurrentAllocatedMipsForCloudlet(ResCloudlet rcl, double time) {   
+                //@todo the method isn't in fact implemented
 		// TODO Auto-generated method stub
 		return 0.0;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see
-	 * org.cloudbus.cloudsim.CloudletScheduler#getTotalCurrentRequestedMipsForCloudlet(org.cloudbus
-	 * .cloudsim.ResCloudlet, double)
-	 */
 	@Override
 	public double getTotalCurrentRequestedMipsForCloudlet(ResCloudlet rcl, double time) {
+                //@todo the method isn't in fact implemented
 		// TODO Auto-generated method stub
 		return 0.0;
 	}
 
 	@Override
 	public double getCurrentRequestedUtilizationOfRam() {
+                //@todo the method isn't in fact implemented
 		// TODO Auto-generated method stub
 		return 0;
 	}
 
 	@Override
 	public double getCurrentRequestedUtilizationOfBw() {
+                //@todo the method isn't in fact implemented
 		// TODO Auto-generated method stub
 		return 0;
 	}

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/CloudletSchedulerTimeShared.java

@@ -13,16 +13,19 @@ import java.util.List;
 import org.cloudbus.cloudsim.core.CloudSim;
 
 /**
- * CloudletSchedulerTimeShared implements a policy of scheduling performed by a virtual machine.
- * Cloudlets execute time-shared in VM.
+ * CloudletSchedulerTimeShared implements a policy of scheduling performed by a virtual machine
+ * to run its {@link Cloudlet Cloudlets}.
+ * Cloudlets execute in time-shared manner in VM.
+ * Each VM has to have its own instance of a CloudletScheduler.
  * 
  * @author Rodrigo N. Calheiros
  * @author Anton Beloglazov
  * @since CloudSim Toolkit 1.0
  */
 public class CloudletSchedulerTimeShared extends CloudletScheduler {
-
-	/** The current cp us. */
+	/** The number of PEs currently available for the VM using the scheduler,
+         * according to the mips share provided to it by
+         * {@link #updateVmProcessing(double, java.util.List)} method. */
 	protected int currentCPUs;
 
 	/**
@@ -37,16 +40,6 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		currentCPUs = 0;
 	}
 
-	/**
-	 * Updates the processing of cloudlets running under management of this scheduler.
-	 * 
-	 * @param currentTime current simulation time
-	 * @param mipsShare array with MIPS share of each processor available to the scheduler
-	 * @return time predicted completion time of the earliest finishing cloudlet, or 0 if there is
-	 *         no next events
-	 * @pre currentTime >= 0
-	 * @post $none
-	 */
 	@Override
 	public double updateVmProcessing(double currentTime, List<Double> mipsShare) {
 		setCurrentMipsShare(mipsShare);
@@ -92,10 +85,11 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 	}
 
 	/**
-	 * Gets the capacity.
+	 * Gets the individual MIPS capacity available for each PE available for the scheduler,
+         * considering that all PEs have the same capacity.
 	 * 
-	 * @param mipsShare the mips share
-	 * @return the capacity
+	 * @param mipsShare list with MIPS share of each PE available to the scheduler
+	 * @return the capacity of each PE
 	 */
 	protected double getCapacity(List<Double> mipsShare) {
 		double capacity = 0.0;
@@ -121,14 +115,6 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		return capacity;
 	}
 
-	/**
-	 * Cancels execution of a cloudlet.
-	 * 
-	 * @param cloudletId ID of the cloudlet being cancealed
-	 * @return the canceled cloudlet, $null if not found
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public Cloudlet cloudletCancel(int cloudletId) {
 		boolean found = false;
@@ -187,14 +173,6 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		return null;
 	}
 
-	/**
-	 * Pauses execution of a cloudlet.
-	 * 
-	 * @param cloudletId ID of the cloudlet being paused
-	 * @return $true if cloudlet paused, $false otherwise
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public boolean cloudletPause(int cloudletId) {
 		boolean found = false;
@@ -222,13 +200,6 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		return false;
 	}
 
-	/**
-	 * Processes a finished cloudlet.
-	 * 
-	 * @param rcl finished cloudlet
-	 * @pre rgl != $null
-	 * @post $none
-	 */
 	@Override
 	public void cloudletFinish(ResCloudlet rcl) {
 		rcl.setCloudletStatus(Cloudlet.SUCCESS);
@@ -236,14 +207,6 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		getCloudletFinishedList().add(rcl);
 	}
 
-	/**
-	 * Resumes execution of a paused cloudlet.
-	 * 
-	 * @param cloudletId ID of the cloudlet being resumed
-	 * @return expected finish time of the cloudlet, 0.0 if queued
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public double cloudletResume(int cloudletId) {
 		boolean found = false;
@@ -276,15 +239,6 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		return 0.0;
 	}
 
-	/**
-	 * Receives an cloudlet to be executed in the VM managed by this scheduler.
-	 * 
-	 * @param cloudlet the submited cloudlet
-	 * @param fileTransferTime time required to move the required files from the SAN to the VM
-	 * @return expected finish time of this cloudlet
-	 * @pre gl != null
-	 * @post $none
-	 */
 	@Override
 	public double cloudletSubmit(Cloudlet cloudlet, double fileTransferTime) {
 		ResCloudlet rcl = new ResCloudlet(cloudlet);
@@ -304,23 +258,11 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		return cloudlet.getCloudletLength() / getCapacity(getCurrentMipsShare());
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.CloudletScheduler#cloudletSubmit(cloudsim.Cloudlet)
-	 */
 	@Override
 	public double cloudletSubmit(Cloudlet cloudlet) {
 		return cloudletSubmit(cloudlet, 0.0);
 	}
 
-	/**
-	 * Gets the status of a cloudlet.
-	 * 
-	 * @param cloudletId ID of the cloudlet
-	 * @return status of the cloudlet, -1 if cloudlet not found
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public int getCloudletStatus(int cloudletId) {
 		for (ResCloudlet rcl : getCloudletExecList()) {
@@ -336,14 +278,11 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		return -1;
 	}
 
-	/**
-	 * Get utilization created by all cloudlets.
-	 * 
-	 * @param time the time
-	 * @return total utilization
-	 */
 	@Override
 	public double getTotalUtilizationOfCpu(double time) {
+                /*
+                 * @todo 
+                 */
 		double totalUtilization = 0;
 		for (ResCloudlet gl : getCloudletExecList()) {
 			totalUtilization += gl.getCloudlet().getUtilizationOfCpu(time);
@@ -351,25 +290,11 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		return totalUtilization;
 	}
 
-	/**
-	 * Informs about completion of some cloudlet in the VM managed by this scheduler.
-	 * 
-	 * @return $true if there is at least one finished cloudlet; $false otherwise
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public boolean isFinishedCloudlets() {
 		return getCloudletFinishedList().size() > 0;
 	}
 
-	/**
-	 * Returns the next cloudlet in the finished list, $null if this list is empty.
-	 * 
-	 * @return a finished cloudlet
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public Cloudlet getNextFinishedCloudlet() {
 		if (getCloudletFinishedList().size() > 0) {
@@ -378,25 +303,11 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		return null;
 	}
 
-	/**
-	 * Returns the number of cloudlets runnning in the virtual machine.
-	 * 
-	 * @return number of cloudlets runnning
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public int runningCloudlets() {
 		return getCloudletExecList().size();
 	}
 
-	/**
-	 * Returns one cloudlet to migrate to another vm.
-	 * 
-	 * @return one running cloudlet
-	 * @pre $none
-	 * @post $none
-	 */
 	@Override
 	public Cloudlet migrateCloudlet() {
 		ResCloudlet rgl = getCloudletExecList().remove(0);
@@ -404,44 +315,27 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 		return rgl.getCloudlet();
 	}
 
-
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.CloudletScheduler#getCurrentRequestedMips()
-	 */
 	@Override
 	public List<Double> getCurrentRequestedMips() {
 		List<Double> mipsShare = new ArrayList<Double>();
 		return mipsShare;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.CloudletScheduler#getTotalCurrentAvailableMipsForCloudlet(cloudsim.ResCloudlet,
-	 * java.util.List)
-	 */
 	@Override
 	public double getTotalCurrentAvailableMipsForCloudlet(ResCloudlet rcl, List<Double> mipsShare) {
-		return getCapacity(getCurrentMipsShare());
+            /*@todo It isn't being used any the the given parameters.*/
+            return getCapacity(getCurrentMipsShare());
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.CloudletScheduler#getTotalCurrentAllocatedMipsForCloudlet(cloudsim.ResCloudlet,
-	 * double)
-	 */
 	@Override
 	public double getTotalCurrentAllocatedMipsForCloudlet(ResCloudlet rcl, double time) {
+                //@todo The method is not implemented, in fact
 		return 0.0;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.CloudletScheduler#getTotalCurrentRequestedMipsForCloudlet(cloudsim.ResCloudlet,
-	 * double)
-	 */
 	@Override
 	public double getTotalCurrentRequestedMipsForCloudlet(ResCloudlet rcl, double time) {
+                //@todo The method is not implemented, in fact
 		// TODO Auto-generated method stub
 		return 0.0;
 	}

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/Consts.java

@@ -14,21 +14,21 @@ public final class Consts {
     }
 
     /** One million. */
-    public static int MILLION = 1000000;
+    public static final int MILLION = 1000000;
 
     // ================== Time constants ==================
     /** One minute time in seconds. */
-    public static int MINUTE = 60;
+    public static final int MINUTE = 60;
     /** One hour time in seconds. */
-    public static int HOUR = 60 * MINUTE;
+    public static final int HOUR = 60 * MINUTE;
     /** One day time in seconds. */
-    public static int DAY = 24 * HOUR;
+    public static final int DAY = 24 * HOUR;
     /** One week time in seconds. */
-    public static int WEEK = 24 * HOUR;
+    public static final int WEEK = 24 * HOUR;
 
     // ================== OS constants ==================
-    /** Constant for *nix OS-es. */
+    /** Constant for *nix Operating Systems. */
     public static final String NIX_OS = "Linux/Unix";
-    /** Constant for Windows OS-es. */
+    /** Constant for Windows Operating Systems. */
     public static final String WINDOWS = "Windows";
 }

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/DatacenterBroker.java

@@ -23,7 +23,7 @@ import org.cloudbus.cloudsim.lists.VmList;
 
 /**
  * DatacentreBroker represents a broker acting on behalf of a user. It hides VM management, as vm
- * creation, sumbission of cloudlets to this VMs and destruction of VMs.
+ * creation, submission of cloudlets to VMs and destruction of VMs.
  * 
  * @author Rodrigo N. Calheiros
  * @author Anton Beloglazov
@@ -31,50 +31,54 @@ import org.cloudbus.cloudsim.lists.VmList;
  */
 public class DatacenterBroker extends SimEntity {
 
-	/** The vm list. */
+	/** The list of VMs submitted to be managed by the broker. */
 	protected List<? extends Vm> vmList;
 
-	/** The vms created list. */
+	/** The list of VMs created by the broker. */
 	protected List<? extends Vm> vmsCreatedList;
 
-	/** The cloudlet list. */
+	/** The list of cloudlet submitted to the broker. 
+         * @see #submitCloudletList(java.util.List) 
+         */
 	protected List<? extends Cloudlet> cloudletList;
 
-	/** The cloudlet submitted list. */
+	/** The list of submitted cloudlets. */
 	protected List<? extends Cloudlet> cloudletSubmittedList;
 
-	/** The cloudlet received list. */
+	/** The list of received cloudlet. */
 	protected List<? extends Cloudlet> cloudletReceivedList;
 
-	/** The cloudlets submitted. */
+	/** The number of submitted cloudlets. */
 	protected int cloudletsSubmitted;
 
-	/** The vms requested. */
+	/** The number of requests to create VM. */
 	protected int vmsRequested;
 
-	/** The vms acks. */
+	/** The number of acknowledges (ACKs) sent in response to
+         * VM creation requests. */
 	protected int vmsAcks;
 
-	/** The vms destroyed. */
+	/** The number of destroyed VMs. */
 	protected int vmsDestroyed;
 
-	/** The datacenter ids list. */
+	/** The id's list of available datacenters. */
 	protected List<Integer> datacenterIdsList;
 
-	/** The datacenter requested ids list. */
+	/** The list of datacenters where was requested to place VMs. */
 	protected List<Integer> datacenterRequestedIdsList;
 
-	/** The vms to datacenters map. */
+	/** The vms to datacenters map, where each key is a VM id
+         * and each value is the datacenter id whwere the VM is placed. */
 	protected Map<Integer, Integer> vmsToDatacentersMap;
 
-	/** The datacenter characteristics list. */
+	/** The datacenter characteristics map where each key
+         * is a datacenter id and each value is its characteristics.. */
 	protected Map<Integer, DatacenterCharacteristics> datacenterCharacteristicsList;
 
 	/**
 	 * Created a new DatacenterBroker object.
 	 * 
-	 * @param name name to be associated with this entity (as required by Sim_entity class from
-	 *            simjava package)
+	 * @param name name to be associated with this entity (as required by {@link SimEntity} class)
 	 * @throws Exception the exception
 	 * @pre name != null
 	 * @post $none
@@ -117,6 +121,13 @@ public class DatacenterBroker extends SimEntity {
 	 * @param list the list
 	 * @pre list !=null
 	 * @post $none
+         * 
+         * @todo The name of the method is confused with the {@link #submitCloudlets()},
+         * that in fact submit cloudlets to VMs. The term "submit" is being used
+         * ambiguously. The method {@link #submitCloudlets()} would be named "sendCloudletsToVMs"
+         * 
+         * The method {@link #submitVmList(java.util.List)} may have
+         * be checked too.
 	 */
 	public void submitCloudletList(List<? extends Cloudlet> list) {
 		getCloudletList().addAll(list);
@@ -135,13 +146,6 @@ public class DatacenterBroker extends SimEntity {
 		CloudletList.getById(getCloudletList(), cloudletId).setVmId(vmId);
 	}
 
-	/**
-	 * Processes events available for this Broker.
-	 * 
-	 * @param ev a SimEvent object
-	 * @pre ev != null
-	 * @post $none
-	 */
 	@Override
 	public void processEvent(SimEvent ev) {
 		switch (ev.getTag()) {
@@ -173,7 +177,7 @@ public class DatacenterBroker extends SimEntity {
 	}
 
 	/**
-	 * Process the return of a request for the characteristics of a PowerDatacenter.
+	 * Process the return of a request for the characteristics of a Datacenter.
 	 * 
 	 * @param ev a SimEvent object
 	 * @pre ev != $null
@@ -289,12 +293,16 @@ public class DatacenterBroker extends SimEntity {
 	}
 
 	/**
-	 * Overrides this method when making a new and different type of Broker. This method is called
-	 * by {@link #body()} for incoming unknown tags.
+	 * Process non-default received events that aren't processed by
+         * the {@link #processEvent(org.cloudbus.cloudsim.core.SimEvent)} method.
+         * This method should be overridden by subclasses in other to process
+         * new defined events.
 	 * 
 	 * @param ev a SimEvent object
 	 * @pre ev != null
 	 * @post $none
+         * @todo to ensure the method will be overridden, it should be defined 
+         * as abstract in a super class from where new brokers have to be extended.
 	 */
 	protected void processOtherEvent(SimEvent ev) {
 		if (ev == null) {
@@ -306,11 +314,12 @@ public class DatacenterBroker extends SimEntity {
 	}
 
 	/**
-	 * Create the virtual machines in a datacenter.
+	 * Create the submitted virtual machines in a datacenter.
 	 * 
-	 * @param datacenterId Id of the chosen PowerDatacenter
+	 * @param datacenterId Id of the chosen Datacenter
 	 * @pre $none
 	 * @post $none
+         * @see #submitVmList(java.util.List) 
 	 */
 	protected void createVmsInDatacenter(int datacenterId) {
 		// send as much vms as possible for this datacenter before trying the next one
@@ -336,6 +345,7 @@ public class DatacenterBroker extends SimEntity {
 	 * 
 	 * @pre $none
 	 * @post $none
+         * @see #submitCloudletList(java.util.List) 
 	 */
 	protected void submitCloudlets() {
 		int vmIndex = 0;
@@ -374,7 +384,7 @@ public class DatacenterBroker extends SimEntity {
 	}
 
 	/**
-	 * Destroy the virtual machines running in datacenters.
+	 * Destroy all virtual machines running in datacenters.
 	 * 
 	 * @pre $none
 	 * @post $none
@@ -398,19 +408,11 @@ public class DatacenterBroker extends SimEntity {
 		sendNow(getId(), CloudSimTags.END_OF_SIMULATION);
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.core.SimEntity#shutdownEntity()
-	 */
 	@Override
 	public void shutdownEntity() {
 		Log.printConcatLine(getName(), " is shutting down...");
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.core.SimEntity#startEntity()
-	 */
 	@Override
 	public void startEntity() {
 		Log.printConcatLine(getName(), " is starting...");
@@ -559,7 +561,8 @@ public class DatacenterBroker extends SimEntity {
 	}
 
 	/**
-	 * Increment vms acks.
+	 * Increment the number of acknowledges (ACKs) sent in response
+         * to requests of VM creation.
 	 */
 	protected void incrementVmsAcks() {
 		vmsAcks++;

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/HostDynamicWorkload.java

@@ -18,7 +18,7 @@ import org.cloudbus.cloudsim.provisioners.BwProvisioner;
 import org.cloudbus.cloudsim.provisioners.RamProvisioner;
 
 /**
- * The class of a host supporting dynamic workloads and performance degradation.
+ * A host supporting dynamic workloads and performance degradation.
  * 
  * @author Anton Beloglazov
  * @since CloudSim Toolkit 2.0
@@ -31,7 +31,7 @@ public class HostDynamicWorkload extends Host {
 	/** The previous utilization mips. */
 	private double previousUtilizationMips;
 
-	/** The state history. */
+	/** The host utilization state history. */
 	private final List<HostStateHistoryEntry> stateHistory = new LinkedList<HostStateHistoryEntry>();
 
 	/**
@@ -40,8 +40,8 @@ public class HostDynamicWorkload extends Host {
 	 * @param id the id
 	 * @param ramProvisioner the ram provisioner
 	 * @param bwProvisioner the bw provisioner
-	 * @param storage the storage
-	 * @param peList the pe list
+	 * @param storage the storage capacity
+	 * @param peList the host's PEs list
 	 * @param vmScheduler the VM scheduler
 	 */
 	public HostDynamicWorkload(
@@ -56,10 +56,6 @@ public class HostDynamicWorkload extends Host {
 		setPreviousUtilizationMips(0);
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.Host#updateVmsProcessing(double)
-	 */
 	@Override
 	public double updateVmsProcessing(double currentTime) {
 		double smallerTime = super.updateVmsProcessing(currentTime);
@@ -140,7 +136,7 @@ public class HostDynamicWorkload extends Host {
 	}
 
 	/**
-	 * Gets the completed vms.
+	 * Gets the list of completed vms.
 	 * 
 	 * @return the completed vms
 	 */
@@ -158,26 +154,26 @@ public class HostDynamicWorkload extends Host {
 	}
 
 	/**
-	 * Gets the max utilization among by all PEs.
+	 * Gets the max utilization percentage among by all PEs.
 	 * 
-	 * @return the utilization
+	 * @return the maximum utilization percentage
 	 */
 	public double getMaxUtilization() {
 		return PeList.getMaxUtilization(getPeList());
 	}
 
 	/**
-	 * Gets the max utilization among by all PEs allocated to the VM.
+	 * Gets the max utilization percentage among by all PEs allocated to a VM.
 	 * 
 	 * @param vm the vm
-	 * @return the utilization
+	 * @return the max utilization percentage of the VM
 	 */
 	public double getMaxUtilizationAmongVmsPes(Vm vm) {
 		return PeList.getMaxUtilizationAmongVmsPes(getPeList(), vm);
 	}
 
 	/**
-	 * Gets the utilization of memory.
+	 * Gets the utilization of memory (in absolute values).
 	 * 
 	 * @return the utilization of memory
 	 */
@@ -186,7 +182,7 @@ public class HostDynamicWorkload extends Host {
 	}
 
 	/**
-	 * Gets the utilization of bw.
+	 * Gets the utilization of bw (in absolute values).
 	 * 
 	 * @return the utilization of bw
 	 */
@@ -210,7 +206,7 @@ public class HostDynamicWorkload extends Host {
 	/**
 	 * Gets the previous utilization of CPU in percentage.
 	 * 
-	 * @return the previous utilization of cpu
+	 * @return the previous utilization of cpu in percents
 	 */
 	public double getPreviousUtilizationOfCpu() {
 		double utilization = getPreviousUtilizationMips() / getTotalMips();
@@ -224,15 +220,17 @@ public class HostDynamicWorkload extends Host {
 	 * Get current utilization of CPU in MIPS.
 	 * 
 	 * @return current utilization of CPU in MIPS
+         * @todo This method only calls the  {@link #getUtilizationMips()}.
+         * getUtilizationMips may be deprecated and its code copied here.
 	 */
 	public double getUtilizationOfCpuMips() {
 		return getUtilizationMips();
 	}
 
 	/**
-	 * Gets the utilization mips.
+	 * Gets the utilization of CPU in MIPS.
 	 * 
-	 * @return the utilization mips
+	 * @return current utilization of CPU in MIPS
 	 */
 	public double getUtilizationMips() {
 		return utilizationMips;
@@ -248,25 +246,25 @@ public class HostDynamicWorkload extends Host {
 	}
 
 	/**
-	 * Gets the previous utilization mips.
+	 * Gets the previous utilization of CPU in mips.
 	 * 
-	 * @return the previous utilization mips
+	 * @return the previous utilization of CPU in mips
 	 */
 	public double getPreviousUtilizationMips() {
 		return previousUtilizationMips;
 	}
 
 	/**
-	 * Sets the previous utilization mips.
+	 * Sets the previous utilization of CPU in mips.
 	 * 
-	 * @param previousUtilizationMips the new previous utilization mips
+	 * @param previousUtilizationMips the new previous utilization of CPU in mips
 	 */
 	protected void setPreviousUtilizationMips(double previousUtilizationMips) {
 		this.previousUtilizationMips = previousUtilizationMips;
 	}
 
 	/**
-	 * Gets the state history.
+	 * Gets the host state history.
 	 * 
 	 * @return the state history
 	 */
@@ -275,7 +273,7 @@ public class HostDynamicWorkload extends Host {
 	}
 
 	/**
-	 * Adds the state history entry.
+	 * Adds a host state history entry.
 	 * 
 	 * @param time the time
 	 * @param allocatedMips the allocated mips

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/HostStateHistoryEntry.java

@@ -9,7 +9,7 @@
 package org.cloudbus.cloudsim;
 
 /**
- * The Class HostStateHistoryEntry.
+ * Stores historic data about a host.
  * 
  * @author Anton Beloglazov
  * @since CloudSim Toolkit 2.1.2
@@ -25,11 +25,13 @@ public class HostStateHistoryEntry {
 	/** The requested mips. */
 	private double requestedMips;
 
-	/** The is active. */
+	/** Indicates if the host was active in the indicated time. 
+         * @see #time
+         */
 	private boolean isActive;
 
 	/**
-	 * Instantiates a new vm mips allocation history entry.
+	 * Instantiates a new host state history entry.
 	 * 
 	 * @param time the time
 	 * @param allocatedMips the allocated mips

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/Packet.java

@@ -15,7 +15,7 @@
 package org.cloudbus.cloudsim;
 
 /**
- * This class contains the structure for a network packet.
+ * Defines the structure for a network packet.
  * 
  * @author Gokul Poduval
  * @author Chen-Khong Tham, National University of Singapore
@@ -85,6 +85,10 @@ public interface Packet {
 	 * @return the network service type
 	 * @pre $none
 	 * @post $none
+         * 
+         * @todo Is it the Type of Service (ToS) of IPv4, like in
+         * the {@link Cloudlet#netToS}? If yes, so the names would
+         * be standardized.
 	 */
 	int getNetServiceType();