Improved documentation of classes from package org.cloudbus.cloudsim.lists.

Included some @todo's suggesting the assessment of some methods used to find an object inside a List in order to reduce search time. One option is to change some List objects by a HashMap. Other details can be seen at the @todo's inside the source code.

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/distributions/GammaDistr.java

@@ -29,8 +29,8 @@ public class GammaDistr implements ContinuousDistribution {
 	 * Instantiates a new Gamma pseudo random number generator.
 	 * 
 	 * @param seed the seed
-	 * @param alpha the alpha
-	 * @param beta the beta
+	 * @param shape the shape
+	 * @param scale the scale
 	 */
 	public GammaDistr(Random seed, int shape, double scale) {
 		this(shape, scale);
@@ -40,8 +40,8 @@ public class GammaDistr implements ContinuousDistribution {
 	/**
 	 * Instantiates a new Gamma pseudo random number generator.
 	 * 
-	 * @param alpha the alpha
-	 * @param beta the beta
+	 * @param shape the shape
+	 * @param scale the scale
 	 */
 	public GammaDistr(int shape, double scale) {
 		numGen = new GammaDistribution(shape, scale);

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/distributions/LognormalDistr.java

@@ -30,8 +30,8 @@ public class LognormalDistr implements ContinuousDistribution {
 	 * Instantiates a new Log-normal pseudo random number generator.
 	 * 
 	 * @param seed the seed
-	 * @param mean the mean
-	 * @param dev the dev
+	 * @param shape the shape
+	 * @param scale the scale
 	 */
 	public LognormalDistr(Random seed, double shape, double scale) {
 		this(shape, scale);
@@ -41,8 +41,8 @@ public class LognormalDistr implements ContinuousDistribution {
 	/**
 	 * Instantiates a new Log-normal pseudo random number generator.
 	 * 
-	 * @param mean the mean
-	 * @param dev the dev
+	 * @param shape the shape
+	 * @param scale the scale
 	 */
 	public LognormalDistr(double shape, double scale) {
 		numGen = new LogNormalDistribution(scale, shape);

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/lists/CloudletList.java

@@ -23,11 +23,11 @@ import org.cloudbus.cloudsim.Cloudlet;
 public class CloudletList {
 
 	/**
-	 * Gets the by id.
+	 * Gets a {@link Cloudlet} with a given id.
 	 * 
-	 * @param cloudletList the cloudlet list
-	 * @param id the id
-	 * @return the by id
+	 * @param cloudletList the list of existing Cloudlets
+	 * @param id the Cloudlet id
+	 * @return a Cloudlet with the given ID or $null if not found
 	 */
 	public static <T extends Cloudlet> T getById(List<T> cloudletList, int id) {
 		for (T cloudlet : cloudletList) {
@@ -39,10 +39,11 @@ public class CloudletList {
 	}
 
 	/**
-	 * Returns the position of the cloudlet with that id, if it exists. Otherwise -1.
-	 * @param cloudletList - the list of cloudlets.
-	 * @param id - the id we search for.
-	 * @return - the position of the cloudlet with that id, or -1 otherwise.
+	 * Gets the position of a cloudlet with a given id.
+         * 
+	 * @param cloudletList the list of existing cloudlets
+	 * @param id the cloudlet id
+	 * @return the position of the cloudlet with the given id or -1 if not found
 	 */
 	public static <T extends Cloudlet> int getPositionById(List<T> cloudletList, int id) {
 		int i = 0 ;

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/lists/HostList.java

@@ -21,13 +21,12 @@ import org.cloudbus.cloudsim.Host;
 public class HostList {
 
 	/**
-	 * Gets the host (PM) object for a particular ID.
+	 * Gets a {@link Host} with a given id.
 	 * 
 	 * @param <T> the generic type
-	 * @param hostList the host list
+	 * @param hostList the list of existing hosts
 	 * @param id the host ID
-	 * @return the host object or <tt>null</tt> if no host exists
-	 * @see gridsim.Machine
+	 * @return a Host with the given ID or $null if not found
          * 
 	 * @pre id >= 0
 	 * @post $none
@@ -42,11 +41,11 @@ public class HostList {
 	}
 
 	/**
-	 * Gets the total number of PEs for all PMs.
+	 * Gets the total number of PEs for all Hosts.
 	 * 
 	 * @param <T> the generic type
-	 * @param hostList the host list
-	 * @return number of PEs
+	 * @param hostList the list of existing hosts
+	 * @return total number of PEs for all PMs
 	 * @pre $none
 	 * @post $result >= 0
 	 */
@@ -59,11 +58,11 @@ public class HostList {
 	}
 
 	/**
-	 * Gets the total number of <tt>FREE</tt> or non-busy PEs for all PMs.
+	 * Gets the total number of <tt>FREE</tt> (non-busy) PEs for all Hosts.
 	 * 
 	 * @param <T> the generic type
-	 * @param hostList the host list
-	 * @return number of PEs
+	 * @param hostList the list of existing hosts
+	 * @return total number of free PEs
 	 * @pre $none
 	 * @post $result >= 0
 	 */
@@ -76,11 +75,11 @@ public class HostList {
 	}
 
 	/**
-	 * Gets the total number of <tt>BUSY</tt> PEs for all PMs.
+	 * Gets the total number of <tt>BUSY</tt> PEs for all Hosts.
 	 * 
 	 * @param <T> the generic type
-	 * @param hostList the host list
-	 * @return number of PEs
+	 * @param hostList the list of existing hosts
+	 * @return total number of busy PEs
 	 * @pre $none
 	 * @post $result >= 0
 	 */
@@ -93,11 +92,11 @@ public class HostList {
 	}
 
 	/**
-	 * Gets the first host with free Pe's.
+	 * Gets the first host with free PEs.
 	 * 
 	 * @param <T> the generic type
-	 * @param hostList the host list
-	 * @return a machine object or <tt>null</tt> if not found
+	 * @param hostList the list of existing hosts
+	 * @return a Host object or <tt>null</tt> if not found
 	 * @pre $none
 	 * @post $none
 	 */
@@ -106,12 +105,12 @@ public class HostList {
 	}
 
 	/**
-	 * Gets the first PM with a specified number of free Pe's.
+	 * Gets the first Host with a specified number of free PEs.
 	 * 
 	 * @param <T> the generic type
-	 * @param hostList the host list
+	 * @param hostList the list of existing hosts
 	 * @param pesNumber the pes number
-	 * @return a machine object or <tt>null</tt> if not found
+	 * @return a Host object or <tt>null</tt> if not found
 	 * @pre $none
 	 * @post $none
 	 */
@@ -125,17 +124,17 @@ public class HostList {
 	}
 
 	/**
-	 * Sets the particular Pe status on a PM.
+	 * Sets the status of a particular PE on a given Host.
 	 * 
 	 * @param <T> the generic type
-	 * @param hostList the host list
-	 * @param status Pe status, either <tt>Pe.FREE</tt> or <tt>Pe.BUSY</tt>
+	 * @param hostList the list of existing hosts
+	 * @param status the PE status, either <tt>Pe.FREE</tt> or <tt>Pe.BUSY</tt>
 	 * @param hostId the host id
-	 * @param peId the pe id
-	 * @return <tt>true</tt> if the Pe status has changed, <tt>false</tt> otherwise (host id or
-	 *         Pe id might not be exist)
-	 * @pre machineID >= 0
-	 * @pre peID >= 0
+	 * @param peId the id of the PE to set the status
+	 * @return <tt>true</tt> if the PE status has changed, <tt>false</tt> otherwise (host id or
+	 *         PE id might not be exist)
+	 * @pre hostId >= 0
+	 * @pre peId >= 0
 	 * @post $none
 	 */
 	public static <T extends Host> boolean setPeStatus(List<T> hostList, int status, int hostId, int peId) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/lists/PeList.java

@@ -23,11 +23,11 @@ import org.cloudbus.cloudsim.Vm;
 public class PeList {
 
 	/**
-	 * Gets a Pe by its id.
+	 * Gets a {@link Pe} with a given id.
 	 * 
 	 * @param peList the PE list where to get a given PE
 	 * @param id the id of the PE to be get
-	 * @return the PE if the given id or null if not found
+	 * @return the PE with the given id or null if not found
 	 * @pre id >= 0
 	 * @post $none
 	 */
@@ -45,7 +45,7 @@ public class PeList {
 	}
 
 	/**
-	 * Gets MIPS Rating of a PE with a specified ID.
+	 * Gets MIPS Rating of a PE with a given ID.
 	 * 
 	 * @param peList the PE list where to get a given PE
 	 * @param id the id of the PE to be get
@@ -78,10 +78,10 @@ public class PeList {
 	}
 
 	/**
-	 * Gets the max utilization percentage among by all PEs.
+	 * Gets the max utilization percentage among all PEs.
 	 * 
 	 * @param peList the pe list
-	 * @return the utilization percentage
+	 * @return the max utilization percentage
 	 */
 	public static <T extends Pe> double getMaxUtilization(List<T> peList) {
 		double maxUtilization = 0;
@@ -95,11 +95,11 @@ public class PeList {
 	}
 
 	/**
-	 * Gets the max utilization percentage among by all PEs allocated to a VM.
+	 * Gets the max utilization percentage among all PEs allocated to a VM.
 	 * 
 	 * @param vm the vm to get the maximum utilization percentage
 	 * @param peList the pe list
-	 * @return the utilization percentage
+	 * @return the max utilization percentage
 	 */
 	public static <T extends Pe> double getMaxUtilizationAmongVmsPes(List<T> peList, Vm vm) {
 		double maxUtilization = 0;
@@ -116,10 +116,10 @@ public class PeList {
 	}
 
 	/**
-	 * Gets the first PE which is FREE.
+	 * Gets the first <tt>FREE</tt> PE which.
 	 * 
 	 * @param peList the PE list
-	 * @return the first free PE, otherwise returns null
+	 * @return the first free PE or null if not found
 	 * @pre $none
 	 * @post $none
 	 */
@@ -133,7 +133,7 @@ public class PeList {
 	}
 
 	/**
-	 * Gets the number of <tt>FREE</tt> or non-busy PEs.
+	 * Gets the number of <tt>FREE</tt> (non-busy) PEs.
 	 * 
 	 * @param peList the PE list
 	 * @return number of free PEs
@@ -153,7 +153,7 @@ public class PeList {
 	/**
 	 * Sets a PE status.
 	 * 
-	 * @param status PE status, either <tt>Pe.FREE</tt> or <tt>Pe.BUSY</tt>
+	 * @param status the PE status, either <tt>Pe.FREE</tt> or <tt>Pe.BUSY</tt>
 	 * @param id the id of the PE to be set
 	 * @param peList the PE list
 	 * @return <tt>true</tt> if the PE status has been changed, <tt>false</tt> otherwise (PE id might
@@ -190,14 +190,15 @@ public class PeList {
 
 	/**
 	 * Sets the status of PEs of a host to FAILED or FREE. NOTE: <tt>resName</tt> and
-	 * <tt>machineID</tt> are used for debugging purposes, which is <b>ON</b> by default. 
+	 * <tt>hostId</tt> are used for debugging purposes, which is <b>ON</b> by default. 
          * Use {@link #setStatusFailed(boolean)} if you do not want this information.
 	 * 
          * @param peList the host's PE list to be set as failed or free
 	 * @param resName the name of the resource
-	 * @param hostId the id of this host
+	 * @param hostId the id of the host
 	 * @param failed true if the host's PEs have to be set as FAILED, false
          * if they have to be set as FREE.
+         * @see #setStatusFailed(java.util.List, boolean) 
 	 */
 	public static <T extends Pe> void setStatusFailed(
 			List<T> peList,

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/lists/ResCloudletList.java

@@ -21,18 +21,20 @@ import org.cloudbus.cloudsim.ResCloudlet;
 public class ResCloudletList {
 
 	/**
-	 * Returns a given Cloudlet. This method needs a combination of Cloudlet Id and User Id because
-	 * each Cloud Users might have exactly same Cloudlet Ids.
+	 * Gets a {@link ResCloudlet} with a given id and owned by a given user.
+         * This method needs a combination of Cloudlet Id and User Id because
+	 * each Cloud User might have exactly the same Cloudlet Id.
 	 * 
 	 * @param cloudletId a Cloudlet Id
 	 * @param userId an User Id
-	 * @param list the list
-	 * @return the Cloudlet.
-	 * @throws IndexOutOfBoundsException - if a Cloudlet with specified Id and user id is not in the
-	 *             list.
+	 * @param list the list of ResCloudlet
+	 * @return a Cloudlet or null if not found
+
          * @pre cloudletId >= 0
 	 * @pre userId >= 0
 	 * @post $none
+         * 
+         * @todo The second phrase of the class documentation is not clear. 
 	 */
 	public static <T extends ResCloudlet> ResCloudlet getByIdAndUserId(
 			List<T> list,
@@ -47,14 +49,15 @@ public class ResCloudletList {
 	}
 
 	/**
-	 * Finds the index of a Cloudlet inside the list. This method needs a combination of Cloudlet Id
+	 * Finds the index of a ResCloudlet inside a list. 
+         * This method needs a combination of Cloudlet Id
 	 * and User Id because each Cloud User might have exactly the same Cloudlet Id.
 	 * 
 	 * @param cloudletId a Cloudlet Id
 	 * @param userId an User Id
-	 * @param list the list
+	 * @param list the list of ResCloudlets
 	 * @return the index in this list of the first occurrence of the specified Cloudlet, or
-	 *         <code>-1</code> if the list does not contain this Cloudlet.
+	 *         <code>-1</code> if the list does not contain the Cloudlet.
 	 * @pre cloudletId >= 0
 	 * @pre userId >= 0
 	 * @post $none
@@ -71,12 +74,12 @@ public class ResCloudletList {
 	}
 
 	/**
-	 * Move a ResCloudlet object from this linked-list into a specified one.
+	 * Moves a ResCloudlet object from a list to another.
 	 * 
-	 * @param listFrom the list from
-	 * @param listTo the list to
-	 * @param cloudlet the cloudlet
-	 * @return <b>true</b> if the moving operation successful, otherwise return <b>false</b>
+	 * @param listFrom the source list
+	 * @param listTo the destination list
+	 * @param cloudlet the cloudlet to be moved from the source to the destination list
+	 * @return <b>true</b> if the moving operation successful, <b>false</b> otherwise
 	 * @pre obj != null
 	 * @pre list != null
 	 * @post $result == true || $result == false
@@ -90,10 +93,11 @@ public class ResCloudletList {
 	}
 
 	/**
-	 * Returns the position of the cloudlet with that id, if it exists. Otherwise -1.
-	 * @param cloudletList - the list of cloudlets.
-	 * @param id - the id we search for.
-	 * @return - the position of the cloudlet with that id, or -1 otherwise.
+	 * Gets the position of a ResCloudlet with a given id.
+         * 
+	 * @param cloudletList the list of cloudlets.
+	 * @param id the cloudlet id
+	 * @return the position of the cloudlet with that id, or -1 if not found.
 	 */
 	public static <T extends ResCloudlet> int getPositionById(List<T> cloudletList, int id) {
 		int i = 0 ;

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/lists/VmList.java

@@ -21,13 +21,30 @@ import org.cloudbus.cloudsim.Vm;
 public class VmList {
 
 	/**
-	 * Return a reference to a Vm object from its ID.
+	 * Gets a {@link Vm} with a given id.
 	 * 
 	 * @param id ID of required VM
-	 * @param vmList the vm list
-	 * @return Vm with the given ID, $null if not found
+	 * @param vmList list of existing VMs
+	 * @return a Vm with the given ID or $null if not found
 	 * @pre $none
 	 * @post $none
+         * 
+         * @todo It may be considered the use of a HashMap in order to improve 
+         * VM search, instead of a List. The map key can be the vm id
+         * and the value the VM itself. However, it has to be assessed
+         * the feasibility to have VMs with the same ID and the need
+         * to find VMs by its id and user id, as in the method
+         * {@link #getByIdAndUserId(java.util.List, int, int)}.
+         * The first concern could be dealt by ensuring that all
+         * VMs have different ID (in fact, I don't know if 
+         * VM id uniqueness is a CloudSim requirement)
+         * and creating a map by VM id.
+         * The second concern could be dealt by creating 
+         * a HashMap<UserID, List<VmIDs>>.
+         * The third concern is, that changing 
+         * the class of these lists may have a potential
+         * effect on the entire project and in the creation of simulations
+         * that has to be priorly assessed.
 	 */
 	public static <T extends Vm> T getById(List<T> vmList, int id) {
 		for (T vm : vmList) {
@@ -39,11 +56,11 @@ public class VmList {
 	}
 
 	/**
-	 * Return a reference to a Vm object from its ID and user ID.
+	 * Gets a {@link Vm} with a given id and owned by a given user.
 	 * 
+	 * @param vmList list of existing VMs
 	 * @param id ID of required VM
-	 * @param userId the user ID
-	 * @param vmList the vm list
+	 * @param userId the user ID of the VM's owner
 	 * @return Vm with the given ID, $null if not found
 	 * @pre $none
 	 * @post $none