chore(core): Add missing docs and further cleanup

packages/core/src/entity/fulfillment/fulfillment.entity.ts

@@ -9,7 +9,7 @@ import { FulfillmentLine } from '../order-line-reference/fulfillment-line.entity
 
 /**
  * @description
- * This entity represents a fulfillment of an Order or part of it, i.e. the {@link OrderItem}s have been
+ * This entity represents a fulfillment of an Order or part of it, i.e. which {@link OrderLine}s have been
  * delivered to the Customer after successful payment.
  *
  * @docsCategory entities

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

@@ -1,195 +0,0 @@
-// import { Adjustment, AdjustmentType, TaxLine } from '@vendure/common/lib/generated-types';
-// import { DeepPartial, ID } from '@vendure/common/lib/shared-types';
-// import { summate } from '@vendure/common/lib/shared-utils';
-// import { Column, Entity, Index, JoinTable, ManyToMany, ManyToOne, OneToOne } from 'typeorm';
-//
-// import { Calculated } from '../../common/calculated-decorator';
-// import { grossPriceOf, netPriceOf } from '../../common/tax-utils';
-// import { VendureEntity } from '../base/base.entity';
-// import { EntityId } from '../entity-id.decorator';
-// import { Fulfillment } from '../fulfillment/fulfillment.entity';
-// import { OrderLine } from '../order-line/order-line.entity';
-// import { Refund } from '../refund/refund.entity';
-// import { Cancellation } from '../stock-movement/cancellation.entity';
-//
-// /**
-//  * @description
-//  * An individual item of an {@link OrderLine}.
-//  *
-//  * @docsCategory entities
-//  */
-// @Entity()
-// export class OrderItem extends VendureEntity {
-//     constructor(input?: DeepPartial<OrderItem>) {
-//         super(input);
-//     }
-//
-//     @Index()
-//     @ManyToOne(type => OrderLine)
-//     line: OrderLine;
-//
-//     @EntityId()
-//     lineId: ID; // TypeORM requires this ID field on the entity explicitly in order to save the foreign key via `.insert`
-//
-//     /**
-//      * @description
-//      * The price as calculated when the OrderItem was first added to the Order. Usually will be identical to the
-//      * `listPrice`, except when the ProductVariant price has changed in the mean time and a re-calculation of
-//      * the Order has been performed.
-//      */
-//     @Column({ nullable: true })
-//     initialListPrice: number;
-//
-//     /**
-//      * @description
-//      * This is the price as listed by the ProductVariant (and possibly modified by the {@link OrderItemPriceCalculationStrategy}),
-//      * which, depending on the current Channel, may or may not include tax.
-//      */
-//     @Column()
-//     listPrice: number;
-//
-//     /**
-//      * @description
-//      * Whether or not the listPrice includes tax, which depends on the settings
-//      * of the current Channel.
-//      */
-//     @Column()
-//     listPriceIncludesTax: boolean;
-//
-//     @Column('simple-json')
-//     adjustments: Adjustment[];
-//
-//     @Column('simple-json')
-//     taxLines: TaxLine[];
-//
-//     @ManyToMany(type => Fulfillment, fulfillment => fulfillment.orderItems)
-//     @JoinTable()
-//     fulfillments: Fulfillment[];
-//
-//     @Index()
-//     @ManyToOne(type => Refund)
-//     refund: Refund;
-//
-//     @EntityId({ nullable: true })
-//     refundId: ID | null;
-//
-//     @OneToOne(type => Cancellation, cancellation => cancellation.orderItem)
-//     cancellation: Cancellation;
-//
-//     @Column({ default: false })
-//     cancelled: boolean;
-//
-//     get fulfillment(): Fulfillment | undefined {
-//         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);
-//     }
-//
-//     /**
-//      * @description
-//      * The total applicable tax rate, which is the sum of all taxLines on this
-//      * OrderItem.
-//      */
-//     @Calculated()
-//     get taxRate(): number {
-//         return summate(this.taxLines, 'taxRate');
-//     }
-//
-//     @Calculated()
-//     get unitTax(): number {
-//         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();
-//         return this.listPriceIncludesTax ? result : grossPriceOf(result, this.taxRate);
-//     }
-//
-//     @Calculated()
-//     get proratedUnitTax(): number {
-//         return this.proratedUnitPriceWithTax - this.proratedUnitPrice;
-//     }
-//
-//     /**
-//      * @description
-//      * The total of all price adjustments. Will typically be a negative number due to discounts.
-//      */
-//     private getAdjustmentsTotal(type?: AdjustmentType): number {
-//         if (!this.adjustments) {
-//             return 0;
-//         }
-//         return this.adjustments
-//             .filter(adjustment => (type ? adjustment.type === type : true))
-//             .reduce((total, a) => total + a.amount, 0);
-//     }
-//
-//     addAdjustment(adjustment: Adjustment) {
-//         this.adjustments = this.adjustments.concat(adjustment);
-//     }
-//
-//     clearAdjustments(type?: AdjustmentType) {
-//         if (!type) {
-//             this.adjustments = [];
-//         } else {
-//             this.adjustments = this.adjustments ? this.adjustments.filter(a => a.type !== type) : [];
-//         }
-//     }
-// }

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

