docs: add search, standard-vs-async guide, API class examples

website/.vitepress/config.mts

@@ -27,6 +27,9 @@ export default defineConfig({
   },
   themeConfig: {
     logo: '/logo.png',
+    search: {
+      provider: 'local'
+    },
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
@@ -39,6 +42,10 @@ export default defineConfig({
         collapsed: false,
         items: [
           { text: 'Getting Started', link: '/getting-started' },
+          {
+            text: 'Standard Apex vs Async Lib',
+            link: '/introduction/standard-apex-vs-async-lib'
+          },
           { text: 'Installation', link: '/introduction/installation' }
         ]
       },
@@ -69,7 +76,6 @@ export default defineConfig({
         ]
       }
     ],
-    footer: false,
     socialLinks: [
       {
         icon: 'github',

website/api/batchable.md

@@ -2,16 +2,43 @@
 
 Apex classes `BatchableBuilder.cls` and `BatchableManager.cls`.
 
-**Common Batchable example:**
+New to async jobs? See
+[Standard Apex vs Async Lib](/introduction/standard-apex-vs-async-lib#batchable)
+for how this maps to a plain `Database.executeBatch`.
+
+**Common BatchJob class example:**
+
+Your batch class is a normal `Database.Batchable`. Async Lib does not change it,
+so `Database.Stateful`, `Database.QueryLocator`, and the `start` / `execute` /
+`finish` methods all work as usual.
 
 ```apex
-Database.Batchable<Object> job = new MyBatchJob();
+public class AccountCleanupBatch implements Database.Batchable<SObject>, Database.Stateful {
+  public Integer deletedCount = 0;
+
+  public Database.QueryLocator start(Database.BatchableContext bc) {
+    return Database.getQueryLocator('SELECT Id FROM Account WHERE Is_Active__c = false');
+  }
+
+  public void execute(Database.BatchableContext bc, List<Account> scope) {
+    delete scope;
+    deletedCount += scope.size();
+  }
+
+  public void finish(Database.BatchableContext bc) {
+    System.debug('Deleted ' + deletedCount + ' accounts');
+  }
+}
+```
 
-Async.AsyncResult result = Async.batchable(job)
+**Common Batchable example:**
+
+```apex
+Async.Result result = Async.batchable(new AccountCleanupBatch())
 	.scopeSize(100)
 	.execute();
 
-System.debug('Batch job enqueued: ' + result);
+System.debug('Batch job enqueued: ' + result.salesforceJobId);
 ```
 
 ## Methods

website/api/queueable.md

@@ -3,40 +3,61 @@
 Apex classes `QueueableBuilder.cls`, `QueueableManager.cls`, and
 `QueueableJob.cls`.
 
-For testing patterns and best practices, see
-[Testing Async Jobs](/explanations/testing-async-jobs).
+New to async jobs? See
+[Standard Apex vs Async Lib](/introduction/standard-apex-vs-async-lib#queueable)
+for how this maps to a plain `Queueable`. For testing patterns and best
+practices, see [Testing Async Jobs](/explanations/testing-async-jobs).
+
+**Common QueueableJob class example:**
+
+Extend `QueueableJob` and put your logic in `work()` instead of implementing
+`Queueable.execute()`.
+
+```apex
+public class AccountProcessorJob extends QueueableJob {
+  private List<Id> accountIds;
+
+  public AccountProcessorJob(List<Id> accountIds) {
+    this.accountIds = accountIds;
+  }
+
+  public override void work() {
+    List<Account> accounts = [SELECT Id, Name FROM Account WHERE Id IN :accountIds];
+    for (Account acc : accounts) {
+      acc.Description = 'Processed';
+    }
+    update accounts;
+  }
+}
+```
 
 **Common Queueable example:**
 
 ```apex
-QueueableJob job = new MyQueueableJob();
-Async.Result result = Async.queueable(job)
+Async.Result result = Async.queueable(new AccountProcessorJob(accountIds))
 	.priority(5)
 	.delay(2)
 	.continueOnJobExecuteFail()
 	.enqueue();
 ```
 
-Returns `result.customJobId` containing MyQueueableJob's unique Custom Job Id.
-
-**Common QueueableJob class example:**
-
-```apex
-public class AccountProcessorJob extends QueueableJob {
-  public override void work() {
-    // Get job context
-    Async.QueueableJobContext ctx = Async.getQueueableJobContext();
-  }
-}
-```
+Returns `result.customJobId` containing AccountProcessorJob's unique Custom Job
+Id.
 
 **Common Finalizer class example:**
 
+A finalizer runs after the job completes, whether it succeeded or threw. Extend
+`QueueableJob.Finalizer` and read the outcome from the `FinalizerContext`.
+
 ```apex
-private class ProcessorFinalizer extends QueueableJob.Finalizer {
+public class ProcessorFinalizer extends QueueableJob.Finalizer {
   public override void work() {
-    // Get finalizer context
     FinalizerContext finalizerCtx = Async.getQueueableJobContext().finalizerCtx;
+    if (finalizerCtx.getResult() == ParentJobResult.SUCCESS) {
+      System.debug('Job succeeded');
+    } else {
+      System.debug('Job failed: ' + finalizerCtx.getException().getMessage());
+    }
   }
 }
 ```

website/api/schedulable.md

@@ -2,11 +2,28 @@
 
 Apex classes `SchedulableBuilder.cls`, `SchedulableManager.cls`, and `CronBuilder.cls`.
 
+New to async jobs? See
+[Standard Apex vs Async Lib](/introduction/standard-apex-vs-async-lib#schedulable)
+for how this maps to a plain `System.schedule`.
+
+**Common SchedulableJob class example:**
+
+Your class is a normal `Schedulable`. Async Lib only replaces the
+`System.schedule(...)` call, building the cron expression and skipping the job
+when one with the same name is already scheduled.
+
+```apex
+public class AccountReportJob implements Schedulable {
+  public void execute(SchedulableContext context) {
+    // ... work ...
+  }
+}
+```
+
 **Common Schedulable example:**
 
 ```apex
-Schedulable job = new MySchedulableJob();
-List<Async.Result> results = Async.schedulable(job)
+List<Async.Result> results = Async.schedulable(new AccountReportJob())
 	.name('Daily Processing Job')
 	.cronExpression('0 0 2 * * ? *')
 	.skipWhenAlreadyScheduled()

website/getting-started.md

@@ -257,16 +257,18 @@ why. Query by **ChainId\_\_c** to see a whole chain run as a timeline.
 
 Now that you understand the basics:
 
-1. **Explore the API** - Learn about all available methods and options:
+1. **[Standard Apex vs Async Lib](/introduction/standard-apex-vs-async-lib)** -
+   See each plain-Apex async pattern next to its Async Lib equivalent.
+2. **Explore the API** - Learn about all available methods and options:
    1. **[Queueable API](/api/queueable.md)** - Detailed information on using
       Queueable jobs
    2. **[Batchable API](/api/batchable.md)** - Detailed information on using
       Batchable jobs
    3. **[Schedulable API](/api/schedulable.md)** - Detailed information on using
       Schedulable jobs
-2. **Read the Blog Post** - Check out the detailed explanation:
+3. **Read the Blog Post** - Check out the detailed explanation:
    [Apex Queueable Processing Framework](https://blog.beyondthecloud.dev/blog/apex-queueable-processing-framework)
-3. **[Initial Queueable Chain Schedulable Explanation](/explanations/initial-scheduled-queuable-batch-job.md)** -
+4. **[Initial Queueable Chain Schedulable Explanation](/explanations/initial-scheduled-queuable-batch-job.md)** -
    Learn why this job is important for framework to function properly.
 
 ## Quick Tips

website/index.md

@@ -12,7 +12,7 @@ hero:
       link: /getting-started
     - theme: alt
       text: View Examples
-      link: /getting-started
+      link: /introduction/standard-apex-vs-async-lib
 
 features:
   - title: Smart Queueable Jobs