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

Some things aren't completely clear, such as how the provisioners classes should be used.
For instance, it wasn't explicit just from a provisioner itself that each PM hast to use its own instance of the provisioners such as ram and bw provisioner, and that it physical PE has to have its own instance of a PE provisioner.
The documentation was improved to make clear these assumptions.

Some @todo were added in order to make some improvements in the code clarity further.
For instance, some attribute names are confusing, such as "ram". It is not clear if it represents the capacity, allocated ram or anything else. However, the documentation of the attributes was accordingly updated to avoid these confusions.

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

@@ -11,8 +11,8 @@ package org.cloudbus.cloudsim;
 import org.cloudbus.cloudsim.provisioners.PeProvisioner;
 
 /**
- * Pe (Processing Element) class represents a CPU core, defined in terms of Millions
- * Instructions Per Second (MIPS) rating.<br>
+ * Pe (Processing Element) class represents a CPU core of a physical machine (PM), 
+ * defined in terms of Millions Instructions Per Second (MIPS) rating.<br/>
  * <b>ASSUMPTION:<b> All PEs under the same Machine have the same MIPS rating.
  * @todo This assumption is not being assured on different class (where other TODOs where introduced)
  * @todo Pe statuses have to be defined using an enum

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/provisioners/BwProvisioner.java

@@ -11,8 +11,10 @@ package org.cloudbus.cloudsim.provisioners;
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * BwProvisioner is an abstract class that represents the provisioning policy of bandwidth to
- * virtual machines inside a Host. When extending this class, care must be taken to guarantee that
+ * BwProvisioner is an abstract class that represents the provisioning policy used by a host
+ * to allocate bandwidth (bw) to virtual machines inside it. 
+ * Each host has to have its own instance of a BwProvisioner.
+ * When extending this class, care must be taken to guarantee that
  * the field availableBw will always contain the amount of free bandwidth available for future
  * allocations.
  * 
@@ -22,16 +24,16 @@ import org.cloudbus.cloudsim.Vm;
  */
 public abstract class BwProvisioner {
 
-	/** The bw. */
+	/** The total bandwidth capacity from the host that the provisioner can allocate to VMs. */
 	private long bw;
 
-	/** The available bw. */
+	/** The available bandwidth. */
 	private long availableBw;
 
 	/**
 	 * Creates the new BwProvisioner.
 	 * 
-	 * @param bw overall amount of bandwidth available in the host.
+	 * @param bw The total bandwidth capacity from the host that the provisioner can allocate to VMs.
 	 * 
 	 * @pre bw >= 0
 	 * @post $none
@@ -44,8 +46,8 @@ public abstract class BwProvisioner {
 	/**
 	 * Allocates BW for a given VM.
 	 * 
-	 * @param vm virtual machine for which the bw are being allocated
-	 * @param bw the bw
+	 * @param vm the virtual machine for which the bw are being allocated
+	 * @param bw the bw to be allocated to the VM
 	 * 
 	 * @return $true if the bw could be allocated; $false otherwise
 	 * 
@@ -74,7 +76,7 @@ public abstract class BwProvisioner {
 	public abstract void deallocateBwForVm(Vm vm);
 
 	/**
-	 * Releases BW used by a all VMs.
+	 * Releases BW used by all VMs.
 	 * 
 	 * @pre $none
 	 * @post none
@@ -84,28 +86,30 @@ public abstract class BwProvisioner {
 	}
 
 	/**
-	 * Checks if BW is suitable for vm.
+	 * Checks if it is possible to change the current allocated BW for the VM
+         * to a new amount, depending on the available BW.
 	 * 
-	 * @param vm the vm
-	 * @param bw the bw
+	 * @param vm the vm to check if there is enough available BW on the host to 
+         * change the VM allocated BW
+	 * @param bw the new total amount of BW for the VM.
 	 * 
-	 * @return true, if BW is suitable for vm
+	 * @return true, if is suitable for vm
 	 */
 	public abstract boolean isSuitableForVm(Vm vm, long bw);
 
 	/**
-	 * Gets the bw.
+	 * Gets the bw capacity.
 	 * 
-	 * @return the bw
+	 * @return the bw capacity
 	 */
 	public long getBw() {
 		return bw;
 	}
 
 	/**
-	 * Sets the bw.
+	 * Sets the bw capacity.
 	 * 
-	 * @param bw the new bw
+	 * @param bw the new bw capacity
 	 */
 	protected void setBw(long bw) {
 		this.bw = bw;

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/provisioners/BwProvisionerSimple.java

@@ -14,8 +14,10 @@ import java.util.Map;
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * BwProvisionerSimple is a class that implements a simple best effort allocation policy: if there
- * is bw available to request, it allocates; otherwise, it fails.
+ * BwProvisionerSimple is an extension of {@link BwProvisioner} which uses a best-effort policy to
+ * allocate bandwidth (bw) to VMs: 
+ * if there is available bw on the host, it allocates; otherwise, it fails. 
+ * Each host has to have its own instance of a RamProvisioner.
  * 
  * @author Rodrigo N. Calheiros
  * @author Anton Beloglazov
@@ -23,23 +25,20 @@ import org.cloudbus.cloudsim.Vm;
  */
 public class BwProvisionerSimple extends BwProvisioner {
 
-	/** The bw table. */
+	/** The BW map, where each key is a VM id and each value
+         * is the amount of BW allocated to that VM. */
 	private Map<String, Long> bwTable;
 
 	/**
 	 * Instantiates a new bw provisioner simple.
 	 * 
-	 * @param bw the bw
+	 * @param bw The total bw capacity from the host that the provisioner can allocate to VMs. 
 	 */
 	public BwProvisionerSimple(long bw) {
 		super(bw);
 		setBwTable(new HashMap<String, Long>());
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.BwProvisioner#allocateBwForVm(cloudsim.Vm, long)
-	 */
 	@Override
 	public boolean allocateBwForVm(Vm vm, long bw) {
 		deallocateBwForVm(vm);
@@ -55,10 +54,6 @@ public class BwProvisionerSimple extends BwProvisioner {
 		return false;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.BwProvisioner#getAllocatedBwForVm(cloudsim.Vm)
-	 */
 	@Override
 	public long getAllocatedBwForVm(Vm vm) {
 		if (getBwTable().containsKey(vm.getUid())) {
@@ -67,10 +62,6 @@ public class BwProvisionerSimple extends BwProvisioner {
 		return 0;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.BwProvisioner#deallocateBwForVm(cloudsim.Vm)
-	 */
 	@Override
 	public void deallocateBwForVm(Vm vm) {
 		if (getBwTable().containsKey(vm.getUid())) {
@@ -80,22 +71,12 @@ public class BwProvisionerSimple extends BwProvisioner {
 		}
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.BwProvisioner#deallocateBwForVm(cloudsim.Vm)
-	 */
 	@Override
 	public void deallocateBwForAllVms() {
 		super.deallocateBwForAllVms();
 		getBwTable().clear();
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see
-	 * gridsim.virtualization.power.provisioners.BWProvisioner#isSuitableForVm(gridsim.virtualization
-	 * .power.VM, long)
-	 */
 	@Override
 	public boolean isSuitableForVm(Vm vm, long bw) {
 		long allocatedBw = getAllocatedBwForVm(vm);
@@ -108,18 +89,18 @@ public class BwProvisionerSimple extends BwProvisioner {
 	}
 
 	/**
-	 * Gets the bw table.
+	 * Gets the map between VMs and allocated bw.
 	 * 
-	 * @return the bw table
+	 * @return the bw map
 	 */
 	protected Map<String, Long> getBwTable() {
 		return bwTable;
 	}
 
 	/**
-	 * Sets the bw table.
+	 * Sets the map between VMs and allocated bw.
 	 * 
-	 * @param bwTable the bw table
+	 * @param bwTable the bw map
 	 */
 	protected void setBwTable(Map<String, Long> bwTable) {
 		this.bwTable = bwTable;

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/provisioners/PeProvisioner.java

@@ -9,27 +9,35 @@
 package org.cloudbus.cloudsim.provisioners;
 
 import java.util.List;
+import org.cloudbus.cloudsim.DatacenterCharacteristics;
 
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * The Class PeProvisioner.
+/**
+ * PeProvisioner is an abstract class that represents the provisioning policy used by a host
+ * to allocate its PEs to virtual machines inside it. It gets a physical PE
+ * and manage it in order to provide this PE as virtual PEs for VMs.
+ * In that way, a given PE might be shared among different VMs.
+ * Each host's PE has to have its own instance of a PeProvisioner.
+ * When extending this class, care must be taken to guarantee that the field
+ * availableMips will always contain the amount of free mips available for future allocations.
  * 
  * @author Anton Beloglazov
  * @since CloudSim Toolkit 2.0
  */
 public abstract class PeProvisioner {
 
-	/** The mips. */
+	/** The total mips capacity of the PE that the provisioner can allocate to VMs. */
 	private double mips;
 
 	/** The available mips. */
 	private double availableMips;
 
 	/**
-	 * Creates the new PeProvisioner.
+	 * Creates a new PeProvisioner.
 	 * 
-	 * @param mips overall amount of MIPS available in the Pe
+	 * @param mips The total mips capacity of the PE that the provisioner can allocate to VMs
 	 * 
 	 * @pre mips>=0
 	 * @post $none
@@ -40,12 +48,14 @@ public abstract class PeProvisioner {
 	}
 
 	/**
-	 * Allocates MIPS for a given VM.
+	 * Allocates a new virtual PE with a specific capacity for a given VM.
+         * The virtual PE to be added will use the total or partial mips capacity
+         * of the physical PE.
 	 * 
-	 * @param vm virtual machine for which the MIPS are being allocated
-	 * @param mips the mips
+	 * @param vm the virtual machine for which the new virtual PE is being allocated
+	 * @param mips the mips to be allocated to the virtual PE of the given VM
 	 * 
-	 * @return $true if the MIPS could be allocated; $false otherwise
+	 * @return $true if the virtual PE could be allocated; $false otherwise
 	 * 
 	 * @pre $none
 	 * @post $none
@@ -53,37 +63,44 @@ public abstract class PeProvisioner {
 	public abstract boolean allocateMipsForVm(Vm vm, double mips);
 
 	/**
-	 * Allocates MIPS for a given VM.
+	 * Allocates a new virtual PE with a specific capacity for a given VM.
 	 * 
-	 * @param vmUid the vm uid
-	 * @param mips the mips
+	 * @param vmUid the virtual machine for which the new virtual PE is being allocated
+	 * @param mips the mips to be allocated to the virtual PE of the given VM
 	 * 
-	 * @return $true if the MIPS could be allocated; $false otherwise
+	 * @return $true if the virtual PE could be allocated; $false otherwise
 	 * 
 	 * @pre $none
 	 * @post $none
+         * @see #allocateMipsForVm(org.cloudbus.cloudsim.Vm, double) 
 	 */
 	public abstract boolean allocateMipsForVm(String vmUid, double mips);
 
 	/**
-	 * Allocates MIPS for a given VM.
+	 * Allocates a new set of virtual PEs with a specific capacity for a given VM.
+         * The virtual PE to be added will use the total or partial mips capacity
+         * of the physical PE.
 	 * 
-	 * @param vm virtual machine for which the MIPS are being allocated
-	 * @param mips the mips for each virtual Pe
+	 * @param vm the virtual machine for which the new virtual PE is being allocated
+	 * @param mips the list of mips capacity of each virtual PE to be allocated to the VM
 	 * 
-	 * @return $true if the MIPS could be allocated; $false otherwise
+	 * @return $true if the set of virtual PEs could be allocated; $false otherwise
 	 * 
 	 * @pre $none
 	 * @post $none
+         * @todo In this case, each PE can have a different capacity, what 
+         * in many places this situation is not considered, such as 
+         * in the {@link Vm}, {@link Pe} and {@link DatacenterCharacteristics}
+         * classes.
 	 */
 	public abstract boolean allocateMipsForVm(Vm vm, List<Double> mips);
 
 	/**
-	 * Gets allocated MIPS for a given VM.
+	 * Gets the list of allocated virtual PEs' MIPS for a given VM.
 	 * 
-	 * @param vm virtual machine for which the MIPS are being allocated
+	 * @param vm the virtual machine the get the list of allocated virtual PEs' MIPS
 	 * 
-	 * @return array of allocated MIPS
+	 * @return list of allocated virtual PEs' MIPS
 	 * 
 	 * @pre $none
 	 * @post $none
@@ -93,7 +110,7 @@ public abstract class PeProvisioner {
 	/**
 	 * Gets total allocated MIPS for a given VM for all PEs.
 	 * 
-	 * @param vm virtual machine for which the MIPS are being allocated
+	 * @param vm the virtual machine the get the total allocated MIPS capacity
 	 * 
 	 * @return total allocated MIPS
 	 * 
@@ -103,12 +120,12 @@ public abstract class PeProvisioner {
 	public abstract double getTotalAllocatedMipsForVm(Vm vm);
 
 	/**
-	 * Gets allocated MIPS for a given VM for a given virtual Pe.
+	 * Gets the MIPS capacity of a virtual Pe allocated to a given VM.
 	 * 
-	 * @param vm virtual machine for which the MIPS are being allocated
-	 * @param peId the pe id
+	 * @param vm virtual machine to get a given virtual PE capacity
+	 * @param peId the virtual pe id
 	 * 
-	 * @return allocated MIPS
+	 * @return allocated MIPS for the virtual PE
 	 * 
 	 * @pre $none
 	 * @post $none
@@ -116,7 +133,7 @@ public abstract class PeProvisioner {
 	public abstract double getAllocatedMipsForVmByVirtualPeId(Vm vm, int peId);
 
 	/**
-	 * Releases MIPS used by a VM.
+	 * Releases all virtual PEs allocated to a given VM.
 	 * 
 	 * @param vm the vm
 	 * 
@@ -126,7 +143,7 @@ public abstract class PeProvisioner {
 	public abstract void deallocateMipsForVm(Vm vm);
 
 	/**
-	 * Releases MIPS used by all VMs.
+	 * Releases all virtual PEs allocated to all VMs.
 	 * 
 	 * @pre $none
 	 * @post none
@@ -166,7 +183,7 @@ public abstract class PeProvisioner {
 	}
 
 	/**
-	 * Sets the available MIPS.
+	 * Sets the available MIPS in the PE.
 	 * 
 	 * @param availableMips the availableMips to set
 	 */

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/provisioners/PeProvisionerSimple.java

@@ -16,20 +16,25 @@ import java.util.Map;
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * The Class PeProvisionerSimple.
+ * PeProvisionerSimple is an extension of {@link PeProvisioner} which uses a best-effort policy to
+ * allocate virtual PEs to VMs: 
+ * if there is available mips on the physical PE, it allocates to a virtual PE; otherwise, it fails. 
+ * Each host's PE has to have its own instance of a PeProvisioner.
  * 
  * @author Anton Beloglazov
  * @since CloudSim Toolkit 2.0
  */
 public class PeProvisionerSimple extends PeProvisioner {
 
-	/** The pe table. */
+	/** The PE map, where each key is a VM id and each value
+         * is the list of PEs (in terms of their amount of MIPS) 
+         * allocated to that VM. */
 	private Map<String, List<Double>> peTable;
 
 	/**
-	 * Creates the PeProvisionerSimple object.
+	 * Instantiates a new pe provisioner simple.
 	 * 
-	 * @param availableMips the available mips
+	 * @param availableMips The total mips capacity of the PE that the provisioner can allocate to VMs. 
 	 * 
 	 * @pre $none
 	 * @post $none
@@ -39,19 +44,11 @@ public class PeProvisionerSimple extends PeProvisioner {
 		setPeTable(new HashMap<String, ArrayList<Double>>());
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.PeProvisioner#allocateMipsForVM(cloudsim.power.VM, int)
-	 */
 	@Override
 	public boolean allocateMipsForVm(Vm vm, double mips) {
 		return allocateMipsForVm(vm.getUid(), mips);
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.PeProvisioner#allocateMipsForVm(java.lang.String, double)
-	 */
 	@Override
 	public boolean allocateMipsForVm(String vmUid, double mips) {
 		if (getAvailableMips() < mips) {
@@ -74,11 +71,6 @@ public class PeProvisionerSimple extends PeProvisioner {
 		return true;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.PeProvisioner#allocateMipsForVM(cloudsim.power.VM,
-	 * java.util.ArrayList)
-	 */
 	@Override
 	public boolean allocateMipsForVm(Vm vm, List<Double> mips) {
 		int totalMipsToAllocate = 0;
@@ -97,22 +89,12 @@ public class PeProvisionerSimple extends PeProvisioner {
 		return true;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.PeProvisioner#deallocateMipsForAllVms()
-	 */
 	@Override
 	public void deallocateMipsForAllVms() {
 		super.deallocateMipsForAllVms();
 		getPeTable().clear();
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see
-	 * cloudsim.provisioners.PeProvisioner#getAllocatedMipsForVMByVirtualPeId(cloudsim.power.VM,
-	 * int)
-	 */
 	@Override
 	public double getAllocatedMipsForVmByVirtualPeId(Vm vm, int peId) {
 		if (getPeTable().containsKey(vm.getUid())) {
@@ -124,10 +106,6 @@ public class PeProvisionerSimple extends PeProvisioner {
 		return 0;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.PeProvisioner#getAllocatedMipsForVM(cloudsim.power.VM)
-	 */
 	@Override
 	public List<Double> getAllocatedMipsForVm(Vm vm) {
 		if (getPeTable().containsKey(vm.getUid())) {
@@ -136,10 +114,6 @@ public class PeProvisionerSimple extends PeProvisioner {
 		return null;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.PeProvisioner#getTotalAllocatedMipsForVM(cloudsim.power.VM)
-	 */
 	@Override
 	public double getTotalAllocatedMipsForVm(Vm vm) {
 		if (getPeTable().containsKey(vm.getUid())) {
@@ -152,10 +126,6 @@ public class PeProvisionerSimple extends PeProvisioner {
 		return 0;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.PeProvisioner#deallocateMipsForVM(cloudsim.power.VM)
-	 */
 	@Override
 	public void deallocateMipsForVm(Vm vm) {
 		if (getPeTable().containsKey(vm.getUid())) {
@@ -167,16 +137,16 @@ public class PeProvisionerSimple extends PeProvisioner {
 	}
 
 	/**
-	 * Gets the pe table.
+	 * Gets the pe map.
 	 * 
-	 * @return the peTable
+	 * @return the pe map
 	 */
 	protected Map<String, List<Double>> getPeTable() {
 		return peTable;
 	}
 
 	/**
-	 * Sets the pe table.
+	 * Sets the pe map.
 	 * 
 	 * @param peTable the peTable to set
 	 */

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/provisioners/RamProvisioner.java

@@ -11,8 +11,10 @@ package org.cloudbus.cloudsim.provisioners;
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * RamProvisioner is an abstract class that represents the provisioning policy of memory to virtual
- * machines inside a Host. When extending this class, care must be taken to guarantee that the field
+ * RamProvisioner is an abstract class that represents the provisioning policy used by a host
+ * to allocate memory to virtual machines inside it. 
+ * Each host has to have its own instance of a RamProvisioner.
+ * When extending this class, care must be taken to guarantee that the field
  * availableMemory will always contain the amount of free memory available for future allocations.
  * 
  * @author Rodrigo N. Calheiros
@@ -21,7 +23,7 @@ import org.cloudbus.cloudsim.Vm;
  */
 public abstract class RamProvisioner {
 
-	/** The ram. */
+	/** The total ram capacity from the host that the provisioner can allocate to VMs. */
 	private int ram;
 
 	/** The available ram. */
@@ -30,7 +32,7 @@ public abstract class RamProvisioner {
 	/**
 	 * Creates the new RamProvisioner.
 	 * 
-	 * @param ram the ram
+	 * @param ram The total ram capacity from the host that the provisioner can allocate to VMs.
 	 * 
 	 * @pre ram>=0
 	 * @post $none
@@ -43,8 +45,8 @@ public abstract class RamProvisioner {
 	/**
 	 * Allocates RAM for a given VM.
 	 * 
-	 * @param vm virtual machine for which the RAM are being allocated
-	 * @param ram the RAM
+	 * @param vm the virtual machine for which the RAM is being allocated
+	 * @param ram the RAM to be allocated to the VM
 	 * 
 	 * @return $true if the RAM could be allocated; $false otherwise
 	 * 
@@ -54,16 +56,16 @@ public abstract class RamProvisioner {
 	public abstract boolean allocateRamForVm(Vm vm, int ram);
 
 	/**
-	 * Gets the allocated RAM for VM.
+	 * Gets the allocated RAM for a given VM.
 	 * 
 	 * @param vm the VM
 	 * 
-	 * @return the allocated RAM for vm
+	 * @return the allocated RAM for the vm
 	 */
 	public abstract int getAllocatedRamForVm(Vm vm);
 
 	/**
-	 * Releases BW used by a VM.
+	 * Releases RAM used by a VM.
 	 * 
 	 * @param vm the vm
 	 * 
@@ -73,7 +75,7 @@ public abstract class RamProvisioner {
 	public abstract void deallocateRamForVm(Vm vm);
 
 	/**
-	 * Releases BW used by a all VMs.
+	 * Releases RAM used by all VMs.
 	 * 
 	 * @pre $none
 	 * @post none
@@ -83,17 +85,19 @@ public abstract class RamProvisioner {
 	}
 
 	/**
-	 * Checks if is suitable for vm.
+	 * Checks if it is possible to change the current allocated RAM for the VM
+         * to a new amount, depending on the available RAM.
 	 * 
-	 * @param vm the vm
-	 * @param ram the ram
+	 * @param vm the vm to check if there is enough available RAM on the host to 
+         * change the VM allocated RAM
+	 * @param ram the new total amount of RAM for the VM.
 	 * 
 	 * @return true, if is suitable for vm
 	 */
 	public abstract boolean isSuitableForVm(Vm vm, int ram);
 
 	/**
-	 * Gets the ram.
+	 * Gets the ram capacity.
 	 * 
 	 * @return the ram
 	 */
@@ -102,7 +106,7 @@ public abstract class RamProvisioner {
 	}
 
 	/**
-	 * Sets the ram.
+	 * Sets the ram capacity.
 	 * 
 	 * @param ram the ram to set
 	 */
@@ -125,7 +129,7 @@ public abstract class RamProvisioner {
 	/**
 	 * Gets the available RAM in the host.
 	 * 
-	 * @return available ram
+	 * @return th available ram
 	 * 
 	 * @pre $none
 	 * @post $none

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/provisioners/RamProvisionerSimple.java

@@ -14,8 +14,9 @@ import java.util.Map;
 import org.cloudbus.cloudsim.Vm;
 
 /**
- * RamProvisionerSimple is an extension of RamProvisioner which uses a best-effort policy to
- * allocate memory to a VM.
+ * RamProvisionerSimple is an extension of {@link RamProvisioner} which uses a best-effort policy to
+ * allocate memory to VMs: if there is available ram on the host, it allocates; otherwise, it fails. 
+ * Each host has to have its own instance of a RamProvisioner.
  * 
  * @author Rodrigo N. Calheiros
  * @author Anton Beloglazov
@@ -23,27 +24,26 @@ import org.cloudbus.cloudsim.Vm;
  */
 public class RamProvisionerSimple extends RamProvisioner {
 
-	/** The RAM table. */
+	/** The RAM map, where each key is a VM id and each value
+         * is the amount of RAM allocated to that VM. */
 	private Map<String, Integer> ramTable;
 
 	/**
 	 * Instantiates a new ram provisioner simple.
 	 * 
-	 * @param availableRam the available ram
+	 * @param availableRam The total ram capacity from the host that the provisioner can allocate to VMs. 
 	 */
 	public RamProvisionerSimple(int availableRam) {
 		super(availableRam);
 		setRamTable(new HashMap<String, Integer>());
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.RamProvisioner#allocateRamForVm(cloudsim.Vm, int)
-	 */
 	@Override
 	public boolean allocateRamForVm(Vm vm, int ram) {
 		int maxRam = vm.getRam();
-
+                /* If the requested amount of RAM to be allocated to the VM is greater than
+                the amount of VM is in fact requiring, allocate only the
+                amount defined in the Vm requirements.*/
 		if (ram >= maxRam) {
 			ram = maxRam;
 		}
@@ -62,10 +62,6 @@ public class RamProvisionerSimple extends RamProvisioner {
 		return false;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.RamProvisioner#getAllocatedRamForVm(cloudsim.Vm)
-	 */
 	@Override
 	public int getAllocatedRamForVm(Vm vm) {
 		if (getRamTable().containsKey(vm.getUid())) {
@@ -74,10 +70,6 @@ public class RamProvisionerSimple extends RamProvisioner {
 		return 0;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.RamProvisioner#deallocateRamForVm(cloudsim.Vm)
-	 */
 	@Override
 	public void deallocateRamForVm(Vm vm) {
 		if (getRamTable().containsKey(vm.getUid())) {
@@ -87,20 +79,12 @@ public class RamProvisionerSimple extends RamProvisioner {
 		}
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.RamProvisioner#deallocateRamForVm(cloudsim.Vm)
-	 */
 	@Override
 	public void deallocateRamForAllVms() {
 		super.deallocateRamForAllVms();
 		getRamTable().clear();
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see cloudsim.provisioners.RamProvisioner#isSuitableForVm(cloudsim.Vm, int)
-	 */
 	@Override
 	public boolean isSuitableForVm(Vm vm, int ram) {
 		int allocatedRam = getAllocatedRamForVm(vm);
@@ -113,18 +97,18 @@ public class RamProvisionerSimple extends RamProvisioner {
 	}
 
 	/**
-	 * Gets the ram table.
+	 * Gets the map between VMs and allocated ram.
 	 * 
-	 * @return the ram table
+	 * @return the ram map
 	 */
 	protected Map<String, Integer> getRamTable() {
 		return ramTable;
 	}
 
 	/**
-	 * Sets the ram table.
+	 * Sets the map between VMs and allocated ram.
 	 * 
-	 * @param ramTable the ram table
+	 * @param ramTable the ram map
 	 */
 	protected void setRamTable(Map<String, Integer> ramTable) {
 		this.ramTable = ramTable;