@@ -8,10 +8,10 @@ import { OrderLineReference } from './order-line-reference.entity';
 
 /**
  * @description
- * This entity represents a fulfillment of an Order or part of it, i.e. the {@link OrderItem}s have been
- * delivered to the Customer after successful payment.
+ * This entity represents a line from an {@link Order} which has been fulfilled by a {@link Fulfillment}.
  *
  * @docsCategory entities
+ * @docsPage OrderLineReference
  */
 @ChildEntity()
 export class FulfillmentLine extends OrderLineReference {

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

@@ -7,10 +7,10 @@ import { OrderLine } from '../order-line/order-line.entity';
 
 /**
  * @description
- * This entity represents a fulfillment of an Order or part of it, i.e. the {@link OrderItem}s have been
- * delivered to the Customer after successful payment.
+ * This is an abstract base class for entities which reference an {@link OrderLine}.
  *
  * @docsCategory entities
+ * @docsPage OrderLineReference
  */
 @Entity()
 @TableInheritance({ column: { type: 'varchar', name: 'discriminator' } })

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

@@ -8,10 +8,10 @@ import { OrderLineReference } from './order-line-reference.entity';
 
 /**
  * @description
- * This entity represents a fulfillment of an Order or part of it, i.e. the {@link OrderItem}s have been
- * delivered to the Customer after successful payment.
+ * This entity represents a line from an {@link Order} which has been modified by an {@link OrderModification}.
  *
  * @docsCategory entities
+ * @docsPage OrderLineReference
  */
 @ChildEntity()
 export class OrderModificationLine extends OrderLineReference {

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

@@ -8,10 +8,10 @@ import { OrderLineReference } from './order-line-reference.entity';
 
 /**
  * @description
- * This entity represents a fulfillment of an Order or part of it, i.e. the {@link OrderItem}s have been
- * delivered to the Customer after successful payment.
+ * This entity represents a line from an {@link Order} which has been refunded by a {@link Refund}.
  *
  * @docsCategory entities
+ * @docsPage OrderLineReference
  */
 @ChildEntity()
 export class RefundLine extends OrderLineReference {

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

@@ -19,7 +19,8 @@ import { TaxCategory } from '../tax-category/tax-category.entity';
 
 /**
  * @description
- * A single line on an {@link Order} which contains one or more {@link OrderItem}s.
+ * A single line on an {@link Order} which contains information about the {@link ProductVariant} and
+ * quantity ordered, as well as the price and tax information.
  *
  * @docsCategory entities
  */
@@ -29,12 +30,21 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
         super(input);
     }
 
+    /**
+     * @description
+     * The {@link Channel} of the {@link Seller} for a multivendor setup.
+     */
     @ManyToOne(type => Channel, { nullable: true, onDelete: 'SET NULL' })
     sellerChannel?: Channel;
 
     @EntityId({ nullable: true })
     sellerChannelId?: ID;
 
+    /**
+     * @description
+     * The {@link ShippingLine} to which this line has been assigned.
+     * This is determined by the configured {@link ShippingLineAssignmentStrategy}.
+     */
     @Index()
     @ManyToOne(type => ShippingLine, { nullable: true, onDelete: 'SET NULL' })
     shippingLine?: ShippingLine;
@@ -42,6 +52,10 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
     @EntityId({ nullable: true })
     shippingLineId?: ID;
 
+    /**
+     * @description
+     * The {@link ProductVariant} which is being ordered.
+     */
     @Index()
     @ManyToOne(type => ProductVariant)
     productVariant: ProductVariant;
@@ -57,9 +71,6 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
     @ManyToOne(type => Asset)
     featuredAsset: Asset;
 
-    // @OneToMany(type => OrderItem, item => item.line, { eager: true })
-    // items: OrderItem[];
-
     @Index()
     @ManyToOne(type => Order, order => order.lines, { onDelete: 'CASCADE' })
     order: Order;
@@ -76,8 +87,8 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
 
     /**
      * @description
-     * The price as calculated when the OrderItem was first added to the Order. Usually will be identical to the
-     * `listPrice`, except when the ProductVariant price has changed in the mean time and a re-calculation of
+     * The price as calculated when the OrderLine was first added to the Order. Usually will be identical to the
+     * `listPrice`, except when the ProductVariant price has changed in the meantime and a re-calculation of
      * the Order has been performed.
      */
     @Column({ nullable: true })
@@ -93,8 +104,7 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
 
     /**
      * @description
-     * Whether or not the listPrice includes tax, which depends on the settings
-     * of the current Channel.
+     * Whether the listPrice includes tax, which depends on the settings of the current Channel.
      */
     @Column()
     listPriceIncludesTax: boolean;
@@ -183,7 +193,7 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
     /**
      * @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
+     * Order-level discounts. This value is the true economic value of the a single unit in this OrderLine, and is used in tax
      * and refund calculations.
      */
     @Calculated()
@@ -200,11 +210,23 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
         return Math.round(this._proratedUnitPriceWithTax());
     }
 
+    /**
+     * @description
+     * Calculates the prorated unit price, excluding tax. This function performs no
+     * rounding, so before being exposed publicly via the GraphQL API, the returned value
+     * needs to be rounded to ensure it is an integer.
+     */
     private _proratedUnitPrice(): number {
         const result = this.listPrice + this.getAdjustmentsTotal();
         return this.listPriceIncludesTax ? netPriceOf(result, this.taxRate) : result;
     }
 
+    /**
+     * @description
+     * Calculates the prorated unit price, including tax. This function performs no
+     * rounding, so before being exposed publicly via the GraphQL API, the returned value
+     * needs to be rounded to ensure it is an integer.
+     */
     private _proratedUnitPriceWithTax(): number {
         const result = this.listPrice + this.getAdjustmentsTotal();
         return this.listPriceIncludesTax ? result : grossPriceOf(result, this.taxRate);
@@ -279,7 +301,7 @@ export class OrderLine extends VendureEntity implements HasCustomFields {
     get discounts(): Discount[] {
         const priceIncludesTax = this.listPriceIncludesTax;
         // Group discounts together, so that it does not list a new
-        // discount row for each OrderItem in the line
+        // discount row for each item in the line
         const groupedDiscounts = new Map<string, Discount>();
         for (const adjustment of this.adjustments) {
             const discountGroup = groupedDiscounts.get(adjustment.adjustmentSource);