phpdoc (#29474)

htdocs/variants/class/ProductCombination2ValuePair.class.php

@@ -16,9 +16,27 @@
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
 
+/**
+ *	\file       htdocs/variants/class/ProductCombination2ValuePair.class.php
+ *	\ingroup    variants
+ *	\brief      File of the ProductCombination2ValuePair class
+ */
+
+
 /**
  * Class ProductCombination2ValuePair
- * Used to represent the relation between a product combination, a product attribute and a product attribute value
+ * Used to represent the relation between a variant and its attributes.
+ *
+ * Example: a product "shirt" has a variant "shirt XL white" linked to the attributes "size: XL" and "color: white".
+ * This is represented with two ProductCombination2ValuePair objects:
+ * - One for "size: XL":
+ *     * $object->fk_prod_combination    ID of the ProductCombination object between product "shirt" and its variant "shirt XL white"
+ *     * $object->fk_prod_attr           ID of the ProductAttribute object "size"
+ *     * $object->fk_prod_attr_val       ID of the ProductAttributeValue object "XL"
+ * - Another for "color: white":
+ *     * $object->fk_prod_combination    ID of the ProductCombination object between product "shirt" and its variant "shirt XL white"
+ *     * $object->fk_prod_attr           ID of the ProductAttribute object "color"
+ *     * $object->fk_prod_attr_val       ID of the ProductAttributeValue object "white"
  */
 class ProductCombination2ValuePair
 {
@@ -29,36 +47,41 @@ class ProductCombination2ValuePair
 	private $db;
 
 	/**
-	 * Combination 2 value pair id
+	 * ID of this ProductCombination2ValuePair
 	 * @var int
 	 */
 	public $id;
 
 	/**
-	 * Product combination id
+	 * ID of the ProductCombination linked to this object
+	 * (ex: ID of the ProductCombination between product "shirt" and its variant "shirt XL white")
 	 * @var int
 	 */
 	public $fk_prod_combination;
 
 	/**
-	 * Product attribute id
+	 * ID of the ProductAttribute linked to this object
+	 * (ex: ID of the ProductAttribute "color")
 	 * @var int
 	 */
 	public $fk_prod_attr;
 
 	/**
-	 * Product attribute value id
+	 * ID of the ProductAttributeValue linked to this object
+	 * (ex: ID of the ProductAttributeValue "white")
 	 * @var int
 	 */
 	public $fk_prod_attr_val;
 
 	/**
-	 * @var string error
+	 * Error message
+	 * @var string
 	 */
 	public $error;
 
 	/**
-	 * @var string[] array of errors
+	 * Array of error messages
+	 * @var string[]
 	 */
 	public $errors = array();
 
@@ -92,10 +115,10 @@ public function __toString()
 	}
 
 	/**
-	 * Creates a product combination 2 value pair
+	 * Create a ProductCombination2ValuePair
 	 *
-	 * @param	User	$user		User that create
-	 * @return 	int 				Return integer <0 KO, >0 OK
+	 * @param	User	$user		User that creates		//not used
+	 * @return 	-1|1				1 if OK, -1 if KO
 	 */
 	public function create($user)
 	{
@@ -115,10 +138,10 @@ public function create($user)
 	}
 
 	/**
-	 * Retrieves a product combination 2 value pair from its rowid
+	 * Retrieve all ProductCombination2ValuePair linked to a given ProductCombination ID.
 	 *
-	 * @param int $fk_combination Fk combination to search
-	 * @return int|ProductCombination2ValuePair[] -1 if KO
+	 * @param   int          $fk_combination           ID of the ProductCombination
+	 * @return  -1|ProductCombination2ValuePair[]      -1 if KO, array of ProductCombination2ValuePair if OK
 	 */
 	public function fetchByFkCombination($fk_combination)
 	{
@@ -154,10 +177,10 @@ public function fetchByFkCombination($fk_combination)
 	}
 
 	/**
-	 * Deletes a product combination 2 value pair
+	 * Delete all ProductCombination2ValuePair linked to a given ProductCombination ID.
 	 *
-	 * @param int $fk_combination Rowid of the combination
-	 * @return int >0 OK <0 KO
+	 * @param       int     $fk_combination         ID of the ProductCombination
+	 * @return      -1|1                            -1 if KO, 1 if OK
 	 */
 	public function deleteByFkCombination($fk_combination)
 	{