docs: add comprehensive JSDoc to processor modules

- Document collect.ts for asynchronous item collection
- Document match.ts for filtering with multiple matchers
- Document sort.ts for item ordering strategies
- Document render.ts for display transformation
- Document preview.ts for preview generation
- Include configuration options and method documentation
- Add examples demonstrating processor usage

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: lambdalisue

denops/fall/processor/collect.ts

@@ -1,3 +1,21 @@
+/**
+ * @module processor/collect
+ *
+ * Collection processor for vim-fall.
+ *
+ * This module provides the CollectProcessor class which manages the collection
+ * of items from a source. It handles:
+ *
+ * - Asynchronous item collection with progress updates
+ * - Chunking for performance optimization
+ * - Item deduplication and ID assignment
+ * - Pause/resume functionality
+ * - Threshold limiting to prevent memory issues
+ *
+ * The processor emits events during collection to update the UI and coordinate
+ * with other components.
+ */
+
 import type { Denops } from "jsr:@denops/std@^7.3.2";
 import { take } from "jsr:@core/iterutil@^0.9.0/async/take";
 import { map } from "jsr:@core/iterutil@^0.9.0/map";
@@ -8,17 +26,60 @@ import { Chunker } from "../lib/chunker.ts";
 import { UniqueOrderedList } from "../lib/unique_ordered_list.ts";
 import { dispatch } from "../event.ts";
 
+/** Default maximum number of items to collect */
 const THRESHOLD = 100000;
+
+/** Default number of items to process in each chunk */
 const CHUNK_SIZE = 1000;
+
+/** Default interval in milliseconds between chunk updates */
 const CHUNK_INTERVAL = 100;
 
+/**
+ * Configuration options for the CollectProcessor.
+ *
+ * @template T - The type of detail data associated with each item
+ */
 export type CollectProcessorOptions<T extends Detail> = {
+  /** Initial items to populate the processor with (useful for resume) */
   initialItems?: readonly IdItem<T>[];
+
+  /** Maximum number of items to collect (default: 100000) */
   threshold?: number;
+
+  /** Number of items to process before emitting an update (default: 1000) */
   chunkSize?: number;
+
+  /** Maximum time in ms between updates regardless of chunk size (default: 100) */
   chunkInterval?: number;
 };
 
