diff --git a/classes/stock/SupplyOrder.php b/classes/stock/SupplyOrder.php
index d15ae4ce8..7c7f91bb0 100755
--- a/classes/stock/SupplyOrder.php
+++ b/classes/stock/SupplyOrder.php
@@ -182,12 +182,12 @@ class SupplyOrderCore extends ObjectModel
 	{
 		$this->calculatePrices();
 
-		$return = parent::update($null_values);
+		$res = parent::update($null_values);
 
-		if ($return)
+		if ($res)
 			$this->addHistory();
 
-		return $return;
+		return $res;
 	}
 
 	/**
@@ -197,12 +197,12 @@ class SupplyOrderCore extends ObjectModel
 	{
 		$this->calculatePrices();
 
-		$return = parent::add($autodate, $null_values);
+		$res = parent::add($autodate, $null_values);
 
-		if ($return)
+		if ($res)
 			$this->addHistory();
 
-		return $return;
+		return $res;
 	}
 
 	/**
@@ -217,29 +217,28 @@ class SupplyOrderCore extends ObjectModel
 		$this->total_with_discount_te = 0;
 		$this->total_tax = 0;
 		$this->total_ti = 0;
-
 		$is_discount = false;
 
 		if (is_numeric($this->discount_rate) && (float)$this->discount_rate > 0)
 			$is_discount = true;
 
-		// get all product entries in this order
+		// gets all product entries in this order
 		$entries = $this->getEntriesCollection();
 
 		foreach ($entries as $entry)
 		{
-			// apply global discount rate on each product if possible
+			// applys global discount rate on each product if possible
 			if ($is_discount)
 				$entry->applyGlobalDiscount((float)$this->discount_rate);
 
-			// add new prices to the total
+			// adds new prices to the total
 			$this->total_te += $entry->price_with_discount_te;
 			$this->total_with_discount_te += $entry->price_with_order_discount_te;
 			$this->total_tax += $entry->tax_value_with_order_discount;
 			$this->total_ti = $this->total_tax + $this->total_with_discount_te;
 		}
 
-		// apply global discount rate if possible
+		// applies global discount rate if possible
 		if ($is_discount)
 			$this->discount_value_te = $this->total_te - $this->total_with_discount_te;
 	}
@@ -334,7 +333,7 @@ class SupplyOrderCore extends ObjectModel
 	}
 
 	/**
-	 * Check if the current state allow to generate delivery_note for this order
+	 * Checks if the current state allows to generate a delivery note for this order
 	 *
 	 * @return bool
 	 */
@@ -350,7 +349,7 @@ class SupplyOrderCore extends ObjectModel
 	}
 
 	/**
-	 * Check if the current state allow add products in stock
+	 * Checks if the current state allows add products in stock
 	 *
 	 * @return bool
 	 */
@@ -366,9 +365,7 @@ class SupplyOrderCore extends ObjectModel
 	}
 
 	/**
-	 * Add order history
-	 *
-	 * @return bool
+	 * Historizes
 	 */
 	protected function addHistory()
 	{
@@ -383,7 +380,7 @@ class SupplyOrderCore extends ObjectModel
 	}
 
 	/**
-	 * Remove all products in the order
+	 * Removes all products ordered
 	 */
 	public function resetProducts()
 	{
diff --git a/classes/stock/SupplyOrderDetail.php b/classes/stock/SupplyOrderDetail.php
index 6f71e2e82..ffbeb19cb 100755
--- a/classes/stock/SupplyOrderDetail.php
+++ b/classes/stock/SupplyOrderDetail.php
@@ -244,35 +244,35 @@ class SupplyOrderDetailCore extends ObjectModel
 	}
 
 	/**
-	 * Determine all price for this product based on its quantity and unit price
-	 * Apply discount if necessary
-	 * Calculate tax value in function of tax rate
+	 * Determines all prices for this product based on its quantity and unit price
+	 * Applies discount if necessary
+	 * Calculates tax value in function of tax rate
 	 *
 	 * @return array
 	 */
 	protected function calculatePrices()
 	{
-		// calcul entry price
+		// calculates entry price
 		$this->price_te = Tools::ps_round((float)$this->unit_price_te * (int)$this->quantity_expected, 6);
 
-		// calcul entry discount value
+		// calculates entry discount value
 		if ($this->discount_rate != null && is_float($this->discount_rate) && $this->discount_rate > 0)
 			$this->discount_value_te = Tools::ps_round((float)$this->price_te * ($this->discount_rate / 100), 6);
 
-		// calcul entry price with discount
+		// calculates entry price with discount
 		$this->price_with_discount_te = Tools::ps_round($this->price_te - $this->discount_value_te, 6);
 
-		// calcul tax value
+		// calculates tax value
 		$this->tax_value = Tools::ps_round($this->price_with_discount_te * ((float)$this->tax_rate / 100), 6);
 		$this->price_ti = Tools::ps_round($this->price_with_discount_te + $this->tax_value, 6);
 
-		// define default values for order discount fields
+		// defines default values for order discount fields
 		$this->tax_value_with_order_discount = Tools::ps_round($this->tax_value, 6);
 		$this->price_with_order_discount_te = Tools::ps_round($this->price_with_discount_te, 6);
 	}
 
 	/**
-	 * Apply a global order discount rate on the current product entity
+	 * Applies a global order discount rate on the current product entity
 	 *
 	 * @param $discount_rate The discount rate in percent (Ex. 5 for 5 percents)
 	 */
