docs(core): Improve inline docs for JobQueue stuff

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

@@ -10,12 +10,12 @@ import { Job } from '../../job-queue/job';
  * accessed. Custom strategies can be defined to make use of external
  * services such as Redis.
  *
- * @docsCateogry JobQueue
+ * @docsCategory JobQueue
  */
 export interface JobQueueStrategy {
     /**
      * @description
-     * Initialization logic to be run when after the Vendure server has been initialized
+     * Initialization logic to be run after the Vendure server has been initialized
      * (in the Nestjs [onApplicationBootstrap hook](https://docs.nestjs.com/fundamentals/lifecycle-events)).
      *
      * Receives an instance of the application's ModuleRef, which can be used to inject

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

@@ -16,7 +16,41 @@ import { CreateQueueOptions, JobData } from './types';
  * The JobQueueService is used to create new {@link JobQueue} instances and access
  * existing jobs.
  *
- * @docsCateogory JobQueue
+ * @example
+ * ```TypeScript
+ * // A service which transcodes video files
+ * class VideoTranscoderService {
+ *
+ *   private jobQueue: JobQueue<{ videoId: string; }>;
+ *
+ *   onModuleInit() {
+ *     // The JobQueue is created on initialization
+ *     this.jobQueue = this.jobQueueService.createQueue({
+ *       name: 'transcode-video',
+ *       concurrency: 5,
+ *       process: async job => {
+ *         try {
+ *           const result = await this.transcodeVideo(job.data.videoId);
+ *           job.complete(result);
+ *         } catch (e) {
+ *           job.fail(e);
+ *         }
+ *       },
+ *     });
+ *   }
+ *
+ *   addToTranscodeQueue(videoId: string) {
+ *     this.jobQueue.add({ videoId, })
+ *   }
+ *
+ *   private transcodeVideo(videoId: string) {
+ *     // e.g. call some external transcoding service
+ *   }
+ *
+ * }
+ * ```
+ *
+ * @docsCategory JobQueue
  */
 @Injectable()
 export class JobQueueService implements OnApplicationBootstrap, OnModuleDestroy {
@@ -30,6 +64,7 @@ export class JobQueueService implements OnApplicationBootstrap, OnModuleDestroy
 
     constructor(private configService: ConfigService, private processContext: ProcessContext) {}
 
+    /** @internal */
     async onApplicationBootstrap() {
         if (this.processContext.isServer) {
             const { pollInterval } = this.configService.jobQueueOptions;
@@ -94,6 +129,11 @@ export class JobQueueService implements OnApplicationBootstrap, OnModuleDestroy
         return this.jobQueueStrategy.findManyById(ids);
     }
 
+    /**
+     * @description
+     * Returns an array of `{ name: string; running: boolean; }` for each
+     * registered JobQueue.
+     */
     getJobQueues(): GraphQlJobQueue[] {
         return this.queues.map(queue => ({
             name: queue.name,
@@ -101,6 +141,11 @@ export class JobQueueService implements OnApplicationBootstrap, OnModuleDestroy
         }));
     }
 
+    /**
+     * @description
+     * Removes settled jobs (completed or failed). The implementation is handled by the configured
+     * {@link JobQueueStrategy}.
+     */
     removeSettledJobs(queueNames: string[], olderThan?: Date) {
         return this.jobQueueStrategy.removeSettledJobs(queueNames, olderThan);
     }

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

@@ -9,9 +9,13 @@ import { CreateQueueOptions, JobConfig, JobData } from './types';
  * @description
  * A JobQueue is used to process {@link Job}s. A job is added to the queue via the
  * `.add()` method, and the queue will then poll for new jobs and process each
- * according to the process
+ * according to the defined `process` function.
  *
- * @docsCateogory JobQueue
+ * *Note*: JobQueue instances should not be directly instantiated. Rather, the
+ * {@link JobQueueService} `createQueue()` method should be used (see that service
+ * for example usage).
+ *
+ * @docsCategory JobQueue
  */
 export class JobQueue<Data extends JobData<Data> = {}> {
     private activeJobs: Array<Job<Data>> = [];

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

@@ -6,14 +6,16 @@ import { SqlJobQueueStrategy } from './sql-job-queue-strategy';
 
 /**
  * @description
- * A plugin which configures Vendure to use the SQL database to persist the JobQueue jobs.
+ * A plugin which configures Vendure to use the SQL database to persist the JobQueue jobs using the {@link SqlJobQueueStrategy}. If you add this
+ * plugin to an existing Vendure installation, you'll need to run a [database migration](/docs/developer-guide/migrations), since this
+ * plugin will add a new "job_record" table to the database.
  *
  * @docsCategory JobQueue
  */
 @VendurePlugin({
     imports: [PluginCommonModule],
     entities: [JobRecord],
-    configuration: (config) => {
+    configuration: config => {
         config.jobQueueOptions.jobQueueStrategy = new SqlJobQueueStrategy();
         return config;
     },

packages/core/src/plugin/default-job-queue-plugin/sql-job-queue-strategy.ts

@@ -11,6 +11,13 @@ import { ListQueryBuilder } from '../../service/helpers/list-query-builder/list-
 
 import { JobRecord } from './job-record.entity';
 
+/**
+ * @description
+ * A {@link JobQueueStrategy} which uses the configured SQL database to persist jobs in the queue.
+ * This strategy is used by the {@link DefaultJobQueuePlugin}.
+ *
+ * @docsCategory JobQueue
+ */
 export class SqlJobQueueStrategy implements JobQueueStrategy {
     private connection: Connection | undefined;
     private listQueryBuilder: ListQueryBuilder;