docs(core): Doc block improvements & reordering

packages/asset-server-plugin/src/s3-asset-storage-strategy.ts

@@ -114,6 +114,7 @@ export function configureS3AssetStorage(s3Config: S3Config) {
  *
  * @docsCategory asset-server-plugin
  * @docsPage S3AssetStorageStrategy
+ * @docsWeight 0
  */
 export class S3AssetStorageStrategy implements AssetStorageStrategy {
     private AWS: typeof import('aws-sdk');

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

@@ -21,6 +21,20 @@ export type SerializedRequestContext = {
  * The RequestContext holds information relevant to the current request, which may be
  * required at various points of the stack.
  *
+ * It is a good practice to inject the RequestContext (using the {@link Ctx} decorator) into
+ * _all_ resolvers & REST handlers, and then pass it through to the service layer.
+ *
+ * This allows the service layer to access information about the current user, the active language,
+ * the active Channel, and so on. In addition, the {@link TransactionalConnection} relies on the
+ * presence of the RequestContext object in order to correctly handle per-request database transactions.
+ *
+ * @example
+ * ```TypeScript
+ * \@Query()
+ * myQuery(\@Ctx() ctx: RequestContext) {
+ *   return this.myService.getData(ctx);
+ * }
+ * ```
  * @docsCategory request
  */
 export class RequestContext {

packages/core/src/api/decorators/allow.decorator.ts

@@ -18,6 +18,6 @@ export const PERMISSIONS_METADATA_KEY = '__permissions__';
  * ```
  *
  * @docsCategory request
- * @docsPage Decorators
+ * @docsPage Allow Decorator
  */
 export const Allow = (...permissions: Permission[]) => SetMetadata(PERMISSIONS_METADATA_KEY, permissions);

packages/core/src/api/decorators/api.decorator.ts

@@ -15,13 +15,13 @@ import { getApiType } from '../common/get-api-type';
  * ```TypeScript
  *  \@Query()
  *  getAdministrators(\@Api() apiType: ApiType) {
- *      if (apiType === 'admin') {
- *          // ...
- *      }
+ *    if (apiType === 'admin') {
+ *      // ...
+ *    }
  *  }
  * ```
  * @docsCategory request
- * @docsPage Decorators
+ * @docsPage Api Decorator
  */
 export const Api = createParamDecorator((data, ctx: ExecutionContext) => {
     const info = ctx.getArgByIndex(3);

packages/core/src/api/decorators/request-context.decorator.ts

@@ -16,7 +16,7 @@ import { REQUEST_CONTEXT_KEY } from '../../common/constants';
  * ```
  *
  * @docsCategory request
- * @docsPage Decorators
+ * @docsPage Ctx Decorator
  */
 export const Ctx = createParamDecorator((data, ctx: ExecutionContext) => {
     if (ctx.getType<ContextType | 'graphql'>() === 'graphql') {

packages/core/src/api/decorators/transaction.decorator.ts

@@ -5,29 +5,49 @@ import { TransactionInterceptor } from '../middleware/transaction-interceptor';
 export const TRANSACTION_MODE_METADATA_KEY = '__transaction_mode__';
 /**
  * @description
- * When in `auto` mode, a transaction will be automatically started before the resolver
- * runs and committed after it ends (or rolled back in case of error).
+ * The Transaction decorator can handle transactions automatically (which is the default) or be set to
+ * "manual" mode, where the {@link TransactionalConnection} `.startTransaction()` and `.commitOpenTransaction()`
+ * methods must them be used.
  *
- * In `manual` mode, the application code itself must start and commit the transactions.
+ * @example
+ * ```TypeScript
+ * // in a GraphQL resolver file
+ *
+ * \@Transaction('manual')
+ * async myMutation(\@Ctx() ctx: RequestContext) {
+ *   await this.connection.startTransaction(ctx);
+ *   const result = this.myService.createThing(ctx);
+ *   const thing = this.myService.updateOtherThing(ctx, result.id);
+ *   await this.connection.commitOpenTransaction(ctx);
+ *   return thing;
+ * }
+ * ```
+ * Note that even in manual mode, a rollback will be automatically performed in
+ * the case that an uncaught error is thrown within the resolver.
  *
  * @default 'auto'
- * @docsCategory data-access
+ * @docsCategory request
+ * @docsPage Transaction Decorator
  */
 export type TransactionMode = 'auto' | 'manual';
 
 /**
  * @description
- * Runs the decorated method in a TypeORM transaction. It works by creating a transctional
+ * Runs the decorated method in a TypeORM transaction. It works by creating a transactional
  * QueryRunner which gets attached to the RequestContext object. When the RequestContext
  * is the passed to the {@link TransactionalConnection} `getRepository()` method, this
  * QueryRunner is used to execute the queries within this transaction.
  *
+ * Essentially, the entire resolver function is wrapped in a try-catch block which commits the
+ * transaction on successful completion of the method, or rolls back the transaction in an unhandled
+ * error is thrown.
+ *
  * @example
  * ```TypeScript
  * // in a GraphQL resolver file
  *
  * \@Transaction()
- * async myMutation(@Ctx() ctx: RequestContext) {
+ * async myMutation(\@Ctx() ctx: RequestContext) {
  *   // as long as the `ctx` object is passed in to
  *   // all database operations, the entire mutation
  *   // will be run as an atomic transaction, and rolled
@@ -38,7 +58,8 @@ export type TransactionMode = 'auto' | 'manual';
  * ```
  *
  * @docsCategory request
- * @docsCategory data-access
+ * @docsPage Transaction Decorator
+ * @docsWeight 0
  */
 export const Transaction = (transactionMode: TransactionMode = 'auto') => {
     return applyDecorators(

packages/core/src/common/finite-state-machine/finite-state-machine.ts

@@ -5,7 +5,7 @@ import { StateMachineConfig } from './types';
 /**
  * @description
  * A simple type-safe finite state machine. This is used internally to control the Order process, ensuring that
- * the state of Orders, Payments and Refunds follows a well-defined behaviour.
+ * the state of Orders, Payments, Fulfillments and Refunds follows a well-defined behaviour.
  *
  * @docsCategory StateMachine
  */

packages/core/src/common/finite-state-machine/types.ts

@@ -53,7 +53,8 @@ export type OnTransitionStartFn<T extends string, Data> = (
 
 /**
  * @description
- * Called after a transition has taken place.
+ * Called when a transition is prevented and the `onTransitionStart` handler has returned an
+ * error message.
  *
  * @docsCategory StateMachine
  * @docsPage StateMachineConfig
@@ -66,8 +67,7 @@ export type OnTransitionErrorFn<T extends string> = (
 
 /**
  * @description
- * Called when a transition is prevented and the `onTransitionStart` handler has returned an
- * error message.
+ * Called after a transition has taken place.
  *
  * @docsCategory StateMachine
  * @docsPage StateMachineConfig
@@ -84,6 +84,7 @@ export type OnTransitionEndFn<T extends string, Data> = (
  *
  * @docsCategory StateMachine
  * @docsPage StateMachineConfig
+ * @docsWeight 0
  */
 export interface StateMachineConfig<T extends string, Data = undefined> {
     /**

packages/core/src/config/fulfillment/custom-fulfillment-process.ts

@@ -16,7 +16,7 @@ import {
  *
  * For detailed description of the interface members, see the {@link StateMachineConfig} docs.
  *
- * @docsCategory fulfillments
+ * @docsCategory fulfillment
  */
 export interface CustomFulfillmentProcess<State extends string> extends InjectableStrategy {
     transitions?: Transitions<State, State | FulfillmentState> &

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

@@ -75,6 +75,7 @@ export interface PromotionOrderActionConfig<T extends ConfigArgs> extends Promot
  *
  * @docsCategory promotions
  * @docsPage promotion-action
+ * @docsWeight 0
  */
 export abstract class PromotionAction<T extends ConfigArgs = {}> extends ConfigurableOperationDef<T> {
     /**
@@ -112,6 +113,7 @@ export abstract class PromotionAction<T extends ConfigArgs = {}> extends Configu
  *
  * @docsCategory promotions
  * @docsPage promotion-action
+ * @docsWeight 1
  */
 export class PromotionItemAction<T extends ConfigArgs = ConfigArgs> extends PromotionAction<T> {
     private readonly executeFn: ExecutePromotionItemActionFn<T>;
@@ -145,6 +147,7 @@ export class PromotionItemAction<T extends ConfigArgs = ConfigArgs> extends Prom
  *
  * @docsCategory promotions
  * @docsPage promotion-action
+ * @docsWeight 2
  */
 export class PromotionOrderAction<T extends ConfigArgs = ConfigArgs> extends PromotionAction<T> {
     private readonly executeFn: ExecutePromotionOrderActionFn<T>;

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

@@ -30,6 +30,7 @@ export type CheckPromotionConditionFn<T extends ConfigArgs> = (
  *
  * @docsCategory promotions
  * @docsPage promotion-condition
+ * @docsWeight 1
  */
 export interface PromotionConditionConfig<T extends ConfigArgs> extends ConfigurableOperationDefOptions<T> {
     check: CheckPromotionConditionFn<T>;
@@ -44,6 +45,7 @@ export interface PromotionConditionConfig<T extends ConfigArgs> extends Configur
  *
  * @docsCategory promotions
  * @docsPage promotion-condition
+ * @docsWeight 0
  */
 export class PromotionCondition<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {
     /**

packages/core/src/config/session-cache/session-cache-strategy.ts

@@ -52,6 +52,7 @@ export type CachedSession = {
  *
  * @docsCategory auth
  * @docsPage SessionCacheStrategy
+ * @docsWeight 0
  */
 export interface SessionCacheStrategy extends InjectableStrategy {
     /**

packages/core/src/job-queue/job.ts

@@ -31,6 +31,7 @@ export type JobEventListener<T extends JobData<T>> = (job: Job<T>) => void;
  *
  * @docsCategory JobQueue
  * @docsPage Job
+ * @docsWeight 0
  */
 export class Job<T extends JobData<T> = any> {
     readonly id: ID | null;

packages/core/src/service/services/stock-movement.service.ts

@@ -1,8 +1,6 @@
 import { Injectable } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/typeorm';
 import { StockMovementListOptions } from '@vendure/common/lib/generated-types';
 import { ID, PaginatedList } from '@vendure/common/lib/shared-types';
-import { Connection } from 'typeorm';
 
 import { RequestContext } from '../../api/common/request-context';
 import { InternalServerError } from '../../common/error/errors';
@@ -10,7 +8,6 @@ import { ShippingCalculator } from '../../config/shipping-method/shipping-calcul
 import { ShippingEligibilityChecker } from '../../config/shipping-method/shipping-eligibility-checker';
 import { OrderItem } from '../../entity/order-item/order-item.entity';
 import { Order } from '../../entity/order/order.entity';
-import { ProductOptionGroup } from '../../entity/product-option-group/product-option-group.entity';
 import { ProductVariant } from '../../entity/product-variant/product-variant.entity';
 import { ShippingMethod } from '../../entity/shipping-method/shipping-method.entity';
 import { Cancellation } from '../../entity/stock-movement/cancellation.entity';

packages/core/src/service/transaction/transactional-connection.ts

@@ -101,7 +101,7 @@ export class TransactionalConnection {
     /**
      * @description
      * Manually commits any open transaction. Should be very rarely needed, since the {@link Transaction} decorator
-     * and the {@link TransactionInterceptor} take care of this automatically. Use-cases include situations
+     * and the internal TransactionInterceptor take care of this automatically. Use-cases include situations
      * in which the worker thread needs to access changes made in the current transaction, or when using the
      * Transaction decorator in manual mode.
      */

packages/ui-devkit/src/compiler/types.ts

@@ -40,6 +40,7 @@ export interface TranslationExtension {
  *
  * @docsCategory UiDevkit
  * @docsPage AdminUiExtension
+ * @docsWeight 0
  */
 export interface AdminUiExtension extends Partial<TranslationExtension> {
     /**