killbill-aplcache

diff --git a/api/src/main/java/com/ning/billing/invoice/api/InvoiceUserApi.java b/api/src/main/java/com/ning/billing/invoice/api/InvoiceUserApi.java
index ef784e0..4a3b43c 100644
--- a/api/src/main/java/com/ning/billing/invoice/api/InvoiceUserApi.java
+++ b/api/src/main/java/com/ning/billing/invoice/api/InvoiceUserApi.java
@@ -31,6 +31,12 @@ import com.ning.billing.util.callcontext.CallContext;
 
 public interface InvoiceUserApi {
 
+    /**
+     * Get all invoices for a given account.
+     *
+     * @param accountId account id
+     * @return all invoices
+     */
     public List<Invoice> getInvoicesByAccount(UUID accountId);
 
     /**
@@ -42,12 +48,36 @@ public interface InvoiceUserApi {
      */
     public List<Invoice> getInvoicesByAccount(UUID accountId, LocalDate fromDate);
 
+    /**
+     * Retrieve the account balance.
+     *
+     * @param accountId account id
+     * @return the account balance
+     */
     public BigDecimal getAccountBalance(UUID accountId);
 
+    /**
+     * Retrieve an invoice by id.
+     *
+     * @param invoiceId invoice id
+     * @return the invoice
+     */
     public Invoice getInvoice(UUID invoiceId);
 
+    /**
+     * Retrieve an invoice by invoice number.
+     *
+     * @param number invoice number
+     * @return the invoice
+     */
     public Invoice getInvoiceByNumber(Integer number);
 
+    /**
+     * Record a payment for an invoice.
+     *
+     * @param invoicePayment invoice payment
+     * @param context        call context
+     */
     public void notifyOfPayment(InvoicePayment invoicePayment, CallContext context);
 
     /**
@@ -71,10 +101,31 @@ public interface InvoiceUserApi {
      */
     public Invoice triggerInvoiceGeneration(UUID accountId, LocalDate targetDate, boolean dryRun, CallContext context) throws InvoiceApiException;
 
+    /**
+     * Mark an invoice as written off.
+     *
+     * @param invoiceId invoice id
+     * @param context   call context
+     * @throws TagApiException
+     */
     public void tagInvoiceAsWrittenOff(UUID invoiceId, CallContext context) throws TagApiException;
 
+    /**
+     * Unmark an invoice as written off.
+     *
+     * @param invoiceId invoice id
+     * @param context   call context
+     * @throws TagApiException
+     */
     public void tagInvoiceAsNotWrittenOff(UUID invoiceId, CallContext context) throws TagApiException;
 
+    /**
+     * Retrieve a credit by id.
+     *
+     * @param creditId credit id
+     * @return the credit
+     * @throws InvoiceApiException
+     */
     public InvoiceItem getCreditById(UUID creditId) throws InvoiceApiException;
 
     /**
@@ -106,5 +157,14 @@ public interface InvoiceUserApi {
     public InvoiceItem insertCreditForInvoice(UUID accountId, UUID invoiceId, BigDecimal amount, LocalDate effectiveDate,
                                               Currency currency, CallContext context) throws InvoiceApiException;
 
+    /**
+     * Retrieve the invoice formatted in HTML.
+     *
+     * @param invoiceId invoice id
+     * @return the invoice in HTML format
+     * @throws AccountApiException
+     * @throws IOException
+     * @throws InvoiceApiException
+     */
     public String getInvoiceAsHTML(UUID invoiceId) throws AccountApiException, IOException, InvoiceApiException;
 }