How to Make Cursor Add Code Comments

1/**
2 * Calculates the total price for an order including all line items.
3 *
4 * @param order - The order containing items with prices and quantities
5 * @returns The total price in cents as an integer
6 * @throws {Error} If any item has a negative price
7 * @example
8 * ```typescript
9 * const total = calculateOrderTotal({
10 *   items: [
11 *     { name: 'Widget', priceCents: 1000, quantity: 2 },
12 *     { name: 'Gadget', priceCents: 2500, quantity: 1 },
13 *   ],
14 * });
15 * console.log(total); // 4500
16 * ```
17 */
18export function calculateOrderTotal(order: Order): number {
19  return order.items.reduce((sum, item) => {
20    if (item.priceCents < 0) {
21      throw new Error(`Invalid price for item: ${item.name}`);
22    }
23    return sum + item.priceCents * item.quantity;
24  }, 0);
25}
26
27/**
28 * Applies a discount to a subtotal amount.
29 *
30 * @param subtotalCents - The original amount in cents
31 * @param discount - The discount to apply (percentage or fixed amount)
32 * @returns The discounted amount in cents, minimum 0
33 * @example
34 * ```typescript
35 * const discounted = applyDiscount(10000, { type: 'percent', value: 10 });
36 * console.log(discounted); // 9000
37 * ```
38 * @see calculateOrderTotal
39 */
40export function applyDiscount(
41  subtotalCents: number,
42  discount: Discount
43): number {
44  const reduction =
45    discount.type === 'percent'
46      ? Math.floor(subtotalCents * (Math.min(discount.value, 100) / 100))
47      : discount.value;
48
49  return Math.max(0, subtotalCents - reduction);
50}
51
52/** Order containing line items for price calculation. */
53export interface Order {
54  items: OrderItem[];
55}
56
57/** A single line item in an order. */
58export interface OrderItem {
59  name: string;
60  priceCents: number;
61  quantity: number;
62}
63
64/** Discount that can be applied to an order subtotal. */
65export interface Discount {
66  type: 'percent' | 'fixed';
67  value: number;
68}