Documentation of package org.cloudbus.cloudsim.core improved.

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

@@ -280,6 +280,9 @@ public class CloudletSchedulerTimeShared extends CloudletScheduler {
 
 	@Override
 	public double getTotalUtilizationOfCpu(double time) {
+                /*
+                 * @todo 
+                 */
 		double totalUtilization = 0;
 		for (ResCloudlet gl : getCloudletExecList()) {
 			totalUtilization += gl.getCloudlet().getUtilizationOfCpu(time);

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

@@ -1045,31 +1045,23 @@ public class Datacenter extends SimEntity {
 		return msg;
 	}
 
-	/*
-	 * (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...");
-		// this resource should register to regional GIS.
-		// However, if not specified, then register to system GIS (the
+		// this resource should register to regional CIS.
+		// However, if not specified, then register to system CIS (the
 		// default CloudInformationService) entity.
 		int gisID = CloudSim.getEntityId(regionalCisName);
 		if (gisID == -1) {
 			gisID = CloudSim.getCloudInfoServiceEntityId();
 		}
 
-		// send the registration to GIS
+		// send the registration to CIS
 		sendNow(gisID, CloudSimTags.REGISTER_RESOURCE, getId());
 		// Below method is for a child class to override
 		registerOtherEntity();

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, submission 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

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

@@ -17,6 +17,8 @@ import java.io.OutputStream;
  * 
  * @author Anton Beloglazov
  * @since CloudSim Toolkit 2.0
+ * @todo To add a method to print formatted text, such as the 
+ * {@link String#format(java.lang.String, java.lang.Object...)} method.
  */
 public class Log {
 

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

@@ -18,7 +18,9 @@ package org.cloudbus.cloudsim;
 public class UtilizationModelFull implements UtilizationModel {
 
 	/**
-	 * Gets the utilization percentage of a given resource.
+	 * Gets the utilization percentage of a given resource
+         * in relation to the total capacity of that resource allocated
+         * to the cloudlet.
          * @param time the time to get the resource usage, that isn't considered
          * for this UtilizationModel.
 	 * @return Always return 1 (100% of utilization), independent of the time.

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

@@ -73,7 +73,14 @@ public class Vm {
 	/** Indicates if the VM is being instantiated. */
 	private boolean beingInstantiated;
 
-	/** The mips allocation history. */
+	/** The mips allocation history. 
+         * @todo Instead of using a list, this attribute would be 
+         * a map, where the key can be the history time
+         * and the value the history itself. 
+         * By this way, if one wants to get the history for a given
+         * time, he/she doesn't have to iterate over the entire list
+         * to find the desired entry.
+         */
 	private final List<VmStateHistoryEntry> stateHistory = new LinkedList<VmStateHistoryEntry>();
 
 	/**

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/CloudInformationService.java

@@ -30,23 +30,37 @@ import org.cloudbus.cloudsim.Log;
  */
 public class CloudInformationService extends SimEntity {
 
-	/** For all types of hostList. */
+	/** A list containing the id of all entities that are registered at the 
+         * Cloud Information Service (CIS). 
+         * @todo It is not clear if this list is a list of host id's or datacenter id's.
+         * The previous attribute documentation just said "For all types of hostList".
+         * It can be seen at the method {@link #processEvent(org.cloudbus.cloudsim.core.SimEvent)}
+         * that the list is updated when a CloudSimTags.REGISTER_RESOURCE event
+         * is received. However, only the Datacenter class sends and event
+         * of this type, including its id as parameter.
+         * 
+         */
 	private final List<Integer> resList;
 
-	/** Only for AR hostList. */
+	/** A list containing only the id of entities with Advanced Reservation feature
+         * that are registered at the CIS. */
 	private final List<Integer> arList;
 
-	/** List of all regional GIS. */
+	/** List of all regional CIS. */
 	private final List<Integer> gisList;
 
 	/**
-	 * Allocates a new CloudInformationService object.
+	 * Instantiates a new CloudInformationService object.
 	 * 
-	 * @param name the name to be associated with this entity (as required by SimEntity class)
-	 * @throws Exception This happens when creating this entity before initialising CloudSim package
+	 * @param name the name to be associated with this entity (as required by {@link SimEntity} class)
+	 * @throws Exception when creating this entity before initialising CloudSim package
 	 *             or this entity name is <tt>null</tt> or empty
 	 * @pre name != null
 	 * @post $none
+         * 
+         * @todo The use of Exception is not recommended. Specific exceptions
+         * would be thrown (such as {@link IllegalArgumentException})
+         * or {@link RuntimeException}
 	 */
 	public CloudInformationService(String name) throws Exception {
 		super(name);
@@ -56,14 +70,14 @@ public class CloudInformationService extends SimEntity {
 	}
 
         /**
-	 * Starts the CloudInformationService entity.
+         * The method has no effect at the current class.
          */
 	@Override
 	public void startEntity() {
 	}
 
 	/**
-	 * Processes events scheduled for this entity.
+	 * Processes events scheduled for the CIS.
 	 * 
 	 * @param ev the event to be handled.
 	 * @see SimEntity#processEvent(SimEvent)
@@ -72,12 +86,12 @@ public class CloudInformationService extends SimEntity {
 	public void processEvent(SimEvent ev) {
 		int id = -1;  // requester id
 		switch (ev.getTag()) {
-		// storing regional GIS id
+		// storing regional CIS id
 			case CloudSimTags.REGISTER_REGIONAL_GIS:
 				gisList.add((Integer) ev.getData());
 				break;
 
-			// request for all regional GIS list
+			// request for all regional CIS list
 			case CloudSimTags.REQUEST_REGIONAL_GIS:
 
 				// Get ID of an entity that send this event
@@ -135,7 +149,7 @@ public class CloudInformationService extends SimEntity {
 	/**
 	 * Gets the list of all CloudResource IDs, including hostList that support Advance Reservation.
 	 * 
-	 * @return LinkedList containing resource IDs. Each ID is represented by an Integer object.
+	 * @return list containing resource IDs. Each ID is represented by an Integer object.
 	 * @pre $none
 	 * @post $none
 	 */
@@ -146,7 +160,7 @@ public class CloudInformationService extends SimEntity {
 	/**
 	 * Gets the list of CloudResource IDs that <b>only</b> support Advanced Reservation.
 	 * 
-	 * @return LinkedList containing resource IDs. Each ID is represented by an Integer object.
+	 * @return list containing resource IDs. Each ID is represented by an Integer object.
 	 * @pre $none
 	 * @post $none
 	 */
@@ -228,10 +242,10 @@ public class CloudInformationService extends SimEntity {
 	// //////////////////////// PROTECTED METHODS ////////////////////////////
 
 	/**
-	 * This method needs to override by a child class for processing other events. These events are
+	 * This method needs to override by child classes for processing other events. These events are
 	 * based on tags that are not mentioned in {@link #body()} method.
 	 * 
-	 * @param ev a Sim_event object
+	 * @param ev a SimEvent object
 	 * @pre ev != null
 	 * @post $none
 	 */
@@ -248,7 +262,7 @@ public class CloudInformationService extends SimEntity {
 
 	/**
 	 * Notifies the registered entities about the end of simulation. This method should be
-	 * overridden by the child class
+	 * overridden by child classes.
 	 */
 	protected void processEndSimulation() {
 		// this should be overridden by the child class
@@ -257,10 +271,10 @@ public class CloudInformationService extends SimEntity {
 	// ////////////////// End of PROTECTED METHODS ///////////////////////////
 
 	/**
-	 * Checks for a list for a particular resource id.
+	 * Checks whether a list contains a particular resource id.
 	 * 
-	 * @param list list of hostList
-	 * @param id a resource ID
+	 * @param list list of resource id
+	 * @param id a resource ID to find
 	 * @return true if a resource is in the list, otherwise false
 	 * @pre list != null
 	 * @pre id > 0
@@ -288,7 +302,7 @@ public class CloudInformationService extends SimEntity {
 	}
 
 	/**
-	 * Tells all registered entities the end of simulation.
+	 * Tells all registered entities about the end of simulation.
 	 * 
 	 * @pre $none
 	 * @post $none
@@ -305,7 +319,8 @@ public class CloudInformationService extends SimEntity {
 	}
 
 	/**
-	 * Sends a signal to all entity IDs mentioned in the given list.
+	 * Sends a {@link CloudSimTags#END_OF_SIMULATION} signal to all entity IDs 
+         * mentioned in the given list.
 	 * 
 	 * @param list List storing entity IDs
 	 * @pre list != null

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/CloudSim.java

@@ -175,7 +175,7 @@ public class CloudSim {
 	 * <p>
 	 * <b>Note</b>: This method should be called after all the entities have been setup and added.
 	 * 
-	 * @return the double
+	 * @return the last clock time
 	 * @throws NullPointerException This happens when creating this entity before initialising
 	 *             CloudSim package or this entity name is <tt>null</tt> or empty.
 	 * @see gridsim.CloudSim#init(int, Calendar, boolean)
@@ -872,7 +872,7 @@ public class CloudSim {
 	 * Start the simulation running. This should be called after all the entities have been setup
 	 * and added, and their ports linked.
 	 * 
-	 * @return the double last clock value
+	 * @return the last clock value
 	 */
 	public static double run() {
 		if (!running) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/CloudSimShutdown.java

@@ -8,13 +8,13 @@
 
 package org.cloudbus.cloudsim.core;
 
-import java.util.Calendar;
+import java.security.InvalidParameterException;
 
 /**
  * CloudimShutdown waits for termination of all CloudSim user entities to determine the end of
  * simulation. This class will be created by CloudSim upon initialisation of the simulation, i.e.
  * done via <tt>CloudSim.init()</tt> method. Hence, do not need to worry about creating an object of
- * this class. This object signals the end of simulation to CloudInformationService (GIS) entity.
+ * this class. This object signals the end of simulation to CloudInformationService (CIS) entity.
  * 
  * @author Manzur Murshed
  * @author Rajkumar Buyya
@@ -22,25 +22,29 @@ import java.util.Calendar;
  */
 public class CloudSimShutdown extends SimEntity {
 
-	/** The num user. */
+	/** The total number of cloud users. */
 	private int numUser;
 
 	/**
-	 * Allocates a new CloudSimShutdown object.
-	 * <p>
-	 * The total number of grid user entity plays an important role to determine whether all
-	 * hostList should be shut down or not. If one or more users are still not finish, then the
-	 * hostList will not be shut down. Therefore, it is important to give a correct number of total
-	 * grid user entity. Otherwise, CloudSim program will hang or encounter a weird behaviour.
+	 * Instantiates a new CloudSimShutdown object.
+	 * <p/>
+	 * The total number of cloud user entities plays an important role to determine whether all
+	 * hostList' should be shut down or not. If one or more users are still not finished, then the
+	 * hostList's will not be shut down. Therefore, it is important to give a correct number of total
+	 * cloud user entities. Otherwise, CloudSim program will hang or encounter a weird behaviour.
 	 * 
-	 * @param name the name to be associated with this entity (as required by SimEntity class)
-	 * @param numUser total number of grid user entity
-	 * @throws Exception This happens when creating this entity before initialising CloudSim package
+	 * @param name the name to be associated with this entity (as required by {@link SimEntity} class)
+	 * @param numUser total number of cloud user entities
+	 * @throws Exception when creating this entity before initialising CloudSim package
 	 *             or this entity name is <tt>null</tt> or empty
-	 * @see gridsim.CloudSim#init(int, Calendar, boolean)
+	 * @see CloudSim#init(int, java.util.Calendar, boolean) 
 	 * @pre name != null
 	 * @pre numUser >= 0
 	 * @post $none
+         * 
+         * @todo The use of Exception is not recommended. Specific exceptions
+         * would be thrown (such as {@link IllegalArgumentException})
+         * or {@link RuntimeException}
 	 */
 	public CloudSimShutdown(String name, int numUser) throws Exception {
 		// NOTE: This entity doesn't use any I/O port.
@@ -50,12 +54,12 @@ public class CloudSimShutdown extends SimEntity {
 	}
 
 	/**
-	 * The main method that shuts down hostList and Cloud Information Service (GIS). In addition,
+	 * The main method that shuts down hostList's and Cloud Information Service (CIS). In addition,
 	 * this method writes down a report at the end of a simulation based on
-	 * <tt>reportWriterName</tt> defined in the Constructor. <br>
-	 * <b>NOTE:</b> This method shuts down grid hostList and GIS entities either <tt>AFTER</tt> all
-	 * grid users have been shut down or an entity requires an abrupt end of the whole simulation.
-	 * In the first case, the number of grid users given in the Constructor <tt>must</tt> be
+	 * <tt>reportWriterName</tt> defined in the Constructor. <br/>
+	 * <b>NOTE:</b> This method shuts down cloud hostList's and CIS entities either <tt>AFTER</tt> all
+	 * cloud users have been shut down or an entity requires an abrupt end of the whole simulation.
+	 * In the first case, the number of cloud users given in the Constructor <tt>must</tt> be
 	 * correct. Otherwise, CloudSim package hangs forever or it does not terminate properly.
 	 * 
 	 * @param ev the ev
@@ -70,18 +74,16 @@ public class CloudSimShutdown extends SimEntity {
 		}
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see org.cloudbus.cloudsim.core.SimEntity#startEntity()
+        /**
+         * The method has no effect at the current class.
          */
 	@Override
 	public void startEntity() {
 		// do nothing
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see org.cloudbus.cloudsim.core.SimEntity#shutdownEntity()
+        /**
+         * The method has no effect at the current class.
          */
 	@Override
 	public void shutdownEntity() {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/CloudSimTags.java

@@ -8,11 +8,15 @@
 
 package org.cloudbus.cloudsim.core;
 
+import org.cloudbus.cloudsim.Datacenter;
+
 /**
  * Contains various static command tags that indicate a type of action that needs to be undertaken
  * by CloudSim entities when they receive or send events. <b>NOTE:</b> To avoid conflicts with other
  * tags, CloudSim reserves negative numbers, 0 - 299, and 9600.
  * 
+ * @todo There aren't negative reserved tags, but only positive tags (with 2 exceptions).
+ * 
  * @author Manzur Murshed
  * @author Rajkumar Buyya
  * @author Anthony Sulistio
@@ -20,25 +24,25 @@ package org.cloudbus.cloudsim.core;
  */
 public class CloudSimTags {
 
-	/** Starting constant value for cloud-related tags **/
+	/** Starting constant value for cloud-related tags. **/
 	private static final int BASE = 0;
 
-	/** Starting constant value for network-related tags **/
+	/** Starting constant value for network-related tags. **/
 	private static final int NETBASE = 100;
 
-	/** Denotes boolean <tt>true</tt> in <tt>int</tt> value */
+	/** Denotes boolean <tt>true</tt> in <tt>int</tt> value. */
 	public static final int TRUE = 1;
 
-	/** Denotes boolean <tt>false</tt> in <tt>int</tt> value */
+	/** Denotes boolean <tt>false</tt> in <tt>int</tt> value. */
 	public static final int FALSE = 0;
 
-	/** Denotes the default baud rate for some CloudSim entities */
+	/** Denotes the default baud rate for CloudSim entities. */
 	public static final int DEFAULT_BAUD_RATE = 9600;
 
-	/** Schedules an entity without any delay */
+	/** Schedules an entity without any delay. */
 	public static final double SCHEDULE_NOW = 0.0;
 
-	/** Denotes the end of simulation */
+	/** Denotes the end of simulation. */
 	public static final int END_OF_SIMULATION = -1;
 
 	/**
@@ -57,37 +61,37 @@ public class CloudSimTags {
 	public static final int EXPERIMENT = BASE + 1;
 
 	/**
-	 * Denotes a grid resource to be registered. This tag is normally used between
-	 * CloudInformationService and CloudResouce entity.
+	 * Denotes a cloud resource to be registered. This tag is normally used between
+	 * {@link CloudInformationService} and CloudResouce entities.
 	 */
 	public static final int REGISTER_RESOURCE = BASE + 2;
 
 	/**
-	 * Denotes a grid resource, that can support advance reservation, to be registered. This tag is
-	 * normally used between CloudInformationService and CloudResouce entity.
+	 * Denotes a cloud resource to be registered, that can support advance reservation. This tag is
+	 * normally used between {@link CloudInformationService} and CloudResouce entity.
 	 */
 	public static final int REGISTER_RESOURCE_AR = BASE + 3;
 
 	/**
-	 * Denotes a list of all hostList, including the ones that can support advance reservation. This
-	 * tag is normally used between CloudInformationService and CloudSim entity.
+	 * Denotes a list of all hostList's, including the ones that can support advance reservation. This
+	 * tag is normally used between {@link CloudInformationService} and CloudSim entity.
 	 */
 	public static final int RESOURCE_LIST = BASE + 4;
 
 	/**
-	 * Denotes a list of hostList that only support advance reservation. This tag is normally used
-	 * between CloudInformationService and CloudSim entity.
+	 * Denotes a list of hostList's that only support advance reservation. This tag is normally used
+	 * between {@link CloudInformationService} and CloudSim entity.
 	 */
 	public static final int RESOURCE_AR_LIST = BASE + 5;
 
 	/**
-	 * Denotes grid resource characteristics information. This tag is normally used between CloudSim
+	 * Denotes cloud resource characteristics information. This tag is normally used between CloudSim
 	 * and CloudResource entity.
 	 */
 	public static final int RESOURCE_CHARACTERISTICS = BASE + 6;
 
 	/**
-	 * Denotes grid resource allocation policy. This tag is normally used between CloudSim and
+	 * Denotes cloud resource allocation policy. This tag is normally used between CloudSim and
 	 * CloudResource entity.
 	 */
 	public static final int RESOURCE_DYNAMICS = BASE + 7;
@@ -120,37 +124,37 @@ public class CloudSimTags {
 	public static final int RETURN_ACC_STATISTICS_BY_CATEGORY = BASE + 12;
 
 	/**
-	 * Denotes a request to register a CloudResource entity to a regional CloudInformationService
-	 * (GIS) entity
+	 * Denotes a request to register a CloudResource entity to a regional 
+	 * {@link CloudInformationService} (CIS) entity.
 	 */
 	public static final int REGISTER_REGIONAL_GIS = BASE + 13;
 
 	/**
-	 * Denotes a request to get a list of other regional GIS entities from the system GIS entity
+	 * Denotes a request to get a list of other regional CIS entities from the system CIS entity.
 	 */
 	public static final int REQUEST_REGIONAL_GIS = BASE + 14;
 
 	/**
-	 * Denotes request for grid resource characteristics information. This tag is normally used
+	 * Denotes request for cloud resource characteristics information. This tag is normally used
 	 * between CloudSim and CloudResource entity.
 	 */
 	public static final int RESOURCE_CHARACTERISTICS_REQUEST = BASE + 15;
 
-	/** This tag is used by an entity to send ping requests */
+	/** This tag is used by an entity to send ping requests. */
 	public static final int INFOPKT_SUBMIT = NETBASE + 5;
 
-	/** This tag is used to return the ping request back to sender */
+	/** This tag is used to return the ping request back to sender. */
 	public static final int INFOPKT_RETURN = NETBASE + 6;
 
 	/**
-	 * Denotes the return of a Cloudlet back to sender. This tag is normally used by CloudResource
-	 * entity.
+	 * Denotes the return of a Cloudlet back to sender. 
+         * This tag is normally used by CloudResource entity.
 	 */
 	public static final int CLOUDLET_RETURN = BASE + 20;
 
 	/**
-	 * Denotes the submission of a Cloudlet. This tag is normally used between CloudSim User and
-	 * CloudResource entity.
+	 * Denotes the submission of a Cloudlet. 
+         * This tag is normally used between CloudSim User and CloudResource entity.
 	 */
 	public static final int CLOUDLET_SUBMIT = BASE + 21;
 
@@ -191,65 +195,68 @@ public class CloudSimTags {
 	public static final int CLOUDLET_MOVE_ACK = BASE + 30;
 
 	/**
-	 * Denotes a request to create a new VM in a Datacentre With acknowledgement information sent by
-	 * the Datacentre
+	 * Denotes a request to create a new VM in a {@link Datacenter} with acknowledgement 
+         * information sent by the Datacenter.
 	 */
 	public static final int VM_CREATE = BASE + 31;
 
 	/**
-	 * Denotes a request to create a new VM in a Datacentre With acknowledgement information sent by
-	 * the Datacentre
+	 * Denotes a request to create a new VM in a {@link Datacenter} 
+         * with acknowledgement information sent by the Datacenter.
 	 */
 	public static final int VM_CREATE_ACK = BASE + 32;
 
 	/**
-	 * Denotes a request to destroy a new VM in a Datacentre
+	 * Denotes a request to destroy a new VM in a {@link Datacenter}.
 	 */
 	public static final int VM_DESTROY = BASE + 33;
 
 	/**
-	 * Denotes a request to destroy a new VM in a Datacentre
+	 * Denotes a request to destroy a new VM in a {@link Datacenter} 
+         * with acknowledgement information sent by the Datacener.
 	 */
 	public static final int VM_DESTROY_ACK = BASE + 34;
 
 	/**
-	 * Denotes a request to migrate a new VM in a Datacentre
+	 * Denotes a request to migrate a new VM in a {@link Datacenter}.
 	 */
 	public static final int VM_MIGRATE = BASE + 35;
 
 	/**
-	 * Denotes a request to migrate a new VM in a Datacentre With acknowledgement information sent
-	 * by the Datacentre
+	 * Denotes a request to migrate a new VM in a {@link Datacenter}  
+         * with acknowledgement information sent by the Datacener.
 	 */
 	public static final int VM_MIGRATE_ACK = BASE + 36;
 
 	/**
-	 * Denotes an event to send a file from a user to a datacenter
+	 * Denotes an event to send a file from a user to a {@link Datacenter}.
 	 */
 	public static final int VM_DATA_ADD = BASE + 37;
 
 	/**
-	 * Denotes an event to send a file from a user to a datacenter
+	 * Denotes an event to send a file from a user to a {@link Datacenter}
+         * with acknowledgement information sent by the Datacener.
 	 */
 	public static final int VM_DATA_ADD_ACK = BASE + 38;
 
 	/**
-	 * Denotes an event to remove a file from a datacenter
+	 * Denotes an event to remove a file from a {@link Datacenter} .
 	 */
 	public static final int VM_DATA_DEL = BASE + 39;
 
 	/**
-	 * Denotes an event to remove a file from a datacenter
+	 * Denotes an event to remove a file from a {@link Datacenter}
+         * with acknowledgement information sent by the Datacener.
 	 */
 	public static final int VM_DATA_DEL_ACK = BASE + 40;
 
 	/**
-	 * Denotes an internal event generated in a PowerDatacenter
+	 * Denotes an internal event generated in a {@link Datacenter}.
 	 */
 	public static final int VM_DATACENTER_EVENT = BASE + 41;
 
 	/**
-	 * Denotes an internal event generated in a Broker
+	 * Denotes an internal event generated in a Broker.
 	 */
 	public static final int VM_BROKER_EVENT = BASE + 42;
 
@@ -265,9 +272,9 @@ public class CloudSimTags {
 
 	public static final int NextCycle = BASE + 48;
 
-	/** Private Constructor */
+	/** Private Constructor. */
 	private CloudSimTags() {
-		throw new UnsupportedOperationException("CloudSim Tags cannot be instantiated");
+		throw new UnsupportedOperationException("CloudSimTags cannot be instantiated");
 	}
 
 }

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/DeferredQueue.java

@@ -14,20 +14,20 @@ import java.util.List;
 import java.util.ListIterator;
 
 /**
- * This class implements the deferred event queue used by {@link Simulation}. The event queue uses a
- * linked list to store the events.
+ * This class implements the deferred event queue used by {@link CloudSim}. 
+ * The event queue uses a linked list to store the events.
  * 
  * @author Marcos Dias de Assuncao
  * @since CloudSim Toolkit 1.0
- * @see Simulation
+ * @see CloudSim
  * @see SimEvent
  */
 public class DeferredQueue {
 
-	/** The list. */
+	/** The list of events. */
 	private final List<SimEvent> list = new LinkedList<SimEvent>();
 
-	/** The max time. */
+	/** The max time that an added event is scheduled. */
 	private double maxTime = -1;
 
 	/**

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/FutureQueue.java

@@ -14,24 +14,28 @@ import java.util.SortedSet;
 import java.util.TreeSet;
 
 /**
- * This class implements the future event queue used by {@link Simulation}. The event queue uses a
- * {@link TreeSet} in order to store the events.
+ * This class implements the future event queue used by {@link CloudSim}. 
+ * The event queue uses a {@link TreeSet} in order to store the events.
  * 
  * @author Marcos Dias de Assuncao
  * @since CloudSim Toolkit 1.0
  * @see Simulation
  * @see java.util.TreeSet
+ * 
+ * @todo It would be used a common interface for queues
+ * such as this one and {@link DeferredQueue}
  */
 public class FutureQueue {
 
-	/** The sorted set. */
+	/** The sorted set of events. */
 	private final SortedSet<SimEvent> sortedSet = new TreeSet<SimEvent>();
 
-	/** The serial. */
+	/** A incremental number used for {@link SimEvent#serial} event attribute.
+         */
 	private long serial = 0;
 
 	/**
-	 * Add a new event to the queue. Adding a new event to the queue preserves the temporal order of
+	 * Adds a new event to the queue. Adding a new event to the queue preserves the temporal order of
 	 * the events in the queue.
 	 * 
 	 * @param newEvent The event to be put in the queue.
@@ -42,7 +46,7 @@ public class FutureQueue {
 	}
 
 	/**
-	 * Add a new event to the head of the queue.
+	 * Adds a new event to the head of the queue.
 	 * 
 	 * @param newEvent The event to be put in the queue.
 	 */

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/SimEntity.java

@@ -25,15 +25,19 @@ import org.cloudbus.cloudsim.core.predicates.Predicate;
  * code would be placed.
  * </ul>
  * 
+ * @todo the list above is redundant once all mentioned methods are abstract.
+ * The documentation duplication may lead to have some of them
+ * out-of-date and future confusion.
+ * 
  * @author Marcos Dias de Assuncao
  * @since CloudSim Toolkit 1.0
  */
 public abstract class SimEntity implements Cloneable {
 
-	/** The name. */
+	/** The entity name. */
 	private String name;
 
-	/** The id. */
+	/** The entity id. */
 	private int id;
 
 	/** The buffer for selected incoming events. */
@@ -45,7 +49,7 @@ public abstract class SimEntity implements Cloneable {
 	/**
 	 * Creates a new entity.
 	 * 
-	 * @param name the name to be associated with this entity
+	 * @param name the name to be associated with the entity
 	 */
 	public SimEntity(String name) {
 		if (name.indexOf(" ") != -1) {
@@ -58,7 +62,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Get the name of this entity.
+	 * Gets the name of this entity.
 	 * 
 	 * @return The entity's name
 	 */
@@ -67,7 +71,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Get the unique id number assigned to this entity.
+	 * Gets the unique id number assigned to this entity.
 	 * 
 	 * @return The id number
 	 */
@@ -78,7 +82,7 @@ public abstract class SimEntity implements Cloneable {
 	// The schedule functions
 
 	/**
-	 * Send an event to another entity by id number, with data. Note that the tag <code>9999</code>
+	 * Sends an event to another entity by id number, with data. Note that the tag <code>9999</code>
 	 * is reserved.
 	 * 
 	 * @param dest The unique id number of the destination entity
@@ -94,7 +98,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send an event to another entity by id number and with <b>no</b> data. Note that the tag
+	 * Sends an event to another entity by id number and with <b>no</b> data. Note that the tag
 	 * <code>9999</code> is reserved.
 	 * 
 	 * @param dest The unique id number of the destination entity
@@ -106,7 +110,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send an event to another entity through a port with a given name, with data. Note that the
+	 * Sends an event to another entity through a port with a given name, with data. Note that the
 	 * tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The name of the port to send the event through
@@ -119,7 +123,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send an event to another entity through a port with a given name, with <b>no</b> data. Note
+	 * Sends an event to another entity through a port with a given name, with <b>no</b> data. Note
 	 * that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The name of the port to send the event through
@@ -131,8 +135,8 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send an event to another entity by id number, with data. Note that the tag <code>9999</code>
-	 * is reserved.
+	 * Sends an event to another entity by id number, with data
+         * but no delay. Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The unique id number of the destination entity
 	 * @param tag An user-defined number representing the type of event.
@@ -143,8 +147,8 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send an event to another entity by id number and with <b>no</b> data. Note that the tag
-	 * <code>9999</code> is reserved.
+	 * Sends an event to another entity by id number and with <b>no</b> data
+         * and no delay. Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The unique id number of the destination entity
 	 * @param tag An user-defined number representing the type of event.
@@ -154,8 +158,8 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send an event to another entity through a port with a given name, with data. Note that the
-	 * tag <code>9999</code> is reserved.
+	 * Sends an event to another entity through a port with a given name, with data
+         * but no delay. Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The name of the port to send the event through
 	 * @param tag An user-defined number representing the type of event.
@@ -166,8 +170,9 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send an event to another entity through a port with a given name, with <b>no</b> data. Note
-	 * that the tag <code>9999</code> is reserved.
+	 * Send an event to another entity through a port with a given name, with <b>no</b> data
+         * and no delay. 
+         * Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The name of the port to send the event through
 	 * @param tag An user-defined number representing the type of event.
@@ -177,8 +182,8 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send a high priority event to another entity by id number, with data. Note that the tag
-	 * <code>9999</code> is reserved.
+	 * Sends a high priority event to another entity by id number, with data. 
+         * Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The unique id number of the destination entity
 	 * @param delay How long from the current simulation time the event should be sent
@@ -193,8 +198,8 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send a high priority event to another entity by id number and with <b>no</b> data. Note that
-	 * the tag <code>9999</code> is reserved.
+	 * Sends a high priority event to another entity by id number and with <b>no</b> data. 
+         * Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The unique id number of the destination entity
 	 * @param delay How long from the current simulation time the event should be sent
@@ -205,7 +210,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send a high priority event to another entity through a port with a given name, with data.
+	 * Sends a high priority event to another entity through a port with a given name, with data.
 	 * Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The name of the port to send the event through
@@ -218,7 +223,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send a high priority event to another entity through a port with a given name, with <b>no</b>
+	 * Sends a high priority event to another entity through a port with a given name, with <b>no</b>
 	 * data. Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The name of the port to send the event through
@@ -230,8 +235,9 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send a high priority event to another entity by id number, with data. Note that the tag
-	 * <code>9999</code> is reserved.
+	 * Sends a high priority event to another entity by id number, with data
+         * and no delay. 
+         * Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The unique id number of the destination entity
 	 * @param tag An user-defined number representing the type of event.
@@ -242,8 +248,9 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send a high priority event to another entity by id number and with <b>no</b> data. Note that
-	 * the tag <code>9999</code> is reserved.
+	 * Sends a high priority event to another entity by id number and with <b>no</b> data
+         * and no delay. 
+         * Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The unique id number of the destination entity
 	 * @param tag An user-defined number representing the type of event.
@@ -253,7 +260,8 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send a high priority event to another entity through a port with a given name, with data.
+	 * Sends a high priority event to another entity through a port with a given name, with data
+         * and no delay.
 	 * Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The name of the port to send the event through
@@ -265,8 +273,8 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Send a high priority event to another entity through a port with a given name, with <b>no</b>
-	 * data. Note that the tag <code>9999</code> is reserved.
+	 * Sends a high priority event to another entity through a port with a given name, with <b>no</b>
+	 * data and no delay. Note that the tag <code>9999</code> is reserved.
 	 * 
 	 * @param dest The name of the port to send the event through
 	 * @param tag An user-defined number representing the type of event.
@@ -276,7 +284,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Set the entity to be inactive for a time period.
+	 * Sets the entity to be inactive for a time period.
 	 * 
 	 * @param delay the time period for which the entity will be inactive
 	 */
@@ -291,7 +299,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Count how many events matching a predicate are waiting in the entity's deferred queue.
+	 * Counts how many events matching a predicate are waiting in the entity's deferred queue.
 	 * 
 	 * @param p The event selection predicate
 	 * @return The count of matching events
@@ -301,7 +309,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Count how many events are waiting in the entity's deferred queue.
+	 * Counts how many events are waiting in the entity's deferred queue.
 	 * 
 	 * @return The count of events
 	 */
@@ -310,7 +318,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Extract the first event matching a predicate waiting in the entity's deferred queue.
+	 * Extracts the first event matching a predicate waiting in the entity's deferred queue.
 	 * 
 	 * @param p The event selection predicate
 	 * @return the simulation event
@@ -324,7 +332,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Cancel the first event matching a predicate waiting in the entity's future queue.
+	 * Cancels the first event matching a predicate waiting in the entity's future queue.
 	 * 
 	 * @param p The event selection predicate
 	 * @return The number of events cancelled (0 or 1)
@@ -338,7 +346,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Get the first event matching a predicate from the deferred queue, or if none match, wait for
+	 * Gets the first event matching a predicate from the deferred queue, or if none match, wait for
 	 * a matching event to arrive.
 	 * 
 	 * @param p The predicate to match
@@ -355,7 +363,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Wait for an event matching a specific predicate. This method does not check the entity's
+	 * Waits for an event matching a specific predicate. This method does not check the entity's
 	 * deferred queue.
 	 * 
 	 * @param p The predicate to match
@@ -370,7 +378,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Get the first event waiting in the entity's deferred queue, or if there are none, wait for an
+	 * Gets the first event waiting in the entity's deferred queue, or if there are none, wait for an
 	 * event to arrive.
 	 * 
 	 * @return the simulation event
@@ -380,13 +388,13 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * This method is invoked by the {@link Simulation} class when the simulation is started. This
-	 * method should be responsible for starting the entity up.
+	 * This method is invoked by the {@link CloudSim} class when the simulation is started. 
+	 * It should be responsible for starting the entity up.
 	 */
 	public abstract void startEntity();
 
 	/**
-	 * This method is invoked by the {@link Simulation} class whenever there is an event in the
+	 * This method is invoked by the {@link CloudSim} class whenever there is an event in the
 	 * deferred queue, which needs to be processed by the entity.
 	 * 
 	 * @param ev the event to be processed by the entity
@@ -394,11 +402,18 @@ public abstract class SimEntity implements Cloneable {
 	public abstract void processEvent(SimEvent ev);
 
 	/**
-	 * This method is invoked by the {@link Simulation} before the simulation finishes. If you want
+	 * This method is invoked by the {@link CloudSim} before the simulation finishes. If you want
 	 * to save data in log files this is the method in which the corresponding code would be placed.
 	 */
 	public abstract void shutdownEntity();
 
+        /**
+         * The run loop to process events fired during the simulation.
+         * The events that will be processed are defined
+         * in the {@link #processEvent(org.cloudbus.cloudsim.core.SimEvent)} method.
+         * 
+         * @see #processEvent(org.cloudbus.cloudsim.core.SimEvent) 
+         */
 	public void run() {
 		SimEvent ev = evbuf != null ? evbuf : getNextEvent();
 
@@ -415,13 +430,13 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Get a clone of the entity. This is used when independent replications have been specified as
+	 * Gets a clone of the entity. This is used when independent replications have been specified as
 	 * an output analysis method. Clones or backups of the entities are made in the beginning of the
 	 * simulation in order to reset the entities for each subsequent replication. This method should
 	 * not be called by the user.
 	 * 
 	 * @return A clone of the entity
-	 * @throws CloneNotSupportedException the clone not supported exception
+	 * @throws CloneNotSupportedException when the entity doesn't support cloning
 	 */
 	@Override
 	protected final Object clone() throws CloneNotSupportedException {
@@ -444,7 +459,7 @@ public abstract class SimEntity implements Cloneable {
 	// --------------- PACKAGE LEVEL METHODS ------------------
 
 	/**
-	 * Gets the state.
+	 * Gets the entity state.
 	 * 
 	 * @return the state
 	 */
@@ -462,6 +477,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	// The entity states
+        //@todo The states should be an enum.
 	/** The Constant RUNNABLE. */
 	public static final int RUNNABLE = 0;
 
@@ -475,7 +491,7 @@ public abstract class SimEntity implements Cloneable {
 	public static final int FINISHED = 3;
 
 	/**
-	 * Sets the state.
+	 * Sets the entity state.
 	 * 
 	 * @param state the new state
 	 */
@@ -484,7 +500,7 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Sets the id.
+	 * Sets the entity id.
 	 * 
 	 * @param id the new id
 	 */
@@ -537,7 +553,7 @@ public abstract class SimEntity implements Cloneable {
 		}
 
 		int srcId = getId();
-		if (entityId != srcId) {// does not delay self messages
+		if (entityId != srcId) {// only delay messages between different entities
 			delay += getNetworkDelay(srcId, entityId);
 		}
 
@@ -595,12 +611,9 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Sends an event/message to another entity by <tt>delaying</tt> the simulation time from the
-	 * current time, with a tag representing the event type.
+	 * Sends an event/message to another entity, with a tag representing the event type.
 	 * 
 	 * @param entityId the id number of the destination entity
-	 * @param delay how long from the current simulation time the event should be sent. If delay is
-	 *            a negative number, then it will be changed to 0
 	 * @param cloudSimTag an user-defined number representing the type of an event/message
 	 * @param data A reference to data to be sent with the event
 	 * @pre entityID > 0
@@ -613,12 +626,9 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Sends an event/message to another entity by <tt>delaying</tt> the simulation time from the
-	 * current time, with a tag representing the event type.
+	 * Sends an event/message to another entity, with a tag representing the event type.
 	 * 
 	 * @param entityId the id number of the destination entity
-	 * @param delay how long from the current simulation time the event should be sent. If delay is
-	 *            a negative number, then it will be changed to 0
 	 * @param cloudSimTag an user-defined number representing the type of an event/message
 	 * @pre entityID > 0
 	 * @pre delay >= 0.0
@@ -629,12 +639,9 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Sends an event/message to another entity by <tt>delaying</tt> the simulation time from the
-	 * current time, with a tag representing the event type.
+	 * Sends an event/message to another entity, with a tag representing the event type.
 	 * 
 	 * @param entityName the name of the destination entity
-	 * @param delay how long from the current simulation time the event should be sent. If delay is
-	 *            a negative number, then it will be changed to 0
 	 * @param cloudSimTag an user-defined number representing the type of an event/message
 	 * @param data A reference to data to be sent with the event
 	 * @pre entityName != null
@@ -647,12 +654,9 @@ public abstract class SimEntity implements Cloneable {
 	}
 
 	/**
-	 * Sends an event/message to another entity by <tt>delaying</tt> the simulation time from the
-	 * current time, with a tag representing the event type.
+	 * Sends an event/message to another entity, with a tag representing the event type.
 	 * 
 	 * @param entityName the name of the destination entity
-	 * @param delay how long from the current simulation time the event should be sent. If delay is
-	 *            a negative number, then it will be changed to 0
 	 * @param cloudSimTag an user-defined number representing the type of an event/message
 	 * @pre entityName != null
 	 * @pre delay >= 0.0

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/SimEvent.java

@@ -17,27 +17,40 @@ package org.cloudbus.cloudsim.core;
  */
 public class SimEvent implements Cloneable, Comparable<SimEvent> {
 
-	/** internal event type **/
+	/** Internal event type. **/
 	private final int etype;
 
-	/** time at which event should occur **/
+	/** The time that this event was scheduled, at which it should occur. **/
 	private final double time;
 
-	/** time that the event was removed from the queue for service **/
+	/** Time that the event was removed from the queue to start service. **/
 	private double endWaitingTime;
 
-	/** id of entity who scheduled event **/
+	/** Id of entity who scheduled the event. **/
 	private int entSrc;
 
-	/** id of entity event will be sent to **/
+	/** Id of entity that the event will be sent to. **/
 	private int entDst;
 
-	/** the user defined type of the event **/
+	/** The user defined type of the event. **/
 	private final int tag;
 
-	/** any data the event is carrying **/
+	/** 
+         * Any data the event is carrying. 
+         * @todo I would be used generics to define the type of the event data.
+         * But this modification would incur several changes in the simulator core
+         * that has to be assessed first.
+         **/
 	private final Object data;
 
+        /**
+         * An attribute to help CloudSim to identify the order of received events
+         * when multiple events are generated at the same time.
+         * If two events have the same {@link #time}, to know
+         * what event is greater than other (i.e. that happens after other),
+         * the {@link #compareTo(org.cloudbus.cloudsim.core.SimEvent)}
+         * makes use of this field.
+         */
 	private long serial = -1;
 
 	// Internal event types
@@ -51,7 +64,7 @@ public class SimEvent implements Cloneable, Comparable<SimEvent> {
 	public static final int CREATE = 3;
 
 	/**
-	 * Create a blank event.
+	 * Creates a blank event.
 	 */
 	public SimEvent() {
 		etype = ENULL;
@@ -87,7 +100,7 @@ public class SimEvent implements Cloneable, Comparable<SimEvent> {
 	}
 
 	/**
-	 * Used to set the time at which this event finished waiting in the event
+	 * Sets the time that the event was removed from the queue to start service. 
 	 * 
 	 * @param end_waiting_time
 	 */
@@ -95,6 +108,8 @@ public class SimEvent implements Cloneable, Comparable<SimEvent> {
 		endWaitingTime = end_waiting_time;
 	}
         
+	// ------------------- PUBLIC METHODS --------------------------        
+
 	@Override
 	public String toString() {
 		return "Event tag = " + tag + " source = " + CloudSim.getEntity(entSrc).getName() + " destination = "
@@ -102,7 +117,7 @@ public class SimEvent implements Cloneable, Comparable<SimEvent> {
 	}
 
 	/**
-	 * The internal type
+	 * Gets the internal type
 	 * 
 	 * @return
 	 */
@@ -110,11 +125,7 @@ public class SimEvent implements Cloneable, Comparable<SimEvent> {
 		return etype;
 	}
 
-	// ------------------- PUBLIC METHODS --------------------------
 
-	/**
-	 * @see Comparable#compareTo(Object)
-	 */
 	@Override
 	public int compareTo(SimEvent event) {
 		if (event == null) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/predicates/Predicate.java

@@ -33,6 +33,7 @@ import org.cloudbus.cloudsim.core.SimEvent;
  * @todo It would be an interface, since it doesn't have any attributes, just 
  * abstract methods.
  * @todo There already is a native java {@link java.util.function.Predicate} interface.
+ * Maybe it was introduced with Java 8 (due to Stream and Lambda functions).
  * 
  */
 public abstract class Predicate {