/* Example of specification/documentation in an intermediate state
** of development.  (In the development snapshot moment here, 
** the spec is internally inconsistent)
** Illustrates the use of javadoc comment formats to develop the 
** specification and (parts of) the documentation.
*/


/**
 * Invariant:  
 * For each item, quantity in cart plus quantity recorded in database
 * equals total current inventory.
 * This is a single thread class.  Only one of the public functions 
 * may be active at a time. 
 *
 * @version 0.1
 * @author Joe Coder
 * @since 0.0
 */
public class Cart
{
 /**
  * Creates an empty cart for customer c.
  * @param c
  * (if customer objects have states in which carts cannot be created
  * for them, I would assert the precondition for an acceptable state here.
  * The reason for having the customer at all is just to filter out
  * demands for too many copies of an item.)
  * @see Customer
  */
  public Cart(Customer c)
  { /* ... */ }

  /**
   * Returns a sequence of the cart's contents.
   * @return 
   *   an enumeration object for traversing the entire cart contents 
   *   in alphabetical order by title.
   */
  public Enumeration contents()
  { /* ... */ }

  /**
   * @param quantity   
   *   This must be positive and below the customer's per item limit.
   * @param item  
   *   The item must be on our current stock list.
   * @return  
   *   True iff current available inventory of item is no less than quantity.
   *   <p>
   *   The specified quantity of item is removed from the central DB
   *   and added to this cart.
   */
  public boolean addToCart(Object item, int quantity)
  { /* ... */ }

  /**
   *  If any quantity of the item is in the cart, it is removed and returned 
   *  to the main DB.
   */
  public void removeFromCart(Object item)
  { /* ... */ }

  /**
   * @return  
   *   The sum of the prices of all of the items in the cart.
   */
  /// Returns the sum of the prices of all of the items in the cart.
  public int totalPrice()
  { /* ... */ }

} // class Cart