diff --git a/htdocs/compta/facture/class/api_invoices.class.php b/htdocs/compta/facture/class/api_invoices.class.php
index fec3edd11ea..eccc537b3b3 100644
--- a/htdocs/compta/facture/class/api_invoices.class.php
+++ b/htdocs/compta/facture/class/api_invoices.class.php
@@ -653,7 +653,9 @@ class Invoices extends DolibarrApi
 
 
      /**
-     * Add a discount line into an invoice (as an invoice line) using an existing absolute discount (Consume the discount)
+     * Add a discount line into an invoice (as an invoice line) using an existing absolute discount
+     *
+     * Note that this consume the discount.
      *
      * @param int   $id             Id of invoice
      * @param int   $discountid     Id of discount
@@ -696,7 +698,9 @@ class Invoices extends DolibarrApi
     }
 
      /**
-     * Add an available credit note discount to payments of an existing invoice (Consume the credit note)
+     * Add an available credit note discount to payments of an existing invoice.
+     *
+     *  Note that this consume the credit note.
      *
      * @param int   $id            Id of invoice
      * @param int   $discountid    Id of a discount coming from a credit note
diff --git a/htdocs/societe/class/api_contacts.class.php b/htdocs/societe/class/api_contacts.class.php
index 652f66380d3..84442aaefac 100644
--- a/htdocs/societe/class/api_contacts.class.php
+++ b/htdocs/societe/class/api_contacts.class.php
@@ -96,7 +96,7 @@ class Contacts extends DolibarrApi
 	 * @param string	$sortorder	        Sort order
 	 * @param int		$limit		        Limit for list
 	 * @param int		$page		        Page number
-     * @param string   	$thirdparty_ids	    Thirdparty ids to filter projects of. {@example '1' or '1,2,3'} {@pattern /^[0-9,]*$/i}
+     * @param string   	$thirdparty_ids	    Thirdparty ids to filter contacts of. {@example '1' or '1,2,3'} {@pattern /^[0-9,]*$/i}
      * @param string    $sqlfilters         Other criteria to filter answers separated by a comma. Syntax example "(t.ref:like:'SO-%') and (t.date_creation:<:'20160101')"
 	 * @return array                        Array of contact objects
      *
@@ -274,9 +274,9 @@ class Contacts extends DolibarrApi
 	}
 
 	/**
-	 * Create useraccount object from contact
+	 * Create an user account object from contact (external user)
 	 *
-	 * @param   int   $id   Id of contact
+	 * @param   int   	$id   Id of contact
 	 * @param   array   $request_data   Request datas
 	 * @return  int     ID of user
 	 *