killbill-aplcache

diff --git a/account/src/main/java/com/ning/billing/account/api/DefaultChangedField.java b/account/src/main/java/com/ning/billing/account/api/DefaultChangedField.java
index 8501b9f..0b762fd 100644
--- a/account/src/main/java/com/ning/billing/account/api/DefaultChangedField.java
+++ b/account/src/main/java/com/ning/billing/account/api/DefaultChangedField.java
@@ -18,6 +18,8 @@ package com.ning.billing.account.api;
 
 import org.joda.time.DateTime;
 
+import com.ning.billing.util.events.ChangedField;
+
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 

diff --git a/account/src/main/java/com/ning/billing/account/api/user/DefaultAccountChangeEvent.java b/account/src/main/java/com/ning/billing/account/api/user/DefaultAccountChangeEvent.java
index 00668f1..39cc93d 100644
--- a/account/src/main/java/com/ning/billing/account/api/user/DefaultAccountChangeEvent.java
+++ b/account/src/main/java/com/ning/billing/account/api/user/DefaultAccountChangeEvent.java
@@ -21,7 +21,7 @@ import java.util.List;
 import java.util.UUID;
 
 import com.ning.billing.account.api.Account;
-import com.ning.billing.account.api.ChangedField;
+import com.ning.billing.util.events.ChangedField;
 import com.ning.billing.account.api.DefaultChangedField;
 import com.ning.billing.util.events.AccountChangeInternalEvent;
 import com.ning.billing.util.events.DefaultBusInternalEvent;

diff --git a/account/src/main/java/com/ning/billing/account/api/user/DefaultAccountUserApi.java b/account/src/main/java/com/ning/billing/account/api/user/DefaultAccountUserApi.java
index e192265..bd2c79c 100644
--- a/account/src/main/java/com/ning/billing/account/api/user/DefaultAccountUserApi.java
+++ b/account/src/main/java/com/ning/billing/account/api/user/DefaultAccountUserApi.java
@@ -155,11 +155,6 @@ public class DefaultAccountUserApi implements AccountUserApi {
     }
 
     @Override
-    public void saveEmails(final UUID accountId, final List<AccountEmail> newEmails, final CallContext context) {
-        accountEmailDao.saveEmails(accountId, newEmails, internalCallContextFactory.createInternalCallContext(accountId, context));
-    }
-
-    @Override
     public void addEmail(final UUID accountId, final AccountEmail email, final CallContext context) {
         accountEmailDao.addEmail(accountId, email, internalCallContextFactory.createInternalCallContext(accountId, context));
     }
@@ -168,18 +163,4 @@ public class DefaultAccountUserApi implements AccountUserApi {
     public void removeEmail(final UUID accountId, final AccountEmail email, final CallContext context) {
         accountEmailDao.removeEmail(accountId, email, internalCallContextFactory.createInternalCallContext(accountId, context));
     }
-
-    @Override
-    public void removePaymentMethod(final UUID accountId, final CallContext context) throws AccountApiException {
-        updatePaymentMethod(accountId, null, context);
-    }
-
-    @Override
-    public void updatePaymentMethod(final UUID accountId, @Nullable final UUID paymentMethodId, final CallContext context) throws AccountApiException {
-        try {
-            accountDao.updatePaymentMethod(accountId, paymentMethodId, internalCallContextFactory.createInternalCallContext(accountId, context));
-        } catch (EntityPersistenceException e) {
-            throw new AccountApiException(e, e.getCode(), e.getMessage());
-        }
-    }
 }

diff --git a/account/src/test/java/com/ning/billing/account/api/user/TestEventJson.java b/account/src/test/java/com/ning/billing/account/api/user/TestEventJson.java
index d5c4207..8dd87bb 100644
--- a/account/src/test/java/com/ning/billing/account/api/user/TestEventJson.java
+++ b/account/src/test/java/com/ning/billing/account/api/user/TestEventJson.java
@@ -24,7 +24,7 @@ import org.testng.Assert;
 import org.testng.annotations.Test;
 
 import com.ning.billing.account.AccountTestSuite;
-import com.ning.billing.account.api.ChangedField;
+import com.ning.billing.util.events.ChangedField;
 import com.ning.billing.account.api.DefaultBillCycleDay;
 import com.ning.billing.account.api.DefaultChangedField;
 import com.ning.billing.account.api.user.DefaultAccountCreationEvent.DefaultAccountData;

diff --git a/api/src/main/java/com/ning/billing/account/api/Account.java b/api/src/main/java/com/ning/billing/account/api/Account.java
index 86dc8f5..7a9b8f9 100644
--- a/api/src/main/java/com/ning/billing/account/api/Account.java
+++ b/api/src/main/java/com/ning/billing/account/api/Account.java
@@ -19,9 +19,31 @@ package com.ning.billing.account.api;
 import com.ning.billing.junction.api.Blockable;
 import com.ning.billing.util.entity.UpdatableEntity;
 
+/**
+ * The interface <code>Account</code> represents an account within Killbill.
+ * <p>
+ * An <code>Account</code> has a unique UUID and also an externalKey that it set when it is created.
+ * The billCycleDay can be specified when creating the account, or it will be set automatically
+ * by the system.
+ *
+ * @see com.ning.billing.account.api.AccountData
+ */
 
 public interface Account extends AccountData, UpdatableEntity, Blockable {
+
+    /**
+     *
+     * @return the mutable account data
+     */
     public MutableAccountData toMutableAccountData();
 
+    /**
+     * The current account object will have its fields updated with those of the deleted account.
+     * <p>
+     * Some fields cannot be updated when they already have a value:
+     *
+     * @param delegate the input account used to update the fields
+     * @return         the new account
+     */
     public Account mergeWithDelegate(final Account delegate);
 }

diff --git a/api/src/main/java/com/ning/billing/account/api/AccountData.java b/api/src/main/java/com/ning/billing/account/api/AccountData.java
index 6816c4f..9a6cbeb 100644
--- a/api/src/main/java/com/ning/billing/account/api/AccountData.java
+++ b/api/src/main/java/com/ning/billing/account/api/AccountData.java
@@ -22,42 +22,131 @@ import org.joda.time.DateTimeZone;
 
 import com.ning.billing.catalog.api.Currency;
 
+/**
+ * The interface <code>AccountData</code> specifies all the fields on the <code>Account</code>.
+ *
+ */
 public interface AccountData {
+
+    /**
+     *
+     * @return  the account externalKey
+     */
     public String getExternalKey();
 
+    /**
+     * The first and last name when that applies are combined into one name.
+     *
+     * @return  the name of the account
+     * @see     AccountData#getFirstNameLength()
+     */
     public String getName();
 
+    /**
+     * @return  the length of the first name that can be extracted from the name
+     */
     public Integer getFirstNameLength();
 
+    /**
+     *
+     * @return  the primary accunt email
+     */
     public String getEmail();
 
+    /**
+     *
+     * The billCycleDay should be interpreted in the account timezone.
+     * The billCycleDay is used to determine when to bill an account
+     * <p>
+     * Its is either set at account creation time or automatically set by the system.
+     *
+     * @return  the billCycleDay for that account
+     *
+     * @see  com.ning.billing.catalog.api.BillingAlignment
+     */
     public BillCycleDay getBillCycleDay();
 
+    /**
+     *
+     * @return  the currency on the account
+     */
     public Currency getCurrency();
 
+    /**
+     *
+     * @return  the UUID of the current default paymentMethod
+     */
     public UUID getPaymentMethodId();
 
+    /**
+     *
+     * @return  the timezone for that account
+     */
     public DateTimeZone getTimeZone();
 
+    /**
+     *
+     * @return  the locale for that account
+     */
     public String getLocale();
 
+    /**
+     *
+     * @return  the address for that account (first line)
+     */
     public String getAddress1();
 
+    /**
+     *
+     * @return  the address for that account (second line)
+     */
     public String getAddress2();
 
+    /**
+     *
+     * @return  the company for that account
+     */
     public String getCompanyName();
 
+    /**
+     *
+     * @return  the city for that account
+     */
     public String getCity();
 
+    /**
+     *
+     * @return  the state or province for that account
+     */
     public String getStateOrProvince();
 
+    /**
+     *
+     * @return  the postal code for that account
+     */
     public String getPostalCode();
 
+    /**
+     *
+     * @return  the country for that account
+     */
     public String getCountry();
 
+    /**
+     *
+     * @return  the phone number for that account
+     */
     public String getPhone();
 
+    /**
+     *
+     * @return  whether or not that account was migrated into the system
+     */
     public Boolean isMigrated();
 
+    /**
+     *
+     * @return  whether or not that account will receive invoice notifications
+     */
     public Boolean isNotifiedForInvoices();
 }

