feat(docs): Clean up various docs

Relates to #89

packages/admin-ui-plugin/src/plugin.ts

@@ -77,6 +77,7 @@ export class AdminUiPlugin implements VendurePlugin {
     private server: Server;
     constructor(private options: AdminUiOptions) {}
 
+    /** @internal */
     async configure(config: Required<VendureConfig>): Promise<Required<VendureConfig>> {
         const route = 'admin';
         config.middleware.push({
@@ -89,6 +90,7 @@ export class AdminUiPlugin implements VendurePlugin {
         return config;
     }
 
+    /** @internal */
     onBootstrap(inject: InjectorFn): void | Promise<void> {
         const adminUiPath = this.getAdminUiPath();
         const assetServer = express();
@@ -99,6 +101,7 @@ export class AdminUiPlugin implements VendurePlugin {
         this.server = assetServer.listen(this.options.port);
     }
 
+    /** @internal */
     onClose(): Promise<void> {
         return new Promise(resolve => this.server.close(() => resolve()));
     }

packages/asset-server-plugin/src/plugin.ts

@@ -192,6 +192,7 @@ export class AssetServerPlugin implements VendurePlugin {
         }
     }
 
+    /** @internal */
     configure(config: Required<VendureConfig>) {
         this.assetStorage = this.createAssetStorageStrategy();
         config.assetOptions.assetPreviewStrategy = new SharpAssetPreviewStrategy({
@@ -206,10 +207,12 @@ export class AssetServerPlugin implements VendurePlugin {
         return config;
     }
 
+    /** @internal */
     onBootstrap(inject: InjectorFn): void | Promise<void> {
         this.createAssetServer();
     }
 
+    /** @internal */
     onClose(): Promise<void> {
         return new Promise(resolve => {
             this.server.close(() => resolve());

packages/core/src/api/common/request-context.ts

@@ -9,8 +9,12 @@ import { Session } from '../../entity/session/session.entity';
 import { User } from '../../entity/user/user.entity';
 
 /**
- * The RequestContext is intended to hold information relevant to the current request, which may be
+ * @description
+ * The RequestContext holds information relevant to the current request, which may be
  * required at various points of the stack.
+ *
+ * @docsCategory
+ * @docsWeight 1
  */
 export class RequestContext {
     private readonly _languageCode: LanguageCode;
@@ -20,6 +24,9 @@ export class RequestContext {
     private readonly _authorizedAsOwnerOnly: boolean;
     private readonly _translationFn: i18next.TranslationFunction;
 
+    /**
+     * @internal
+     */
     constructor(options: {
         channel: Channel;
         session?: Session;
@@ -85,6 +92,7 @@ export class RequestContext {
     }
 
     /**
+     * @description
      * Translate the given i18n key
      */
     translate(key: string, variables?: { [k: string]: any }): string {

packages/core/src/config/config.service.mock.ts

@@ -34,6 +34,7 @@ export class MockConfigService implements MockClass<ConfigService> {
     orderOptions = {};
     customFields = {};
     middleware = [];
+    logger = {} as any;
     plugins = [];
 }
 

packages/core/src/config/logger/default-logger.ts

@@ -23,6 +23,7 @@ const DEFAULT_CONTEXT = 'Vendure Server';
  * @docsCategory Logger
  */
 export class DefaultLogger implements VendureLogger {
+    /** @internal */
     level: LogLevel = LogLevel.Info;
     private readonly timestamp: boolean;
     private readonly localeStringOptions = {
@@ -45,6 +46,7 @@ export class DefaultLogger implements VendureLogger {
      * To be run directly before the `NestFactory.create()` call in the `bootstrap()` function.
      *
      * See https://github.com/nestjs/nest/issues/1838
+     * @internal
      */
     static hideNestBoostrapLogs(): void {
         const { logger } = Logger;
@@ -63,6 +65,7 @@ export class DefaultLogger implements VendureLogger {
      * `bootstrap()` function.
      *
      * See https://github.com/nestjs/nest/issues/1838
+     * @internal
      */
     static restoreOriginalLogLevel(): void {
         const { logger } = Logger;

packages/core/src/config/logger/vendure-logger.ts

@@ -7,6 +7,10 @@ import { LoggerService } from '@nestjs/common';
  * @docsCategory Logger
  */
 export enum LogLevel {
+    /**
+     * @description
+     * Log Errors only.
+     */
     Error = 0,
     Warn = 1,
     Info = 2,
@@ -77,16 +81,16 @@ const noopLogger: VendureLogger = {
  *         this.logfile.write(`ERROR: [${context}] ${message}\n`);
  *     }
  *     warn(message: string, context?: string) {
- *          this.logfile.write(`WARN: [${context}] ${message}\n`);
+ *         this.logfile.write(`WARN: [${context}] ${message}\n`);
  *     }
  *     info(message: string, context?: string) {
- *          this.logfile.write(`INFO: [${context}] ${message}\n`);
+ *         this.logfile.write(`INFO: [${context}] ${message}\n`);
  *     }
  *     verbose(message: string, context?: string) {
- *          this.logfile.write(`VERBOSE: [${context}] ${message}\n`);
+ *         this.logfile.write(`VERBOSE: [${context}] ${message}\n`);
  *     }
  *     debug(message: string, context?: string) {
- *          this.logfile.write(`DEBUG: [${context}] ${message}\n`);
+ *         this.logfile.write(`DEBUG: [${context}] ${message}\n`);
  *     }
  * }
  *
@@ -112,47 +116,53 @@ export class Logger implements LoggerService {
         return _instance;
     }
 
+    /** @internal */
     static useLogger(logger: VendureLogger) {
         Logger._logger = logger;
     }
 
+    /** @internal */
     error(message: any, trace?: string, context?: string): any {
         this.instance.error(message, context, trace);
     }
 
+    /** @internal */
     warn(message: any, context?: string): any {
         this.instance.warn(message, context);
     }
 
+    /** @internal */
     log(message: any, context?: string): any {
         this.instance.info(message, context);
     }
 
+    /** @internal */
     verbose(message: any, context?: string): any {
         this.instance.verbose(message, context);
     }
 
+    /** @internal */
     debug(message: any, context?: string): any {
         this.instance.debug(message, context);
     }
 
-    static error(message: string, context?: string, trace?: string) {
+    static error(message: string, context?: string, trace?: string): void {
         Logger.logger.error(message, context, trace);
     }
 
-    static warn(message: string, context?: string) {
+    static warn(message: string, context?: string): void {
         Logger.logger.warn(message, context);
     }
 
-    static info(message: string, context?: string) {
+    static info(message: string, context?: string): void {
         Logger.logger.info(message, context);
     }
 
-    static verbose(message: string, context?: string) {
+    static verbose(message: string, context?: string): void {
         Logger.logger.verbose(message, context);
     }
 
-    static debug(message: string, context?: string) {
+    static debug(message: string, context?: string): void {
         Logger.logger.debug(message, context);
     }
 }

packages/core/src/config/payment-method/payment-method-handler.ts

@@ -18,6 +18,17 @@ export type PaymentMethodArgType = ConfigArgType.INT | ConfigArgType.STRING | Co
 export type PaymentMethodArgs = ConfigArgs<PaymentMethodArgType>;
 export type OnTransitionStartReturnType = ReturnType<Required<StateMachineConfig<any>>['onTransitionStart']>;
 
+/**
+ * @description
+ * The signature of the function defined by `onStateTransitionStart` in {@link PaymentMethodConfigOptions}.
+ *
+ * This function is called before the state of a Payment is transitioned. Its
+ * return value used to determine whether the transition can occur.
+ *
+ * TODO: This is currently not called by Vendure. Needs to be implemented.
+ *
+ * @docsCategory payment
+ */
 export type OnTransitionStartFn<T extends PaymentMethodArgs> = (
     fromState: PaymentState,
     toState: PaymentState,
@@ -144,8 +155,11 @@ export interface PaymentMethodConfigOptions<T extends PaymentMethodArgs = Paymen
  */
 export class PaymentMethodHandler<T extends PaymentMethodArgs = PaymentMethodArgs>
     implements ConfigurableOperationDef {
+    /** @internal */
     readonly code: string;
+    /** @internal */
     readonly description: string;
+    /** @internal */
     readonly args: T;
     private readonly createPaymentFn: CreatePaymentFn<T>;
     private readonly onTransitionStartFn?: OnTransitionStartFn<T>;
@@ -161,6 +175,8 @@ export class PaymentMethodHandler<T extends PaymentMethodArgs = PaymentMethodArg
     /**
      * @description
      * Called internally to create a new Payment
+     *
+     * @internal
      */
     async createPayment(order: Order, args: ConfigArg[], metadata: PaymentMetadata) {
         const paymentConfig = await this.createPaymentFn(order, argsArrayToHash(args), metadata);
@@ -176,7 +192,7 @@ export class PaymentMethodHandler<T extends PaymentMethodArgs = PaymentMethodArg
      * was instantiated with a `onStateTransitionStart` function, that function will be invoked and its
      * return value used to determine whether the transition can occur.
      *
-     * @docsCategory payment
+     * @internal
      */
     onStateTransitionStart(
         fromState: PaymentState,

packages/core/src/config/promotion/promotion-action.ts

@@ -91,6 +91,7 @@ export class PromotionItemAction<T extends PromotionActionArgs = {}> extends Pro
         this.executeFn = config.execute;
     }
 
+    /** @internal */
     execute(orderItem: OrderItem, orderLine: OrderLine, args: ConfigArg[], utils: PromotionUtils) {
         return this.executeFn(orderItem, orderLine, argsArrayToHash(args), utils);
     }
@@ -122,6 +123,7 @@ export class PromotionOrderAction<T extends PromotionActionArgs = {}> extends Pr
         this.executeFn = config.execute;
     }
 
+    /** @internal */
     execute(order: Order, args: ConfigArg[], utils: PromotionUtils) {
         return this.executeFn(order, argsArrayToHash(args), utils);
     }

packages/core/src/config/shipping-method/default-shipping-eligibility-checker.ts

@@ -1,8 +1,13 @@
+import { ConfigArgType } from '../../../../common/lib/generated-types';
 import { ShippingEligibilityChecker } from './shipping-eligibility-checker';
 
 export const defaultShippingEligibilityChecker = new ShippingEligibilityChecker({
     code: 'default-shipping-eligibility-checker',
     description: 'Default Shipping Eligibility Checker',
-    args: {},
-    check: order => true,
+    args: {
+        orderMinimum: ConfigArgType.MONEY,
+    },
+    check: (order, args) => {
+        return order.total >= args.orderMinimum;
+    },
 });

packages/core/src/config/shipping-method/shipping-calculator.ts

@@ -10,6 +10,14 @@ export type ShippingCalculatorArgType =
     | ConfigArgType.STRING
     | ConfigArgType.BOOLEAN;
 export type ShippingCalculatorArgs = ConfigArgs<ShippingCalculatorArgType>;
+
+/**
+ * @description
+ * A function which implements the specific shipping calculation logic. It takes an {@link Order} and
+ * an arguments object and should return the shipping price as an integer in cents.
+ *
+ * @docsCategory shipping
+ */
 export type CalculateShippingFn<T extends ShippingCalculatorArgs> = (
     order: Order,
     args: ConfigArgValues<T>,
@@ -19,11 +27,28 @@ export type CalculateShippingFn<T extends ShippingCalculatorArgs> = (
  * @description
  * The ShippingCalculator is used by a {@link ShippingMethod} to calculate the price of shipping on a given {@link Order}.
  *
+ * @example
+ * ```ts
+ * const flatRateCalculator = new ShippingCalculator({
+ *     code: 'flat-rate-calculator',
+ *     description: 'Default Flat-Rate Shipping Calculator',
+ *     args: {
+ *         rate: ConfigArgType.MONEY,
+ *     },
+ *     calculate: (order, args) => {
+ *         return args.rate;
+ *     },
+ * });
+ * ```
+ *
  * @docsCategory shipping
  */
 export class ShippingCalculator<T extends ShippingCalculatorArgs = {}> implements ConfigurableOperationDef {
+    /** @internal */
     readonly code: string;
+    /** @internal */
     readonly description: string;
+    /** @internal */
     readonly args: ShippingCalculatorArgs;
     private readonly calculateFn: CalculateShippingFn<T>;
 
@@ -37,6 +62,8 @@ export class ShippingCalculator<T extends ShippingCalculatorArgs = {}> implement
     /**
      * @description
      * Calculates the price of shipping for the given Order.
+     *
+     * @internal
      */
     calculate(order: Order, args: ConfigArg[]): number | Promise<number> {
         return this.calculateFn(order, argsArrayToHash(args));

packages/core/src/config/shipping-method/shipping-eligibility-checker.ts

@@ -10,6 +10,14 @@ export type ShippingEligibilityCheckerArgType =
     | ConfigArgType.STRING
     | ConfigArgType.BOOLEAN;
 export type ShippingEligibilityCheckerArgs = ConfigArgs<ShippingEligibilityCheckerArgType>;
+
+/**
+ * @description
+ * A function which implements logic to determine whether a given {@link Order} is eligible for
+ * a particular shipping method.
+ *
+ * @docsCategory shipping
+ */
 export type CheckShippingEligibilityCheckerFn<T extends ShippingEligibilityCheckerArgs> = (
     order: Order,
     args: ConfigArgValues<T>,
@@ -20,12 +28,29 @@ export type CheckShippingEligibilityCheckerFn<T extends ShippingEligibilityCheck
  * The ShippingEligibilityChecker class is used to check whether an order qualifies for a
  * given {@link ShippingMethod}.
  *
+ * @example
+ * ```ts
+ * const minOrderTotalEligibilityChecker = new ShippingEligibilityChecker({
+ *     code: 'min-order-total-eligibility-checker',
+ *     description: 'Checks that the order total is above some minimum value',
+ *     args: {
+ *         orderMinimum: ConfigArgType.MONEY,
+ *     },
+ *     check: (order, args) => {
+ *         return order.total >= args.orderMinimum;
+ *     },
+ * });
+ * ```
+ *
  * @docsCategory shipping
  */
 export class ShippingEligibilityChecker<T extends ShippingEligibilityCheckerArgs = {}>
     implements ConfigurableOperationDef {
+    /** @internal */
     readonly code: string;
+    /** @internal */
     readonly description: string;
+    /** @internal */
     readonly args: ShippingEligibilityCheckerArgs;
     private readonly checkFn: CheckShippingEligibilityCheckerFn<T>;
 
@@ -44,6 +69,8 @@ export class ShippingEligibilityChecker<T extends ShippingEligibilityCheckerArgs
     /**
      * @description
      * Check the given Order to determine whether it is eligible.
+     *
+     * @internal
      */
     check(order: Order, args: ConfigArg[]): boolean | Promise<boolean> {
         return this.checkFn(order, argsArrayToHash(args));

packages/core/src/plugin/plugin-utils.ts

@@ -1,11 +1,12 @@
 import { notNullOrUndefined } from '@vendure/common/lib/shared-utils';
+import { RequestHandler } from 'express';
 import proxy from 'http-proxy-middleware';
 
 import { APIExtensionDefinition, Logger, VendureConfig, VendurePlugin } from '../config';
 
 /**
  * @description
- * Options to configure the proxy middleware.
+ * Options to configure proxy middleware via {@link createProxyHandler}.
  *
  * @docsCategory Plugin
  */
@@ -41,9 +42,28 @@ export interface ProxyOptions {
  * Useful for plugins which start their own servers but should be accessible
  * via the main Vendure url.
  *
+ * @example
+ * ```ts
+ * // Example usage in the `configure` method of a VendurePlugin.
+ * // Imagine that we have started a Node server on port 5678
+ * // running some service which we want to access via the `/my-plugin/`
+ * // route of the main Vendure server.
+ * configure(config: Required<VendureConfig>): Required<VendureConfig> {
+ *     config.middleware.push({
+ *         handler: createProxyHandler({
+ *             label: 'Admin UI',
+ *             route: 'my-plugin',
+ *             port: 5678,
+ *         }),
+ *         route: 'my-plugin',
+ *     });
+ *     return config;
+ * }
+ * ```
+ *
  * @docsCategory Plugin
  */
-export function createProxyHandler(options: ProxyOptions) {
+export function createProxyHandler(options: ProxyOptions): RequestHandler {
     const route = options.route.charAt(0) === '/' ? options.route : '/' + options.route;
     const proxyHostname = options.hostname || 'localhost';
     const middleware = proxy({

packages/email-plugin/src/event-listener.ts

@@ -173,6 +173,8 @@ export class EmailEventHandler<T extends string = string, Event extends EventWit
     /**
      * @description
      * Used internally by the EmailPlugin to handle incoming events.
+     *
+     * @internal
      */
     handle(
         event: Event,

packages/email-plugin/src/plugin.ts

@@ -143,6 +143,7 @@ export class EmailPlugin implements VendurePlugin {
         }
     }
 
+    /** @internal */
     configure(config: Required<VendureConfig>): Required<VendureConfig> | Promise<Required<VendureConfig>> {
         if (isDevModeOptions(this.options) && this.options.mailboxPort !== undefined) {
             this.devMailbox = new DevMailbox();
@@ -157,6 +158,7 @@ export class EmailPlugin implements VendurePlugin {
         return config;
     }
 
+    /** @internal */
     async onBootstrap(inject: <T>(type: Type<T>) => T): Promise<void> {
         this.eventBus = inject(EventBus);
         this.templateLoader = new TemplateLoader(this.options.templatePath);
@@ -169,13 +171,14 @@ export class EmailPlugin implements VendurePlugin {
         }
     }
 
+    /** @internal */
     async onClose() {
         if (this.devMailbox) {
             this.devMailbox.destroy();
         }
     }
 
-    async setupEventSubscribers() {
+    private async setupEventSubscribers() {
         for (const handler of this.options.handlers) {
             this.eventBus.subscribe(handler.event, event => {
                 return this.handleEvent(handler, event);