/**
 * Returns the price after applying a percentage discount.     <- summary sentence
 * <p>
 * The discount is applied before tax. Prices are not rounded.  <- more description
 *
 * @param price    the original price; must not be negative     <- block tags
 * @param percent  the discount, from 0 to 100
 * @return the discounted price
 * @throws IllegalArgumentException if price is negative or percent is out of range
 */
public static double applyDiscount(double price, double percent) { ... }

//PriceCalculator.java
import java.util.List;

/**
 * Utility methods for calculating order prices.
 * <p>
 * All amounts are in the shop's currency, as {@code double} values. For exact
 * money calculations, see {@link java.math.BigDecimal}.
 *
 * @since 1.0
 */
public final class PriceCalculator {

  /** The tax rate applied by {@link #withTax(double)}, as a fraction (0.18 means 18%). */
  public static final double TAX_RATE = 0.18;

  private PriceCalculator() {
  }

  /**
   * Returns the price after applying a percentage discount.
   *
   * @param price   the original price; must not be negative
   * @param percent the discount, from 0 to 100
   * @return the discounted price
   * @throws IllegalArgumentException if {@code price} is negative or {@code percent} is outside 0 to 100
   */
  public static double applyDiscount(double price, double percent) {
    if (price < 0 || percent < 0 || percent > 100) {
      throw new IllegalArgumentException("Invalid price " + price + " or percent " + percent);
    }
    return price * (100 - percent) / 100;
  }

  /**
   * Adds tax to a price, using {@link #TAX_RATE}.
   *
   * @param price the price before tax
   * @return the price including tax
   */
  public static double withTax(double price) {
    return price * (1 + TAX_RATE);
  }

  /**
   * Returns the sum of a list of prices.
   * {@snippet :
   * double total = PriceCalculator.total(List.of(9.99, 5.0)); // 14.99
   * }
   *
   * @param prices the prices to add; an empty list gives 0
   * @return the total of all prices
   * @see #withTax(double)
   */
  public static double total(List<Double> prices) {
    double sum = 0;
    for (double p : prices) {
      sum += p;
    }
    return sum;
  }

  /**
   * Prints two example calculations.
   *
   * @param args not used
   */
  public static void main(String[] args) {
    System.out.println(withTax(applyDiscount(100, 10)));
    System.out.println(total(List.of(9.99, 5.0)));
  }
}

//Inventory.java
/**
 * Tracks stock levels.
 */
public class Inventory {
  private int stock;

  /** Creates an empty inventory. */
  public Inventory() {
  }

  /**
   * Adds items to the stock.
   *
   * @return the new stock level
   */
  public int add(int quantity) {
    stock += quantity;
    return stock;
  }

  public int stock() {
    return stock;
  }
}