diff --git a/api/src/main/java/com/ning/billing/account/api/AccountEmail.java b/api/src/main/java/com/ning/billing/account/api/AccountEmail.java
index a1b535f..5ac42af 100644
--- a/api/src/main/java/com/ning/billing/account/api/AccountEmail.java
+++ b/api/src/main/java/com/ning/billing/account/api/AccountEmail.java
@@ -21,7 +21,16 @@ import java.util.UUID;
 import com.ning.billing.util.entity.UpdatableEntity;
 
 public interface AccountEmail extends UpdatableEntity {
+
+    /**
+     *
+     * @return  the accountId for this email
+     */
     UUID getAccountId();
 
+    /**
+     *
+     * @return  the email body
+     */
     String getEmail();
 }

diff --git a/api/src/main/java/com/ning/billing/account/api/AccountService.java b/api/src/main/java/com/ning/billing/account/api/AccountService.java
index febe8dd..f03bed2 100644
--- a/api/src/main/java/com/ning/billing/account/api/AccountService.java
+++ b/api/src/main/java/com/ning/billing/account/api/AccountService.java
@@ -18,6 +18,11 @@ package com.ning.billing.account.api;
 
 import com.ning.billing.lifecycle.KillbillService;
 
+/**
+ * The interface {@code AccountService} is a {@code KillbillService} required to handle account operations
+ *
+ * @see KillbillService
+ */
 public interface AccountService extends KillbillService {
 
 }

diff --git a/api/src/main/java/com/ning/billing/account/api/AccountUserApi.java b/api/src/main/java/com/ning/billing/account/api/AccountUserApi.java
index e0914a5..da18c28 100644
--- a/api/src/main/java/com/ning/billing/account/api/AccountUserApi.java
+++ b/api/src/main/java/com/ning/billing/account/api/AccountUserApi.java
@@ -22,42 +22,122 @@ import java.util.UUID;
 import com.ning.billing.util.callcontext.CallContext;
 import com.ning.billing.util.callcontext.TenantContext;
 
+/**
+ * The interface {@code AccountUserApi} offers APIs related to account operations.
+ */
 public interface AccountUserApi {
 
+    /**
+     *
+     * @param data      the account data
+     * @param context   the user context
+     * @return          the created Account
+     *
+     * @throws AccountApiException
+     */
     public Account createAccount(AccountData data, CallContext context) throws AccountApiException;
 
+    /**
+     *
+     * @param data      the account data
+     * @param context   the user context
+     * @return          the migrated account
+     *
+     * @throws AccountApiException
+     */
     public Account migrateAccount(MigrationAccountData data, CallContext context) throws AccountApiException;
 
     /**
-     * Note: does not update the external key
+     * Updates the account by specifying the destination {@code Account} object
+     * <p>
      *
      * @param account account to be updated
      * @param context contains specific information about the call
+     *
      * @throws AccountApiException if a failure occurs
      */
     public void updateAccount(Account account, CallContext context) throws AccountApiException;
 
+    /**
+     * Updates the account by specifying the {@code AccountData} object
+     * <p>
+     *
+     * @param key account external key
+     * @param context contains specific information about the call
+     *
+     * @throws AccountApiException if a failure occurs
+     */
     public void updateAccount(String key, AccountData accountData, CallContext context) throws AccountApiException;
 
+    /**
+     * Updates the account by specifying the {@code AccountData} object
+     * <p>
+     *
+     * @param accountId account unique id
+     * @param context contains specific information about the call
+     *
+     * @throws AccountApiException if a failure occurs
+     */
     public void updateAccount(UUID accountId, AccountData accountData, CallContext context) throws AccountApiException;
 
-    public void removePaymentMethod(UUID accountId, CallContext context) throws AccountApiException;
-
-    public void updatePaymentMethod(UUID accountId, UUID paymentMethodId, CallContext context) throws AccountApiException;
-
+    /**
+     *
+     * @param key       the externalKey for the account
+     * @param context   the user context
+     * @return          the account
+     *
+     * @throws AccountApiException if there is no such account
+     */
     public Account getAccountByKey(String key, TenantContext context) throws AccountApiException;
 
+    /**
+     *
+     * @param accountId the unique id for the account
+     * @param context   the user context
+     * @return          the account
+     *
+     * @throws AccountApiException if there is no such account
+     */
     public Account getAccountById(UUID accountId, TenantContext context) throws AccountApiException;
 
+    /**
+     *
+     * @param context   the user context
+     * @return          the list of accounts for that tenant
+     */
     public List<Account> getAccounts(TenantContext context);
 
+    /**
+     *
+     * @param externalKey   the externalKey for the account
+     * @param context       the user context
+     * @return              the unique id for that account
+     *
+     * @throws AccountApiException  if there is no such account
+     */
     public UUID getIdFromKey(String externalKey, TenantContext context) throws AccountApiException;
 
+    /**
+     *
+     * @param accountId the account unique id
+     * @param context   the user context
+     * @return          the laist of emails configured for that account
+     */
     public List<AccountEmail> getEmails(UUID accountId, TenantContext context);
 
-    public void saveEmails(UUID accountId, List<AccountEmail> emails, CallContext context);
-
+    /**
+     *
+     * @param accountId the account unique id
+     * @param email     the email to be added
+     * @param context   the user context
+     */
     public void addEmail(UUID accountId, AccountEmail email, CallContext context);
 
+    /**
+     *
+     * @param accountId the account unique id
+     * @param email     the email to be removed
+     * @param context   the user context
+     */
     public void removeEmail(UUID accountId, AccountEmail email, CallContext context);
 }

diff --git a/api/src/main/java/com/ning/billing/account/api/BillCycleDay.java b/api/src/main/java/com/ning/billing/account/api/BillCycleDay.java
index 1fc203d..014bc0b 100644
--- a/api/src/main/java/com/ning/billing/account/api/BillCycleDay.java
+++ b/api/src/main/java/com/ning/billing/account/api/BillCycleDay.java
@@ -16,6 +16,9 @@
 
 package com.ning.billing.account.api;
 