@@ -280,11 +280,11 @@ class SupplyOrderDetailCore extends ObjectModel
 	{
 		if ($discount_rate != null && is_numeric($discount_rate) && (float)$discount_rate > 0)
 		{
-			// calculate new price, with global order discount, tax ecluded
+			// calculates new price, with global order discount, tax ecluded
 			$this->price_with_order_discount_te = Tools::ps_round($this->price_with_discount_te - ($this->price_with_discount_te * ((float)$discount_rate / 100)),
 																  6);
 
-			// calculate new tax value, with global order discount
+			// calculates new tax value, with global order discount
 			$this->tax_value_with_order_discount = Tools::ps_round($this->price_with_order_discount_te * ((float)$this->tax_rate / 100), 6);
 
 			parent::update();
@@ -298,7 +298,7 @@ class SupplyOrderDetailCore extends ObjectModel
 	{
 		$errors = array();
 
-		/* Checking for required fields */
+		/* required fields */
 		$fields_required = $this->fieldsRequired;
 
 		if (isset(self::$fieldsRequiredDatabase[get_class($this)]))
@@ -313,13 +313,13 @@ class SupplyOrderDetailCore extends ObjectModel
 					$errors[] = '<b>'.self::displayFieldName($field, get_class($this), $htmlentities)
 								.'</b> '.Tools::displayError('is required.');
 
-		/* Checking for maximum fields sizes */
+		/* Checks maximum fields sizes */
 		foreach ($this->fieldsSize as $field => $max_length)
 			if ($value = $this->{$field} && Tools::strlen($value) > $max_length)
 				$errors[] = '<b>'.self::displayFieldName($field, get_class($this), $htmlentities)
 							.'</b> '.Tools::displayError('is too long.').' ('.Tools::displayError('Maximum length:').' '.$max_length.')';
 
-		/* Checking for fields validity */
+		/* Checks fields validity */
 		foreach ($this->fieldsValidate as $field => $function)
 			if ($value = $this->{$field})
 				if (!Validate::$function($value) && (!empty($value) || in_array($field, $this->fieldsRequired)))
diff --git a/classes/stock/Warehouse.php b/classes/stock/Warehouse.php
index ea15e978b..11e0c1501 100644
--- a/classes/stock/Warehouse.php
+++ b/classes/stock/Warehouse.php
@@ -35,22 +35,22 @@ class WarehouseCore extends ObjectModel
 	/** @var int identifier of the warehouse */
 	public $id;
 
-	/** @var int The id of the address associated to the warehouse */
+	/** @var int Id of the address associated to the warehouse */
 	public $id_address;
 
-	/** @var string The reference of the warehouse */
+	/** @var string Reference of the warehouse */
 	public $reference;
 
-	/** @var string The name of the warehouse */
+	/** @var string Name of the warehouse */
 	public $name;
 
-	/** @var int The id of the employee who is responsible of the warehouse */
+	/** @var int Id of the employee who manages the warehouse */
 	public $id_employee;
 
-	/** @var int The id of the valuation currency of the warehouse */
+	/** @var int Id of the valuation currency of the warehouse */
 	public $id_currency;
 
-	/** @var boolean True if warehouse has been deleted (staying in database as deleted) */
+	/** @var boolean True if warehouse has been deleted (hence, no deletion in DB) */
 	public $deleted = 0;
 
 	/**
@@ -79,7 +79,7 @@ class WarehouseCore extends ObjectModel
 		'reference' => 'isString',
 		'name' => 'isName',
 		'id_employee' => 'isUnsignedId',
-		'management_type' => 'isStockManagement',
+		'management_type' => 'isStockManagement', /* @see Validate::isStockManagement() */
 		'id_currency' => 'isUnsignedId'
 	);
 
@@ -101,9 +101,9 @@ class WarehouseCore extends ObjectModel
 	}
 
 	/**
-	 * Gets the shops associated to the current warehouse
+	 * Gets the shops (id and name) associated to the current warehouse
 	 *
-	 * @return array ids
+	 * @return array
 	 */
 	public function getShops()
 	{
@@ -179,6 +179,7 @@ class WarehouseCore extends ObjectModel
 	/**
 	 * For a given carrier, removes it from the warehouse/carrier association
 	 * If $id_warehouse is set, it only removes the carrier for this warehouse
+	 *
 	 * @param int $id_carrier
 	 * @param int $id_warehouse optional
 	 */
@@ -268,7 +269,7 @@ class WarehouseCore extends ObjectModel
 	}
 
 	/**
-	 * Gets the wareehouses
+	 * Gets available warehouses
 	 * It is possible via ignore_shop and id_shop to filter the list with shop id
 	 *
 	 * @param bool $ignore_shop false by default