+/**
+ * Processor responsible for collecting items from a source.
+ *
+ * The CollectProcessor manages the asynchronous collection of items from a source,
+ * handling chunking, deduplication, and progress updates. It can be paused and
+ * resumed, making it suitable for long-running collection operations.
+ *
+ * @template T - The type of detail data associated with each item
+ *
+ * @example
+ * ```typescript
+ * const processor = new CollectProcessor(fileSource, {
+ *   threshold: 50000,
+ *   chunkSize: 500,
+ * });
+ *
+ * // Start collecting
+ * processor.start(denops, { args: ["--hidden"] });
+ *
+ * // Access collected items
+ * console.log(processor.items.length);
+ *
+ * // Pause if needed
+ * processor.pause();
+ * ```
+ */
 export class CollectProcessor<T extends Detail> implements Disposable {
   readonly #controller: AbortController = new AbortController();
   readonly #items: UniqueOrderedList<IdItem<T>>;
@@ -28,6 +89,12 @@ export class CollectProcessor<T extends Detail> implements Disposable {
   #processing?: Promise<void>;
   #paused?: PromiseWithResolvers<void>;
 
+  /**
+   * Creates a new CollectProcessor.
+   *
+   * @param source - The source to collect items from
+   * @param options - Configuration options
+   */
   constructor(
     readonly source: Source<T>,
     options: CollectProcessorOptions<T> = {},
@@ -45,10 +112,20 @@ export class CollectProcessor<T extends Detail> implements Disposable {
     );
   }
 
+  /**
+   * Gets the currently collected items.
+   *
+   * @returns An array of collected items with assigned IDs
+   */
   get items(): readonly IdItem<T>[] {
     return this.#items.items;
   }
 
+  /**
+   * Validates that the processor is not disposed.
+   *
+   * @throws Error if the processor is disposed
+   */
   #validateAvailability(): void {
     try {
       this.#controller.signal.throwIfAborted();
@@ -60,6 +137,26 @@ export class CollectProcessor<T extends Detail> implements Disposable {
     }
   }
 
+  /**
+   * Starts or resumes the collection process.
+   *
+   * If collection is already in progress and paused, this will resume it.
+   * Otherwise, it starts a new collection process.
+   *
+   * The method emits the following events:
+   * - `collect-processor-started`: When collection begins
+   * - `collect-processor-updated`: When new items are collected
+   * - `collect-processor-succeeded`: When collection completes successfully
+   * - `collect-processor-failed`: If an error occurs
+   *
+   * @param denops - The Denops instance
+   * @param params - Parameters to pass to the source's collect method
+   *
+   * @example
+   * ```typescript
+   * processor.start(denops, { args: ["--hidden", "--no-ignore"] });
+   * ```
+   */
   start(
     denops: Denops,
     params: CollectParams,
@@ -107,6 +204,20 @@ export class CollectProcessor<T extends Detail> implements Disposable {
       });
   }
 
+  /**
+   * Pauses the collection process.
+   *
+   * The collection can be resumed by calling `start()` again.
+   * This is useful for temporarily stopping collection to free up
+   * resources or when the user navigates away.
+   *
+   * @example
+   * ```typescript
+   * processor.pause();
+   * // Later...
+   * processor.start(denops, params); // Resumes from where it left off
+   * ```
+   */
   pause(): void {
     this.#validateAvailability();
     if (!this.#processing) {
@@ -118,6 +229,9 @@ export class CollectProcessor<T extends Detail> implements Disposable {
     });
   }
 
+  /**
+   * Resumes a paused collection process.
+   */
   #resume(): void {
     if (!this.#paused) {
       return;
@@ -126,6 +240,12 @@ export class CollectProcessor<T extends Detail> implements Disposable {
     this.#paused = undefined;
   }
 
+  /**
+   * Disposes of the processor and cancels any ongoing collection.
+   *
+   * This method is called automatically when the processor is no longer needed.
+   * It aborts the collection process and cleans up resources.
+   */
   [Symbol.dispose](): void {
     try {
       this.#controller.abort(null);

denops/fall/processor/match.ts

@@ -1,3 +1,21 @@
+/**
+ * @module processor/match
+ *
+ * Matching processor for vim-fall.
+ *
+ * This module provides the MatchProcessor class which filters items based on
+ * user queries using configurable matchers. It supports:
+ *
+ * - Multiple matcher implementations (fuzzy, substring, regex, etc.)
+ * - Incremental matching for performance optimization
+ * - Asynchronous processing with chunking
+ * - Query caching to avoid redundant processing
+ * - Matcher switching during runtime
+ *
+ * The processor transforms collected items into filtered items that match
+ * the current query, emitting events to coordinate with other components.
+ */
+
 import type { Denops } from "jsr:@denops/std@^7.3.2";
 import { delay } from "jsr:@std/async@^1.0.0/delay";
 import { take } from "jsr:@core/iterutil@^0.9.0/async/take";
@@ -8,22 +26,75 @@ import { Chunker } from "../lib/chunker.ts";
 import { ItemBelt } from "../lib/item_belt.ts";
 import { dispatch } from "../event.ts";
 
+/** Default delay interval between processing cycles */
 const INTERVAL = 0;
+
+/** Default maximum number of items to process */
 const THRESHOLD = 100000;
+
+/** Default number of items to process in each chunk */
 const CHUNK_SIZE = 1000;
+
+/** Default interval in milliseconds between chunk updates */
 const CHUNK_INTERVAL = 100;
 
+/**
+ * Configuration options for the MatchProcessor.
+ *
+ * @template T - The type of detail data associated with each item
+ */
 export type MatchProcessorOptions<T extends Detail> = {
+  /** Initial filtered items (useful for resume) */
   initialItems?: readonly IdItem<T>[];
+
+  /** Initial query string */
   initialQuery?: string;
+
+  /** Initial matcher index */
   initialIndex?: number;
+
+  /** Delay between processing cycles in ms (default: 0) */
   interval?: number;
+
+  /** Maximum items to process (default: 100000) */
   threshold?: number;
+
+  /** Items per chunk (default: 1000) */
   chunkSize?: number;
+
+  /** Max time between chunk updates in ms (default: 100) */
   chunkInterval?: number;
+
+  /** Enable incremental matching mode for better performance */
   incremental?: boolean;
 };
 
+/**
+ * Processor responsible for filtering items based on user queries.
+ *
+ * The MatchProcessor applies matchers to filter collected items according to
+ * the current query. It supports multiple matchers that can be switched
+ * dynamically, and provides both standard and incremental matching modes.
+ *
+ * @template T - The type of detail data associated with each item
+ *
+ * @example
+ * ```typescript
+ * const processor = new MatchProcessor([fzf(), substring()], {
+ *   incremental: true,
+ *   chunkSize: 500,
+ * });
+ *
+ * // Start matching
+ * processor.start(denops, {
+ *   items: collectedItems,
+ *   query: "search term",
+ * });
+ *
+ * // Switch matcher
+ * processor.matcherIndex = 1;
+ * ```
+ */
 export class MatchProcessor<T extends Detail> implements Disposable {
   readonly matchers: ItemBelt<Matcher<T>>;
   readonly #interval: number;
@@ -57,18 +128,34 @@ export class MatchProcessor<T extends Detail> implements Disposable {
     return this.matchers.current!;
   }
 
+  /**
+   * Gets the currently filtered items.
+   *
+   * @returns Array of items that match the current query
+   */
   get items(): IdItem<T>[] {
     return this.#items;
   }
 
+  /**
+   * Gets the total number of available matchers.
+   */
   get matcherCount(): number {
     return this.matchers.count;
   }
 
+  /**
+   * Gets the current matcher index.
+   */
   get matcherIndex(): number {
     return this.matchers.index;
   }
 
+  /**
+   * Sets the current matcher index.
+   *
+   * @param index - The matcher index or "$" for the last matcher
+   */
   set matcherIndex(index: number | "$") {
     if (index === "$") {
       index = this.matchers.count;
@@ -87,6 +174,34 @@ export class MatchProcessor<T extends Detail> implements Disposable {
     }
   }
 
+  /**
+   * Starts the matching process.
+   *
+   * This method filters the provided items based on the query using the
+   * current matcher. It handles:
+   * - Query caching to avoid redundant processing
+   * - Incremental matching when enabled
+   * - Asynchronous processing with progress updates
+   *
+   * The method emits:
+   * - `match-processor-started`: When matching begins
+   * - `match-processor-updated`: When new matches are found
+   * - `match-processor-succeeded`: When matching completes
+   * - `match-processor-failed`: If an error occurs
+   *
+   * @param denops - The Denops instance
+   * @param params - Items to filter and the query string
+   * @param options - Optional configuration
+   * @param options.restart - Force restart even if processing
+   *
+   * @example
+   * ```typescript
+   * processor.start(denops, {
+   *   items: collectedItems,
+   *   query: "search term",
+   * });
+   * ```
+   */
   start(
     denops: Denops,
     { items, query }: MatchParams<T>,
@@ -158,6 +273,12 @@ export class MatchProcessor<T extends Detail> implements Disposable {
       });
   }
 
+  /**
+   * Disposes of the processor and cancels any ongoing matching.
+   *
+   * This method is called automatically when the processor is no longer needed.
+   * It aborts the matching process and cleans up resources.
+   */
   [Symbol.dispose](): void {
     try {
       this.#controller.abort(null);