+/**
+ * The interface {@code BillCycleDay} represents the default account billing date
+ */
 public interface BillCycleDay {
 
     int getDayOfMonthUTC();

diff --git a/api/src/main/java/com/ning/billing/account/api/MigrationAccountData.java b/api/src/main/java/com/ning/billing/account/api/MigrationAccountData.java
index 1b00586..275c612 100644
--- a/api/src/main/java/com/ning/billing/account/api/MigrationAccountData.java
+++ b/api/src/main/java/com/ning/billing/account/api/MigrationAccountData.java
@@ -20,8 +20,15 @@ import java.util.List;
 
 import org.joda.time.DateTime;
 
+/**
+ * The interface {@code MigrationAccountData}
+ */
 public interface MigrationAccountData extends AccountData {
 
+    /**
+     *
+     * @return the createdDate for
+     */
     public DateTime getCreatedDate();
 
     public DateTime getUpdatedDate();

diff --git a/api/src/main/java/com/ning/billing/account/api/MutableAccountData.java b/api/src/main/java/com/ning/billing/account/api/MutableAccountData.java
index b1716ec..e2560c3 100644
--- a/api/src/main/java/com/ning/billing/account/api/MutableAccountData.java
+++ b/api/src/main/java/com/ning/billing/account/api/MutableAccountData.java
@@ -22,43 +22,141 @@ import org.joda.time.DateTimeZone;
 
 import com.ning.billing.catalog.api.Currency;
 
+/**
+ * The interface {@code MutableAccountData} is used to set the  {@code AccountData} fields individually and pass them as the whole
+ * to the {@code AccountUserApi}.
+ *
+ */
 public interface MutableAccountData extends AccountData {
+
+    /**
+     * Sets the account external Key
+     *
+     * @param externalKey
+     */
     public void setExternalKey(String externalKey);
 
+    /**
+     * Sets the default account email
+     *
+     * @param email
+     */
     public void setEmail(String email);
 
+    /**
+     * Sets the account name
+     *
+     * @param name
+     */
     public void setName(String name);
 
+    /**
+     * Sets the length for the first name-- if applicable
+     *
+     * @param firstNameLength
+     */
     public void setFirstNameLength(int firstNameLength);
 
+    /**
+     * Sets the account currency
+     *
+     * @param currency
+     */
     public void setCurrency(Currency currency);
 
+    /**
+     * Sets the account billCycleDay
+     *
+     * @param billCycleDay
+     */
     public void setBillCycleDay(BillCycleDay billCycleDay);
 
+    /**
+     * Sets the UUID of the default paymentMethod
+     *
+     * @param paymentMethodId
+     */
     public void setPaymentMethodId(UUID paymentMethodId);
 
+    /**
+     * Sets the account timezone
+     *
+     * @param timeZone
+     */
     public void setTimeZone(DateTimeZone timeZone);
 
+    /**
+     * Sets the account locale
+     *
+     * @param locale
+     */
     public void setLocale(String locale);
 
+    /**
+     * Sets the account address (first line)
+     * @param address1
+     */
     public void setAddress1(String address1);
 
+    /**
+     * Sets the account address (second line)
+     * @param address2
+     */
     public void setAddress2(String address2);
 
+    /**
+     * Sets the account company name
+     *
+     * @param companyName
+     */
     public void setCompanyName(String companyName);
 
+    /**
+     * Sets the account city
+     *
+     * @param city
+     */
     public void setCity(String city);
 
+    /**
+     * Sets the account state or province
+     *
+     * @param stateOrProvince
+     */
     public void setStateOrProvince(String stateOrProvince);
 
+    /**
+     * Sets the account country
+     *
+     * @param country
+     */
     public void setCountry(String country);
 
+    /**
+     * Sets the account postalCode
+     *
+     * @param postalCode
+     */
     public void setPostalCode(String postalCode);
 
+    /**
+     * Sets the account phone number
+     *
+     * @param phone
+     */
     public void setPhone(String phone);
 
+    /**
+     * Sets whether the account has been migrated or not
+     *
+     * @param isMigrated
+     */
     public void setIsMigrated(boolean isMigrated);
 
+    /**
+     * Sets whether or not the account should receive notification on future invoices
+     * @param isNotifiedForInvoices
+     */
     public void setIsNotifiedForInvoices(boolean isNotifiedForInvoices);
 
 }

diff --git a/api/src/main/java/com/ning/billing/analytics/api/AnalyticsService.java b/api/src/main/java/com/ning/billing/analytics/api/AnalyticsService.java
index 23d31be..82c8346 100644
--- a/api/src/main/java/com/ning/billing/analytics/api/AnalyticsService.java
+++ b/api/src/main/java/com/ning/billing/analytics/api/AnalyticsService.java
@@ -18,5 +18,8 @@ package com.ning.billing.analytics.api;
 
 import com.ning.billing.lifecycle.KillbillService;
 
+/**
+ * The interface {@code AnalyticsService} is a {@code KillbillService} required to handle analytics operations.
+ */
 public interface AnalyticsService extends KillbillService {
 }

diff --git a/api/src/main/java/com/ning/billing/analytics/api/user/AnalyticsUserApi.java b/api/src/main/java/com/ning/billing/analytics/api/user/AnalyticsUserApi.java
index ba5ae0f..859a1eb 100644
--- a/api/src/main/java/com/ning/billing/analytics/api/user/AnalyticsUserApi.java
+++ b/api/src/main/java/com/ning/billing/analytics/api/user/AnalyticsUserApi.java
@@ -21,6 +21,9 @@ import com.ning.billing.analytics.api.TimeSeriesData;
 import com.ning.billing.util.callcontext.CallContext;
 import com.ning.billing.util.callcontext.TenantContext;
 
+/**
+ * The interface {@code AnalyticsUserApi} is used to retrieve analytics information on a pre tenant basis
+ */
 public interface AnalyticsUserApi {
 
     /**
@@ -36,7 +39,9 @@ public interface AnalyticsUserApi {
     public TimeSeriesData getSubscriptionsCreatedOverTime(String productType, String slug, TenantContext context);
 
     /**
-     * Rebuild all analytics tables for an account
+     * Rebuild all analytics tables for an account based on the Killbill row tables
+     * <p>
+     * This endpoint should only be used when those tables are not in sync due (bugs?)
      *
      * @param account account
      * @param context call context

diff --git a/api/src/main/java/com/ning/billing/beatrix/bus/api/BeatrixService.java b/api/src/main/java/com/ning/billing/beatrix/bus/api/BeatrixService.java
index d8b5dfa..2d47066 100644
--- a/api/src/main/java/com/ning/billing/beatrix/bus/api/BeatrixService.java
+++ b/api/src/main/java/com/ning/billing/beatrix/bus/api/BeatrixService.java
@@ -17,6 +17,9 @@ package com.ning.billing.beatrix.bus.api;
 
 import com.ning.billing.lifecycle.KillbillService;
 
+/**
+ * The interface {@code BeatrixService} is a {@code KillbillService} required to manage the {@code ExternalBus}
+ *
+ */
 public interface BeatrixService extends KillbillService {
-
 }

diff --git a/api/src/main/java/com/ning/billing/beatrix/bus/api/ExtBusEventType.java b/api/src/main/java/com/ning/billing/beatrix/bus/api/ExtBusEventType.java
index 037cbd5..6ca5900 100644
--- a/api/src/main/java/com/ning/billing/beatrix/bus/api/ExtBusEventType.java
+++ b/api/src/main/java/com/ning/billing/beatrix/bus/api/ExtBusEventType.java
@@ -15,6 +15,9 @@
  */
 package com.ning.billing.beatrix.bus.api;
 
+/**
+ * User visible bus event types.
+ */
 public enum ExtBusEventType {
     ACCOUNT_CREATION,
     ACCOUNT_CHANGE,

diff --git a/api/src/main/java/com/ning/billing/BillingExceptionBase.java b/api/src/main/java/com/ning/billing/BillingExceptionBase.java
index 251773a..44c922f 100644
--- a/api/src/main/java/com/ning/billing/BillingExceptionBase.java
+++ b/api/src/main/java/com/ning/billing/BillingExceptionBase.java
@@ -22,6 +22,7 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 public class BillingExceptionBase extends Exception {
+
     private static final Logger log = LoggerFactory.getLogger(BillingExceptionBase.class);
 
     private static final long serialVersionUID = 165720101383L;

diff --git a/api/src/main/java/com/ning/billing/catalog/api/ActionPolicy.java b/api/src/main/java/com/ning/billing/catalog/api/ActionPolicy.java
index 831a3f2..5dbe51b 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/ActionPolicy.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/ActionPolicy.java
@@ -16,8 +16,19 @@
 
 package com.ning.billing.catalog.api;
 
+/**
+ * Specifies how {@code Subscription} cancellation or plan change should operate
+ * <p>
+ */
 public enum ActionPolicy {
-    END_OF_TERM, // transition occurs at end of term
-    IMMEDIATE,   // transition occurs immediately
-    ILLEGAL      // transition is not allowed
+    /**
+     * The cancellation or {@code Plan} change effectiveDate will occur at the end of the current invoiced service
+     * period, and that will not trigger any proration and credit.
+     */
+    END_OF_TERM,
+    /**
+     * The cancellation or {@code Plan} change effectiveDate will occur at the requestedDate
+     */
+    IMMEDIATE,
+    ILLEGAL
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/BillingAlignment.java b/api/src/main/java/com/ning/billing/catalog/api/BillingAlignment.java
index a774936..7ac463b 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/BillingAlignment.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/BillingAlignment.java
@@ -16,8 +16,33 @@
 
 package com.ning.billing.catalog.api;
 
+/**
+ * The various <code>BillingAlignement<code/> supported in Killbill.
+ * <p>
+ * The <code>Catalog</code> will define the billing alignement for each <code>Plan</code>
+ *
+ * @see com.ning.billing.catalog.api.Plan
+ * @see com.ning.billing.catalog.api.PlanPhase
+ * @see com.ning.billing.catalog.api.ProductCategory
+ */
 public enum BillingAlignment {
+    /**
+     * All {@code Subscription}s whose {@code Plan} has been configured with this alignment will
+     * be invoiced using the {@code Account} billCycleDay.
+     */
     ACCOUNT,
+
+    /**
+     * All {@code Subscription}s whose {@code Plan} has been configured with this alignment will
+     * be invoiced using the startDate of the first billable {@code PlanPhase} for the {@code ProductCategory.BASE}
+     * {@code Plan}.
+     */
     BUNDLE,
+
+    /**
+     * All {@code Subscription}s whose {@code Plan} has been configured with this alignment will
+     * be invoiced using the startDate of the first billable {@code PlanPhase} for the
+     * {@code Subscription}.
+     */
     SUBSCRIPTION
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/BillingPeriod.java b/api/src/main/java/com/ning/billing/catalog/api/BillingPeriod.java
index 6ab91ed..a0e8011 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/BillingPeriod.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/BillingPeriod.java
@@ -16,12 +16,13 @@
 
 package com.ning.billing.catalog.api;
 
+/**
+ * The {@code BillingPeriod} supported in the system
+ */
 public enum BillingPeriod {
     MONTHLY(1),
     QUARTERLY(3),
-    //SEMI_ANNUAL(6), ** not yet supported
     ANNUAL(12),
-    //BI_ANNUAL(24); ** not yet supported
     NO_BILLING_PERIOD(0);
 
     private final int numberOfMonths;

diff --git a/api/src/main/java/com/ning/billing/catalog/api/Catalog.java b/api/src/main/java/com/ning/billing/catalog/api/Catalog.java
index af96414..f6fd855 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/Catalog.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/Catalog.java
@@ -18,66 +18,140 @@ package com.ning.billing.catalog.api;
 
 import org.joda.time.DateTime;
 
+/**
+ * The {@code Catalog} information for a specific tenant.
+ *
+ */
 public interface Catalog {
-    //
-    // Simple getters
-    //
-    public abstract String getCatalogName();
-
-    public abstract Currency[] getSupportedCurrencies(DateTime requestedDate) throws CatalogApiException;
-
-    public abstract Product[] getProducts(DateTime requestedDate) throws CatalogApiException;
-
-    public abstract Plan[] getPlans(DateTime requestedDate) throws CatalogApiException;
 
-
-    //
-    // Find a plan
-    //
-
-    public abstract Plan findPlan(String name, DateTime requestedDate) throws CatalogApiException;
-
-    public abstract Plan findPlan(String productName, BillingPeriod term, String priceListName,
+    /**
+     *
+     * @return  the catalogName
+     */
+    public String getCatalogName();
+
+    /**
+     *
+     * @param requestedDate specifies the state of the catalog for that date
+     * @return              an array of available {@code Currency}s
+     *
+     * @throws CatalogApiException
+     */
+    public Currency[] getSupportedCurrencies(DateTime requestedDate) throws CatalogApiException;
+
+    /**
+     *
+     * @param requestedDate specifies the state of the catalog for that date
+     * @return              an array of available {@code Product}s
+     *
+     * @throws CatalogApiException
+     */
+    public Product[] getProducts(DateTime requestedDate) throws CatalogApiException;
+
+    /**
+     *
+     * @param requestedDate specifies the state of the catalog for that date
+     * @return              an array of available {@code Plan}s
+     * @throws CatalogApiException
+     */
+    public Plan[] getPlans(DateTime requestedDate) throws CatalogApiException;
+
+    /**
+     *
+     * @param name          the unique name of the plan
+     * @param requestedDate specifies the state of the catalog for that date
+     * @return              the {@code Plan}
+     *
+     * @throws CatalogApiException if {@code Plan} does not exist
+     */
+    public Plan findPlan(String name, DateTime requestedDate) throws CatalogApiException;
+
+    /**
+     *
+     * @param productName   the unique name for the {@code Product}
+     * @param billingPeriod the unique name for the {@code BillingPeriod}
+     * @param priceListName the unique name for the {@code PriceList}
+     * @param requestedDate specifies the state of the catalog for that date
+     * @return              the {@code Plan}
+     *
+     * @throws CatalogApiException if {@code Plan} does not exist
+     */
+    public Plan findPlan(String productName, BillingPeriod billingPeriod, String priceListName,
                                   DateTime requestedDate) throws CatalogApiException;
 
-    public abstract Plan findPlan(String name, DateTime effectiveDate, DateTime subscriptionStartDate) throws CatalogApiException;
-
-    public abstract Plan findPlan(String productName, BillingPeriod term, String priceListName,
+    /**
+     *
+     * @param name                  the unique name of the plan
+     * @param requestedDate         specifies the state of the catalog for that date
+     * @param subscriptionStartDate the startDate of the subscription
+     * @return                      the {@code Plan}
+     *
+     * @throws CatalogApiException if {@code Plan} does not exist
+     */
+    public Plan findPlan(String name, DateTime requestedDate, DateTime subscriptionStartDate) throws CatalogApiException;
+
+    /**
+     *
+     * @param productName   the unique name for the {@code Product}
+     * @param billingPeriod the unique name for the {@code BillingPeriod}
+     * @param priceListName the unique name for the {@code PriceList}
+     * @param requestedDate specifies the state of the catalog for that date
+     * @return              the {@code Plan}
+     *
+     * @throws CatalogApiException if {@code Plan} does not exist
+     */
+    public Plan findPlan(String productName, BillingPeriod billingPeriod, String priceListName,
                                   DateTime requestedDate, DateTime subscriptionStartDate) throws CatalogApiException;
 
-    //
-    // Find a product
-    //
-    public abstract Product findProduct(String name, DateTime requestedDate) throws CatalogApiException;
-
-    //
-    // Find a phase
-    //  
-    public abstract PlanPhase findPhase(String name, DateTime requestedDate, DateTime subscriptionStartDate) throws CatalogApiException;
-
-    //
-    // Find a priceList
-    //  
-    public abstract PriceList findPriceList(String name, DateTime requestedDate) throws CatalogApiException;
-
-    //
-    // Rules
-    //
-    public abstract ActionPolicy planChangePolicy(PlanPhaseSpecifier from,
+    /**
+     *
+     * @param name          the unique name for the {@code Product}
+     * @param requestedDate specifies the state of the catalog for that date
+     * @return              the {@code Product}
+     *
+     * @throws CatalogApiException if {@code Product} does not exist
+     */
+    public Product findProduct(String name, DateTime requestedDate) throws CatalogApiException;
+
+    /**
+     *
+     * @param name          the unique name for the {@code PlanPhase}
+     * @param requestedDate specifies the state of the catalog for that date
+     * @return              the {@code PlanPhase}
+     *
+     * @throws CatalogApiException if the {@code PlanPhase} does not exist
+     */
+    public PriceList findPriceList(String name, DateTime requestedDate) throws CatalogApiException;
+
+
+    /**
+     *
+     * @param name                  the unique name for the {@code PlanPhase}
+     * @param requestedDate         specifies the state of the catalog for that date
+     * @param subscriptionStartDate the startDate of the subscription
+     * @return                      the {@code PlanPhase}
+     * @throws CatalogApiException if the {@code PlanPhase} does not exist
+     */
+    public PlanPhase findPhase(String name, DateTime requestedDate, DateTime subscriptionStartDate) throws CatalogApiException;
+
+
+    // TODO : should they be private APIs
+
+    public ActionPolicy planChangePolicy(PlanPhaseSpecifier from,
                                                   PlanSpecifier to, DateTime requestedDate) throws CatalogApiException;
 
-    public abstract PlanChangeResult planChange(PlanPhaseSpecifier from,
+    public PlanChangeResult planChange(PlanPhaseSpecifier from,
                                                 PlanSpecifier to, DateTime requestedDate) throws CatalogApiException;
 
-    public abstract ActionPolicy planCancelPolicy(PlanPhaseSpecifier planPhase, DateTime requestedDate) throws CatalogApiException;
+    public ActionPolicy planCancelPolicy(PlanPhaseSpecifier planPhase, DateTime requestedDate) throws CatalogApiException;
 
-    public abstract PlanAlignmentCreate planCreateAlignment(PlanSpecifier specifier, DateTime requestedDate) throws CatalogApiException;
+    public PlanAlignmentCreate planCreateAlignment(PlanSpecifier specifier, DateTime requestedDate) throws CatalogApiException;
 
-    public abstract BillingAlignment billingAlignment(PlanPhaseSpecifier planPhase, DateTime requestedDate) throws CatalogApiException;
+    public BillingAlignment billingAlignment(PlanPhaseSpecifier planPhase, DateTime requestedDate) throws CatalogApiException;
 
-    public abstract PlanAlignmentChange planChangeAlignment(PlanPhaseSpecifier from,
+    public PlanAlignmentChange planChangeAlignment(PlanPhaseSpecifier from,
                                                             PlanSpecifier to, DateTime requestedDate) throws CatalogApiException;
 
-    public abstract boolean canCreatePlan(PlanSpecifier specifier, DateTime requestedDate) throws CatalogApiException;
+    public boolean canCreatePlan(PlanSpecifier specifier, DateTime requestedDate) throws CatalogApiException;
 
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/CatalogService.java b/api/src/main/java/com/ning/billing/catalog/api/CatalogService.java
index 6b7b673..541d7e0 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/CatalogService.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/CatalogService.java
@@ -18,6 +18,10 @@ package com.ning.billing.catalog.api;
 
 import com.ning.billing.lifecycle.KillbillService;
 
+
+/**
+ * The interface {@code CatalogService} is a {@code KillbillService} required to handle catalog operations.
+ */
 public interface CatalogService extends KillbillService {
 
     public abstract Catalog getFullCatalog();

diff --git a/api/src/main/java/com/ning/billing/catalog/api/CatalogUserApi.java b/api/src/main/java/com/ning/billing/catalog/api/CatalogUserApi.java
index e7c9cb9..6225e84 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/CatalogUserApi.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/CatalogUserApi.java
@@ -18,7 +18,16 @@ package com.ning.billing.catalog.api;
 
 import com.ning.billing.util.callcontext.TenantContext;
 
+/**
+ * The interface {@code CatalogUserApi} to retrieve catalog information
+ */
 public interface CatalogUserApi {
 
+    /**
+     *
+     * @param catalogName   the name of the catalog
+     * @param context       the user context that specifies the enant information
+     * @return              the {@code Catalog}
+     */
     Catalog getCatalog(String catalogName, TenantContext context);
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/Duration.java b/api/src/main/java/com/ning/billing/catalog/api/Duration.java
index fe1b01a..ad9ae26 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/Duration.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/Duration.java
@@ -21,10 +21,23 @@ import org.joda.time.Period;
 
 public interface Duration {
 
-    public abstract TimeUnit getUnit();
+    /**
+     *
+     * @return the {@code TimeUnit}
+     */
+    public TimeUnit getUnit();
 
-    public abstract int getNumber();
+    /**
+     *
+     * @return the number of units
+     */
+    public int getNumber();
 
+    /**
+     *
+     * @param dateTime  the date to add to that duration
+     * @return          the joda {@code Period}
+     */
     public DateTime addToDateTime(DateTime dateTime);
 
     public Period toJodaPeriod();

diff --git a/api/src/main/java/com/ning/billing/catalog/api/InternationalPrice.java b/api/src/main/java/com/ning/billing/catalog/api/InternationalPrice.java
index 7f8ffef..266cc97 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/InternationalPrice.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/InternationalPrice.java
@@ -19,12 +19,31 @@ package com.ning.billing.catalog.api;
 import java.math.BigDecimal;
 
 
+/**
+ * The interface {@code InternationalPrice} allows to associate a set of prices in different currencies to
+ * a given object.
+ */
 public interface InternationalPrice {
 
+    /**
+     *
+     * @return an array of {@code Price} in the various currencies
+     */
     public abstract Price[] getPrices();
 
+    /**
+     *
+     * @param currency  the currency
+     * @return          the price associated with that currency
+     *
+     * @throws CatalogApiException if there is no entry
+     */
     public abstract BigDecimal getPrice(Currency currency) throws CatalogApiException;
 
+    /**
+     *
+     * @return whether this is a zero price
+     */
     public abstract boolean isZero();
 
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/Listing.java b/api/src/main/java/com/ning/billing/catalog/api/Listing.java
index 69ac8b5..3c07299 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/Listing.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/Listing.java
@@ -18,7 +18,15 @@ package com.ning.billing.catalog.api;
 
 public interface Listing {
 
+    /**
+     *
+     * @return the {@code Plan}
+     */
     Plan getPlan();
 
+    /**
+     *
+     * @return the {@code PriceList}
+     */
     PriceList getPriceList();
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/MigrationPlan.java b/api/src/main/java/com/ning/billing/catalog/api/MigrationPlan.java
index cdb0433..7ae53a8 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/MigrationPlan.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/MigrationPlan.java
@@ -17,6 +17,7 @@
 package com.ning.billing.catalog.api;
 
 public interface MigrationPlan extends Plan {
+
     public static final String MIGRATION_PLAN_NAME = "__KILLBILL_MIGRATION_PLAN__";
     public static final String MIGRATION_PLAN_PHASE_NAME = "__KILLBILL_MIGRATION_PLAN_PHASE__";
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/OverdueActions.java b/api/src/main/java/com/ning/billing/catalog/api/OverdueActions.java
index d73db06..e9b937d 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/OverdueActions.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/OverdueActions.java
@@ -16,6 +16,9 @@
 
 package com.ning.billing.catalog.api;
 
+/**
+ * The enum {@code OverdueActions} specifies the policies that should be taken when a specific object becomes overdue
+ */
 public enum OverdueActions {
     CANCEL,
     PAYMENT_RETRY

diff --git a/api/src/main/java/com/ning/billing/catalog/api/Plan.java b/api/src/main/java/com/ning/billing/catalog/api/Plan.java
index 551a9e1..1116401 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/Plan.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/Plan.java
@@ -21,30 +21,86 @@ import java.util.Iterator;
 
 import org.joda.time.DateTime;
 
+/**
+ * The interface {@code Plan}
+ */
 public interface Plan {
 
-    public abstract PlanPhase[] getInitialPhases();
-
-    public abstract Product getProduct();
-
-    public abstract String getName();
-
-    public abstract boolean isRetired();
-
-    public abstract Iterator<PlanPhase> getInitialPhaseIterator();
-
-    public abstract PlanPhase getFinalPhase();
-
-    public abstract BillingPeriod getBillingPeriod();
-
-    public abstract int getPlansAllowedInBundle();
-
-    public abstract PlanPhase[] getAllPhases();
-
-    public abstract Date getEffectiveDateForExistingSubscriptons();
-
-    public abstract PlanPhase findPhase(String name) throws CatalogApiException;
-
-    public abstract DateTime dateOfFirstRecurringNonZeroCharge(DateTime subscriptionStartDate, PhaseType intialPhaseType);
+    /**
+     * 
+     * @return an array of {@code PlanPhase}
+     */
+    public PlanPhase[] getInitialPhases();
+
+    /**
+     *
+     * @return the {@code Product} associated with that {@code Plan}
+     */
+    public Product getProduct();
+
+    /**
+     *
+     * @return the name of the {@code Plan}
+     */
+    public String getName();
+
+    /**
+     *
+     * @return whether the {@code Plan} has been retired
+     */
+    public boolean isRetired();
+
+    /**
+     *
+     * @return an iterator through the {@code PlanPhase}
+     */
+    public Iterator<PlanPhase> getInitialPhaseIterator();
+
+    /**
+     *
+     * @return the final {@code PlanPhase}
+     */
+    public PlanPhase getFinalPhase();
+
+    /**
+     *
+     * @return the {@code BillingPeriod}
+     */
+    public BillingPeriod getBillingPeriod();
+
+    /**
+     *
+     * @return the number of instance of subscriptions in a bundle with that {@code Plan}
+     */
+    public int getPlansAllowedInBundle();
+
+    /**
+     *
+     * @return an array of {@code PlanPhase}
+     */
+    public PlanPhase[] getAllPhases();
+
+    /**
+     *
+     * @return the date for which existing subscriptions become effective with that {@code Plan}
+     */
+    public Date getEffectiveDateForExistingSubscriptons();
+
+    /**
+     *
+     * @param name  the name of the {@code PlanPhase}
+     * @return      the {@code PlanPhase}
+     *
+     * @throws CatalogApiException if there is not such {@code PlanPhase}
+     */
+    public PlanPhase findPhase(String name) throws CatalogApiException;
+
+    /**
+     *
+     * @param subscriptionStartDate the subscriptionStartDate
+     * @param intialPhaseType       the type of the initial phase
+     * @return                      the date at which we see the first recurring non zero charge
+     */
+    public DateTime dateOfFirstRecurringNonZeroCharge(DateTime subscriptionStartDate, PhaseType intialPhaseType);
 
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/PlanAlignmentCreate.java b/api/src/main/java/com/ning/billing/catalog/api/PlanAlignmentCreate.java
index 5f4a851..33944b5 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/PlanAlignmentCreate.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/PlanAlignmentCreate.java
@@ -16,6 +16,11 @@
 
 package com.ning.billing.catalog.api;
 
+// TODO private?
+
+/**
+ * The available alignments for the entitlement system
+ */
 public enum PlanAlignmentCreate {
     START_OF_BUNDLE,
     START_OF_SUBSCRIPTION,

diff --git a/api/src/main/java/com/ning/billing/catalog/api/PlanPhase.java b/api/src/main/java/com/ning/billing/catalog/api/PlanPhase.java
index fa43433..6b9082e 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/PlanPhase.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/PlanPhase.java
@@ -17,21 +17,52 @@
 package com.ning.billing.catalog.api;
 
 
+/**
+ * The interface {@code PlanPhase} is used to express the various phases available on a given {@code Plan}
+ * 
+ * @see com.ning.billing.catalog.api.Plan
+  */
 public interface PlanPhase {
 
-    public abstract InternationalPrice getRecurringPrice();
+    /**
+     *
+     * @return the recurring {@code InternationalPrice} for that {@code Phase} if defined
+     */
+    public InternationalPrice getRecurringPrice();
 
-    public abstract InternationalPrice getFixedPrice();
+    /**
+     *
+     * @return the fixed {@code InternationalPrice} for that {@code Phase} if defined
+     */
+    public InternationalPrice getFixedPrice();
 
-    public abstract BillingPeriod getBillingPeriod();
+    /**
+     *
+     * @return the {@code BillingPeriod}
+     */
+    public BillingPeriod getBillingPeriod();
 
-    public abstract String getName();
+    /**
+     *
+     * @return the unique name for that {@code Phase}
+     */
+    public String getName();
 
-    public abstract Plan getPlan();
-
-    public abstract Duration getDuration();
-
-    public abstract PhaseType getPhaseType();
+    /**
+     *
+     * @return the parent {@code Plan}
+     */
+    public Plan getPlan();
 
+    /**
+     *
+     * @return the duration of that {@code PlanPhase}
+     */
+    public Duration getDuration();
 
+    /**
+     *
+     * @return  the {@code PhaseType}
+     */
+    public PhaseType getPhaseType();
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/PlanPhaseSpecifier.java b/api/src/main/java/com/ning/billing/catalog/api/PlanPhaseSpecifier.java
index d737426..9206720 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/PlanPhaseSpecifier.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/PlanPhaseSpecifier.java
@@ -16,6 +16,11 @@
 
 package com.ning.billing.catalog.api;
 
+// TODO should be interface ?
+
+/**
+ * The class {@code PlanPhaseSpecifier} specifies the attributes of a {@code PlanPhase}
+ */
 public class PlanPhaseSpecifier {
 
     private final PhaseType phaseType;
@@ -33,26 +38,50 @@ public class PlanPhaseSpecifier {
         this.priceListName = priceListName;
     }
 
+    /**
+     *
+     * @return the {@code Product} name
+     */
     public String getProductName() {
         return productName;
     }
 
+    /**
+     *
+     * @return the {@code ProductCategory}
+     */
     public ProductCategory getProductCategory() {
         return productCategory;
     }
 
+    /**
+     *
+     * @return the {@code BillingPeriod}
+     */
     public BillingPeriod getBillingPeriod() {
         return billingPeriod;
     }
 
+    /**
+     *
+     * @return the name of the {@code PriceList}
+     */
     public String getPriceListName() {
         return priceListName;
     }
 
+    /**
+     *
+     * @return the {@code PhaseType}
+     */
     public PhaseType getPhaseType() {
         return phaseType;
     }
 
+    /**
+     *
+     * @return the {@code PlanSpecifier}
+     */
     public PlanSpecifier toPlanSpecifier() {
         return new PlanSpecifier(productName, productCategory, billingPeriod, priceListName);
     }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/PlanSpecifier.java b/api/src/main/java/com/ning/billing/catalog/api/PlanSpecifier.java
index bc88ae6..a1dce56 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/PlanSpecifier.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/PlanSpecifier.java
@@ -16,7 +16,13 @@
 
 package com.ning.billing.catalog.api;
 
+// TODO should be interface?
+
+/**
+ * The class {@code PlanSpecifier} specifies the attributes of a {@code Plan}
+ */
 public class PlanSpecifier {
+
     private final String productName;
     private final ProductCategory productCategory;
     private final BillingPeriod billingPeriod;
@@ -39,18 +45,34 @@ public class PlanSpecifier {
         this.priceListName = planPhase.getPriceListName();
     }
 
+    /**
+     *
+     * @return the name of the product
+     */
     public String getProductName() {
         return productName;
     }
 
+    /**
+     *
+     * @return the {@code ProductCategory}
+     */
     public ProductCategory getProductCategory() {
         return productCategory;
     }
 
+    /**
+     *
+     * @return the {@code BillingPeriod}
+     */
     public BillingPeriod getBillingPeriod() {
         return billingPeriod;
     }
 
+    /**
+     *
+     * @return the name of the {@code PriceList}
+     */
     public String getPriceListName() {
         return priceListName;
     }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/Price.java b/api/src/main/java/com/ning/billing/catalog/api/Price.java
index a98275a..213b533 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/Price.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/Price.java
@@ -21,8 +21,18 @@ import java.math.BigDecimal;
 
 public interface Price {
 
-    public abstract Currency getCurrency();
+    /**
+     *
+     * @return the {@code Currency}
+     */
+    public Currency getCurrency();
 
-    public abstract BigDecimal getValue() throws CurrencyValueNull;
+    /**
+     *
+     * @return the price amount
+     *
+     * @throws CurrencyValueNull
+     */
+    public BigDecimal getValue() throws CurrencyValueNull;
 
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/PriceListSet.java b/api/src/main/java/com/ning/billing/catalog/api/PriceListSet.java
index 5e78044..5e0565d 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/PriceListSet.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/PriceListSet.java
@@ -20,6 +20,13 @@ public interface PriceListSet {
 
     public static final String DEFAULT_PRICELIST_NAME = "DEFAULT";
 
-    public abstract Plan getPlanListFrom(String priceListName, Product product, BillingPeriod period);
+    /**
+     *
+     * @param priceListName the name of the {@code PriceList}
+     * @param product       the {@code Product}
+     * @param period        the {@code BillingPeriod}
+     * @return              the {@code Plan}
+     */
+    public Plan getPlanListFrom(String priceListName, Product product, BillingPeriod period);
 
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/Product.java b/api/src/main/java/com/ning/billing/catalog/api/Product.java
index cb08271..21f1502 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/Product.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/Product.java
@@ -16,20 +16,46 @@
 
 package com.ning.billing.catalog.api;
 
-
+/**
+ * The interface {@code Product}
+ */
 public interface Product {
 
-    public abstract String getName();
-
-    public abstract boolean isRetired();
-
-    public abstract Product[] getAvailable();
-
-    public abstract Product[] getIncluded();
-
-    public abstract ProductCategory getCategory();
-
-    public abstract String getCatalogName();
+    /**
+     * 
+     * @return the name of the {@code Product}
+     */
+    public String getName();
+
+    /**
+     * 
+     * @return whether this {@code Product} has been retired
+     */
+    public boolean isRetired();
+
+    /**
+     * 
+     * @return an array of other {@code Product} that can be purchased with that one
+     */
+    public Product[] getAvailable();
+
+    /**
+     * 
+     * @return an array of other {@code Product} that are already included within this one
+     */
+    public Product[] getIncluded();
+
+    /**
+     * 
+     * @return the {@code ProductCategory} associated with that {@code Product}
+     */
+    public ProductCategory getCategory();
+
+    /**
+     * 
+     * @return the name of tha catalog where this {@code Product} has been defined
+     */
+    public String getCatalogName();
 
 
 }

diff --git a/api/src/main/java/com/ning/billing/catalog/api/StaticCatalog.java b/api/src/main/java/com/ning/billing/catalog/api/StaticCatalog.java
index 8f2fbcf..9ce760b 100644
--- a/api/src/main/java/com/ning/billing/catalog/api/StaticCatalog.java
+++ b/api/src/main/java/com/ning/billing/catalog/api/StaticCatalog.java
@@ -20,64 +20,122 @@ import java.util.Date;
 import java.util.List;
 
 
+/**
+ * The interface {@code StaticCatalog} gives the view of that {@code Catalog} at a given time.
+ * This represents a specific version of the {@code Catalog}
+ */
 public interface StaticCatalog {
-    //
-    // Simple getters
-    //
-    public abstract String getCatalogName();
-
-    public abstract Date getEffectiveDate() throws CatalogApiException;
-
-    public abstract Currency[] getCurrentSupportedCurrencies() throws CatalogApiException;
-
-    public abstract Product[] getCurrentProducts() throws CatalogApiException;
-
-    public abstract Plan[] getCurrentPlans() throws CatalogApiException;
-
-    //
-    // Find a plan
-    //
-    public abstract Plan findCurrentPlan(String productName, BillingPeriod term, String priceList) throws CatalogApiException;
 
-    public abstract Plan findCurrentPlan(String name) throws CatalogApiException;
-
-    //
-    // Find a product
-    //
-    public abstract Product findCurrentProduct(String name) throws CatalogApiException;
-
-    //
-    // Find a phase
-    //
-    public abstract PlanPhase findCurrentPhase(String name) throws CatalogApiException;
-
-    //
-    // Find a pricelist
-    //
-    public abstract PriceList findCurrentPricelist(String name) throws CatalogApiException;
-
-    //
-    //
-    //
-    public abstract ActionPolicy planChangePolicy(PlanPhaseSpecifier from,
+    /**
+     *
+     * @return the {@code Catalog} name
+     */
+    public String getCatalogName();
+
+    /**
+     *
+     * @return the date at which this version of {@code Catalog} becomes effective
+     *
+     * @throws CatalogApiException
+     */
+    public Date getEffectiveDate() throws CatalogApiException;
+
+    /**
+     *
+     * @return an array of supported {@code Currency}
+     *
+     * @throws CatalogApiException
+     */
+    public Currency[] getCurrentSupportedCurrencies() throws CatalogApiException;
+
+    /**
+     *
+     * @return an array of supported {@code Product}
+     *
+     * @throws CatalogApiException
+     */
+    public Product[] getCurrentProducts() throws CatalogApiException;
+
+    /**
+     *
+     * @return an array of supported {@code Plan}
+     *
+     * @throws CatalogApiException
+     */
+    public Plan[] getCurrentPlans() throws CatalogApiException;
+
+    /**
+     *
+     * @param productName   the {@code Product} name
+     * @param billingPeriod the billingPeriod
+     * @param priceList     the name of the {@code PriceList}
+     * @return              the {@code Plan}
+     *
+     * @throws CatalogApiException if not such {@code Plan} can be found
+     */
+    public Plan findCurrentPlan(String productName, BillingPeriod billingPeriod, String priceList) throws CatalogApiException;
+
+    /**
+     *
+     * @param name  the name of the {@Plan}
+     * @return      the {@code Plan}
+     *
+     * @throws CatalogApiException if not such {@code Plan} can be found
+     */
+    public Plan findCurrentPlan(String name) throws CatalogApiException;
+
+    /**
+     *
+     * @param name  the name of the {@code Product}
+     * @return      the {@code Product}
+     *
+     * @throws CatalogApiException if no such {@code Product} exists
+     */
+    public Product findCurrentProduct(String name) throws CatalogApiException;
+
+    /**
+     *
+     * @param name  the name of the {@code PlanPhase}
+     * @return      the {@code PlanPhase}
+     *
+     * @throws CatalogApiException if no such {@code PlanPhase} exists
+     */
+    public PlanPhase findCurrentPhase(String name) throws CatalogApiException;
+
+
+    /**
+     *
+     * @param name  the name of the {@code PriceList}
+     * @return      the {@code PriceList}
+     *
+     * @throws CatalogApiException if no such {@code PriceList} exists
+     */
+    public PriceList findCurrentPricelist(String name) throws CatalogApiException;
+
+
+    // TODO private APIs ?
+
+    public ActionPolicy planChangePolicy(PlanPhaseSpecifier from,
                                                   PlanSpecifier to) throws CatalogApiException;
 
-    public abstract PlanChangeResult planChange(PlanPhaseSpecifier from,
+    public PlanChangeResult planChange(PlanPhaseSpecifier from,
                                                 PlanSpecifier to) throws CatalogApiException;
 
 
-    public abstract ActionPolicy planCancelPolicy(PlanPhaseSpecifier planPhase) throws CatalogApiException;
 
-    public abstract PlanAlignmentCreate planCreateAlignment(PlanSpecifier specifier) throws CatalogApiException;
 
-    public abstract BillingAlignment billingAlignment(PlanPhaseSpecifier planPhase) throws CatalogApiException;
+    public ActionPolicy planCancelPolicy(PlanPhaseSpecifier planPhase) throws CatalogApiException;
+
+    public PlanAlignmentCreate planCreateAlignment(PlanSpecifier specifier) throws CatalogApiException;
+
+    public BillingAlignment billingAlignment(PlanPhaseSpecifier planPhase) throws CatalogApiException;
 
-    public abstract PlanAlignmentChange planChangeAlignment(PlanPhaseSpecifier from,
+    public PlanAlignmentChange planChangeAlignment(PlanPhaseSpecifier from,
                                                             PlanSpecifier to) throws CatalogApiException;
 
-    public abstract boolean canCreatePlan(PlanSpecifier specifier) throws CatalogApiException;
+    public boolean canCreatePlan(PlanSpecifier specifier) throws CatalogApiException;
 
-    public abstract List<Listing> getAvailableBasePlanListings() throws CatalogApiException;
-    public abstract List<Listing> getAvailableAddonListings(String baseProductName) throws CatalogApiException;
+    public List<Listing> getAvailableBasePlanListings() throws CatalogApiException;
+    public List<Listing> getAvailableAddonListings(String baseProductName) throws CatalogApiException;
 
 }

diff --git a/api/src/main/java/com/ning/billing/lifecycle/KillbillService.java b/api/src/main/java/com/ning/billing/lifecycle/KillbillService.java
index df00532..148bf15 100644
--- a/api/src/main/java/com/ning/billing/lifecycle/KillbillService.java
+++ b/api/src/main/java/com/ning/billing/lifecycle/KillbillService.java
@@ -16,6 +16,14 @@
 
 package com.ning.billing.lifecycle;
 
+/**
+ * The interface <code>KillbillService<code/> represents a service that will go through the Killbill lifecyle.
+ * <p>
+ * A <code>KillbillService<code> can register handlers for the various phases of the lifecycle, so
+ * that its proper initialization/shutdown sequence occurs at the right time with regard
+ * to other <code>KillbillService</code>.
+ *
+ */
 public interface KillbillService {
 
     public static class ServiceException extends Exception {

diff --git a/api/src/main/java/com/ning/billing/util/entity/Entity.java b/api/src/main/java/com/ning/billing/util/entity/Entity.java
index 83b2151..f486dfd 100644
--- a/api/src/main/java/com/ning/billing/util/entity/Entity.java
+++ b/api/src/main/java/com/ning/billing/util/entity/Entity.java
@@ -22,9 +22,21 @@ import org.joda.time.DateTime;
 
 public interface Entity {
 
+    /**
+     *
+     * @return  the UUID of the object
+     */
     public UUID getId();
 
+    /**
+     *
+     * @return  the createdDate of that object
+     */
     public DateTime getCreatedDate();
 
+    /**
+     *
+     * @return  the last updatedDate of that object
+     */
     public DateTime getUpdatedDate();
 }

diff --git a/beatrix/src/test/java/com/ning/billing/beatrix/integration/overdue/TestOverdueIntegration.java b/beatrix/src/test/java/com/ning/billing/beatrix/integration/overdue/TestOverdueIntegration.java
index a08877d..4ce0c2f 100644
--- a/beatrix/src/test/java/com/ning/billing/beatrix/integration/overdue/TestOverdueIntegration.java
+++ b/beatrix/src/test/java/com/ning/billing/beatrix/integration/overdue/TestOverdueIntegration.java
@@ -198,7 +198,7 @@ public class TestOverdueIntegration extends TestOverdueBase {
         clock.setTime(new DateTime(2012, 5, 1, 0, 3, 42, 0));
 
         // Make sure the account doesn't have any payment method
-        accountUserApi.removePaymentMethod(account.getId(), callContext);
+        accountInternalApi.removePaymentMethod(account.getId(), internalCallContext);
 
         // Create subscription
         final Subscription baseSubscription = createSubscriptionAndCheckForCompletion(bundle.getId(), productName, ProductCategory.BASE, term, NextEvent.CREATE, NextEvent.INVOICE);

diff --git a/beatrix/src/test/java/com/ning/billing/beatrix/integration/TestIntegrationBase.java b/beatrix/src/test/java/com/ning/billing/beatrix/integration/TestIntegrationBase.java
index 3eaea42..bbd2e47 100644
--- a/beatrix/src/test/java/com/ning/billing/beatrix/integration/TestIntegrationBase.java
+++ b/beatrix/src/test/java/com/ning/billing/beatrix/integration/TestIntegrationBase.java
@@ -82,6 +82,7 @@ import com.ning.billing.payment.api.PaymentMethodPlugin;
 import com.ning.billing.payment.provider.MockPaymentProviderPlugin;
 import com.ning.billing.util.api.TagUserApi;
 import com.ning.billing.util.clock.ClockMock;
+import com.ning.billing.util.svcapi.account.AccountInternalApi;
 import com.ning.billing.util.svcsapi.bus.BusService;
 
 import com.google.common.base.Function;
@@ -173,10 +174,12 @@ public class TestIntegrationBase extends BeatrixTestSuiteWithEmbeddedDB implemen
     @Inject
     protected PaymentChecker paymentChecker;
 
-
     @Inject
     protected ExternalBus externalBus;
 
+    @Inject
+    protected AccountInternalApi accountInternalApi;
+
     protected TestApiListener busHandler;
 
     private boolean isListenerFailed;

diff --git a/junction/src/main/java/com/ning/billing/junction/plumbing/api/BlockingAccountUserApi.java b/junction/src/main/java/com/ning/billing/junction/plumbing/api/BlockingAccountUserApi.java
index c9a8171..3d8a7ab 100644
--- a/junction/src/main/java/com/ning/billing/junction/plumbing/api/BlockingAccountUserApi.java
+++ b/junction/src/main/java/com/ning/billing/junction/plumbing/api/BlockingAccountUserApi.java
@@ -101,11 +101,6 @@ public class BlockingAccountUserApi implements AccountUserApi {
     }
 
     @Override
-    public void saveEmails(final UUID accountId, final List<AccountEmail> emails, final CallContext context) {
-        userApi.saveEmails(accountId, emails, context);
-    }
-
-    @Override
     public void addEmail(final UUID accountId, final AccountEmail email, final CallContext context) {
         userApi.addEmail(accountId, email, context);
     }
@@ -114,14 +109,4 @@ public class BlockingAccountUserApi implements AccountUserApi {
     public void removeEmail(final UUID accountId, final AccountEmail email, final CallContext context) {
         userApi.removeEmail(accountId, email, context);
     }
-
-    @Override
-    public void updatePaymentMethod(final UUID accountId, final UUID paymentMethodId, CallContext context) throws AccountApiException {
-        userApi.updatePaymentMethod(accountId, paymentMethodId, context);
-    }
-
-    @Override
-    public void removePaymentMethod(final UUID accountId, final CallContext context) throws AccountApiException {
-        userApi.removePaymentMethod(accountId, context);
-    }
 }

diff --git a/util/src/main/java/com/ning/billing/util/events/AccountChangeInternalEvent.java b/util/src/main/java/com/ning/billing/util/events/AccountChangeInternalEvent.java
index b6458e3..ea3f5b6 100644
--- a/util/src/main/java/com/ning/billing/util/events/AccountChangeInternalEvent.java
+++ b/util/src/main/java/com/ning/billing/util/events/AccountChangeInternalEvent.java
@@ -19,8 +19,6 @@ package com.ning.billing.util.events;
 import java.util.List;
 import java.util.UUID;
 
-import com.ning.billing.account.api.ChangedField;
-
 public interface AccountChangeInternalEvent extends BusInternalEvent {
     public UUID getAccountId();
 

diff --git a/util/src/test/java/com/ning/billing/mock/api/MockAccountUserApi.java b/util/src/test/java/com/ning/billing/mock/api/MockAccountUserApi.java
index 8494212..17137c5 100644
--- a/util/src/test/java/com/ning/billing/mock/api/MockAccountUserApi.java
+++ b/util/src/test/java/com/ning/billing/mock/api/MockAccountUserApi.java
@@ -129,11 +129,6 @@ public class MockAccountUserApi implements AccountUserApi {
     }
 
     @Override
-    public void saveEmails(final UUID accountId, final List<AccountEmail> emails, final CallContext context) {
-        throw new UnsupportedOperationException();
-    }
-
-    @Override
     public void addEmail(final UUID accountId, final AccountEmail email, final CallContext context) {
         throw new UnsupportedOperationException();
     }
@@ -167,14 +162,4 @@ public class MockAccountUserApi implements AccountUserApi {
             throws AccountApiException {
         throw new UnsupportedOperationException();
     }
-
-    @Override
-    public void updatePaymentMethod(final UUID accountId, final UUID paymentMethodId, final CallContext context) throws AccountApiException {
-        throw new UnsupportedOperationException();
-    }
-
-    @Override
-    public void removePaymentMethod(final UUID accountId, final CallContext context) throws AccountApiException {
-        throw new UnsupportedOperationException();
-    }
 }