docs(core): Better docs on TS Order entities

Fixes #1165

packages/core/src/api/schema/common/order.type.graphql

@@ -130,7 +130,7 @@ type OrderItem implements Node {
     "The price of a single unit including discounts and tax"
     discountedUnitPriceWithTax: Int!
     """
-    The actual unit price, taking into account both item discounts _and_ prorated (proportially-distributed)
+    The actual unit price, taking into account both item discounts _and_ prorated (proportionally-distributed)
     Order-level discounts. This value is the true economic value of the OrderItem, and is used in tax
     and refund calculations.
     """
@@ -175,7 +175,7 @@ type OrderLine implements Node {
     "The price of a single unit including discounts and tax"
     discountedUnitPriceWithTax: Int!
     """
-    The actual unit price, taking into account both item discounts _and_ prorated (proportially-distributed)
+    The actual unit price, taking into account both item discounts _and_ prorated (proportionally-distributed)
     Order-level discounts. This value is the true economic value of the OrderItem, and is used in tax
     and refund calculations.
     """
@@ -190,7 +190,7 @@ type OrderLine implements Node {
     """
     linePrice: Int!
     """
-    The total price of the line including tax bit excluding discounts.
+    The total price of the line including tax but excluding discounts.
     """
     linePriceWithTax: Int!
     "The price of the line including discounts, excluding tax"
@@ -198,7 +198,7 @@ type OrderLine implements Node {
     "The price of the line including discounts and tax"
     discountedLinePriceWithTax: Int!
     """
-    The actual line price, taking into account both item discounts _and_ prorated (proportially-distributed)
+    The actual line price, taking into account both item discounts _and_ prorated (proportionally-distributed)
     Order-level discounts. This value is the true economic value of the OrderLine, and is used in tax
     and refund calculations.
     """

packages/core/src/entity/order-item/order-item.entity.ts

@@ -81,11 +81,19 @@ export class OrderItem extends VendureEntity {
         return this.fulfillments?.find(f => f.state !== 'Cancelled');
     }
 
+    /**
+     * @description
+     * The price of a single unit, excluding tax and discounts.
+     */
     @Calculated()
     get unitPrice(): number {
         return this.listPriceIncludesTax ? netPriceOf(this.listPrice, this.taxRate) : this.listPrice;
     }
 
+    /**
+     * @description
+     * The price of a single unit, including tax but excluding discounts.
+     */
     @Calculated()
     get unitPriceWithTax(): number {
         return this.listPriceIncludesTax ? this.listPrice : grossPriceOf(this.listPrice, this.taxRate);
@@ -106,24 +114,47 @@ export class OrderItem extends VendureEntity {
         return this.unitPriceWithTax - this.unitPrice;
     }
 
+    /**
+     * @description
+     * The price of a single unit including discounts, excluding tax.
+     *
+     * If Order-level discounts have been applied, this will not be the
+     * actual taxable unit price (see `proratedUnitPrice`), but is generally the
+     * correct price to display to customers to avoid confusion
+     * about the internal handling of distributed Order-level discounts.
+     */
     @Calculated()
     get discountedUnitPrice(): number {
         const result = this.listPrice + this.getAdjustmentsTotal(AdjustmentType.PROMOTION);
         return this.listPriceIncludesTax ? netPriceOf(result, this.taxRate) : result;
     }
 
+    /**
+     * @description
+     * The price of a single unit including discounts and tax.
+     */
     @Calculated()
     get discountedUnitPriceWithTax(): number {
         const result = this.listPrice + this.getAdjustmentsTotal(AdjustmentType.PROMOTION);
         return this.listPriceIncludesTax ? result : grossPriceOf(result, this.taxRate);
     }
 
+    /**
+     * @description
+     * The actual unit price, taking into account both item discounts _and_ prorated (proportionally-distributed)
+     * Order-level discounts. This value is the true economic value of the OrderItem, and is used in tax
+     * and refund calculations.
+     */
     @Calculated()
     get proratedUnitPrice(): number {
         const result = this.listPrice + this.getAdjustmentsTotal();
         return this.listPriceIncludesTax ? netPriceOf(result, this.taxRate) : result;
     }
 
+    /**
+     * @description
+     * The `proratedUnitPrice` including tax.
+     */
     @Calculated()
     get proratedUnitPriceWithTax(): number {
         const result = this.listPrice + this.getAdjustmentsTotal();

packages/core/src/entity/order-line/order-line.entity.ts

@@ -44,16 +44,28 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
     @Column(type => CustomOrderLineFields)
     customFields: CustomOrderLineFields;
 
+    /**
+     * @description
+     * The price of a single unit, excluding tax and discounts.
+     */
     @Calculated()
     get unitPrice(): number {
         return this.firstActiveItemPropOr('unitPrice', 0);
     }
 
+    /**
+     * @description
+     * The price of a single unit, including tax but excluding discounts.
+     */
     @Calculated()
     get unitPriceWithTax(): number {
         return this.firstActiveItemPropOr('unitPriceWithTax', 0);
     }
 
+    /**
+     * @description
+     * Non-zero if the `unitPrice` has changed since it was initially added to Order.
+     */
     @Calculated()
     get unitPriceChangeSinceAdded(): number {
         const firstItem = this.activeItems[0];
@@ -67,6 +79,10 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
         return this.unitPrice - initialPrice;
     }
 
+    /**
+     * @description
+     * Non-zero if the `unitPriceWithTax` has changed since it was initially added to Order.
+     */
     @Calculated()
     get unitPriceWithTaxChangeSinceAdded(): number {
         const firstItem = this.activeItems[0];
@@ -80,21 +96,44 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
         return this.unitPriceWithTax - initialPriceWithTax;
     }
 
+    /**
+     * @description
+     * The price of a single unit including discounts, excluding tax.
+     *
+     * If Order-level discounts have been applied, this will not be the
+     * actual taxable unit price (see `proratedUnitPrice`), but is generally the
+     * correct price to display to customers to avoid confusion
+     * about the internal handling of distributed Order-level discounts.
+     */
     @Calculated()
     get discountedUnitPrice(): number {
         return this.firstActiveItemPropOr('discountedUnitPrice', 0);
     }
 
+    /**
+     * @description
+     * The price of a single unit including discounts and tax
+     */
     @Calculated()
     get discountedUnitPriceWithTax(): number {
         return this.firstActiveItemPropOr('discountedUnitPriceWithTax', 0);
     }
 
+    /**
+     * @description
+     * The actual unit price, taking into account both item discounts _and_ prorated (proportionally-distributed)
+     * Order-level discounts. This value is the true economic value of the OrderItem, and is used in tax
+     * and refund calculations.
+     */
     @Calculated()
     get proratedUnitPrice(): number {
         return this.firstActiveItemPropOr('proratedUnitPrice', 0);
     }
 
+    /**
+     * @description
+     * The `proratedUnitPrice` including tax.
+     */
     @Calculated()
     get proratedUnitPriceWithTax(): number {
         return this.firstActiveItemPropOr('proratedUnitPriceWithTax', 0);
@@ -123,21 +162,37 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
         return this.firstActiveItemPropOr('taxRate', 0);
     }
 
+    /**
+     * @description
+     * The total price of the line excluding tax and discounts.
+     */
     @Calculated()
     get linePrice(): number {
         return summate(this.activeItems, 'unitPrice');
     }
 
+    /**
+     * @description
+     * The total price of the line including tax but excluding discounts.
+     */
     @Calculated()
     get linePriceWithTax(): number {
         return summate(this.activeItems, 'unitPriceWithTax');
     }
 
+    /**
+     * @description
+     * The price of the line including discounts, excluding tax.
+     */
     @Calculated()
     get discountedLinePrice(): number {
         return summate(this.activeItems, 'discountedUnitPrice');
     }
 
+    /**
+     * @description
+     * The price of the line including discounts and tax.
+     */
     @Calculated()
     get discountedLinePriceWithTax(): number {
         return summate(this.activeItems, 'discountedUnitPriceWithTax');
@@ -169,16 +224,30 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
         return [...groupedDiscounts.values()];
     }
 
+    /**
+     * @description
+     * The total tax on this line.
+     */
     @Calculated()
     get lineTax(): number {
         return summate(this.activeItems, 'unitTax');
     }
 
+    /**
+     * @description
+     * The actual line price, taking into account both item discounts _and_ prorated (proportionally-distributed)
+     * Order-level discounts. This value is the true economic value of the OrderLine, and is used in tax
+     * and refund calculations.
+     */
     @Calculated()
     get proratedLinePrice(): number {
         return summate(this.activeItems, 'proratedUnitPrice');
     }
 
+    /**
+     * @description
+     * The `proratedLinePrice` including tax.
+     */
     @Calculated()
     get proratedLinePriceWithTax(): number {
         return summate(this.activeItems, 'proratedUnitPriceWithTax');

packages/core/src/entity/order/order.entity.ts

@@ -44,13 +44,32 @@ export class Order extends VendureEntity implements ChannelAware, HasCustomField
         super(input);
     }
 
+    /**
+     * @description
+     * A unique code for the Order, generated according to the
+     * {@link OrderCodeStrategy}. This should be used as an order reference
+     * for Customers, rather than the Order's id.
+     */
     @Column() code: string;
 
     @Column('varchar') state: OrderState;
 
+    /**
+     * @description
+     * Whether the Order is considered "active", meaning that the
+     * Customer can still make changes to it and has not yet completed
+     * the checkout process.
+     * This is governed by the {@link OrderPlacedStrategy}.
+     */
     @Column({ default: true })
     active: boolean;
 
+    /**
+     * @description
+     * The date & time that the Order was placed, i.e. the Customer
+     * completed the checkout and the Order is no longer "active".
+     * This is governed by the {@link OrderPlacedStrategy}.
+     */
     @Column({ nullable: true })
     orderPlacedAt?: Date;
 
@@ -60,12 +79,28 @@ export class Order extends VendureEntity implements ChannelAware, HasCustomField
     @OneToMany(type => OrderLine, line => line.order)
     lines: OrderLine[];
 
+    /**
+     * @description
+     * Surcharges are arbitrary modifications to the Order total which are neither
+     * ProductVariants nor discounts resulting from applied Promotions. For example,
+     * one-off discounts based on customer interaction, or surcharges based on payment
+     * methods.
+     */
     @OneToMany(type => Surcharge, surcharge => surcharge.order)
     surcharges: Surcharge[];
 
+    /**
+     * @description
+     * An array of all coupon codes applied to the Order.
+     */
     @Column('simple-array')
     couponCodes: string[];
 
+    /**
+     * @description
+     * Promotions applied to the order. Only gets populated after the payment process has completed,
+     * i.e. the Order is no longer active.
+     */
     @ManyToMany(type => Promotion)
     @JoinTable()
     promotions: Promotion[];
@@ -93,15 +128,34 @@ export class Order extends VendureEntity implements ChannelAware, HasCustomField
     @OneToMany(type => OrderModification, modification => modification.order)
     modifications: OrderModification[];
 
+    /**
+     * @description
+     * The subTotal is the total of all OrderLines in the Order. This figure also includes any Order-level
+     * discounts which have been prorated (proportionally distributed) amongst the OrderItems.
+     * To get a total of all OrderLines which does not account for prorated discounts, use the
+     * sum of {@link OrderLine}'s `discountedLinePrice` values.
+     */
     @Column()
     subTotal: number;
 
+    /**
+     * @description
+     * Same as subTotal, but inclusive of tax.
+     */
     @Column()
     subTotalWithTax: number;
 
+    /**
+     * @description
+     * The shipping charges applied to this order.
+     */
     @OneToMany(type => ShippingLine, shippingLine => shippingLine.order)
     shippingLines: ShippingLine[];
 
+    /**
+     * @description
+     * The total of all the `shippingLines`.
+     */
     @Column({ default: 0 })
     shipping: number;
 
@@ -136,6 +190,10 @@ export class Order extends VendureEntity implements ChannelAware, HasCustomField
         return [...groupedAdjustments.values()];
     }
 
+    /**
+     * @description
+     * Equal to `subTotal` plus `shipping`
+     */
     @Calculated({
         query: qb =>
             qb
@@ -156,6 +214,10 @@ export class Order extends VendureEntity implements ChannelAware, HasCustomField
         return this.subTotal + (this.shipping || 0);
     }
 
+    /**
+     * @description
+     * The final payable amount. Equal to `subTotalWithTax` plus `shippingWithTax`.
+     */
     @Calculated({
         query: qb =>
             qb
@@ -198,6 +260,10 @@ export class Order extends VendureEntity implements ChannelAware, HasCustomField
         return summate(this.lines, 'quantity');
     }
 
+    /**
+     * @description
+     * A summary of the taxes being applied to this Order.
+     */
     @Calculated()
     get taxSummary(): OrderTaxSummary[] {
         const taxRateMap = new Map<