From 6084bbe687d7682e9df6e2f6ce1fd40ea6793b94 Mon Sep 17 00:00:00 2001
From: Joshua Horton <joshua_horton@sil.org>
Date: Thu, 9 Apr 2026 16:48:18 -0500
Subject: [PATCH] docs(web): add documentation for new search-related
 interfaces

---
 .../correction/correction-result-mapping.ts   | 22 ++++++++++++++++
 .../main/correction/correction-searchable.ts  | 25 +++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/web/src/engine/predictive-text/worker-thread/src/main/correction/correction-result-mapping.ts b/web/src/engine/predictive-text/worker-thread/src/main/correction/correction-result-mapping.ts
index 35c391c34e..2c00c637a2 100644
--- a/web/src/engine/predictive-text/worker-thread/src/main/correction/correction-result-mapping.ts
+++ b/web/src/engine/predictive-text/worker-thread/src/main/correction/correction-result-mapping.ts
@@ -1,7 +1,29 @@
+/*
+ * Keyman is copyright (C) SIL Global. MIT License.
+ *
+ * Created by jahorton on 2026-04-02
+ *
+ * This file defines the type used for tracking critical graph-search properties
+ * utilized during correction-search by any type compatible with the
+ * `getBestMatches` algorithm.
+ */
+
 import { CorrectionSearchable } from "./correction-searchable.js";
 
+/**
+ * Any return value from `.handleNextNode()` designed for use with the
+ * `getBestMatches` method must adhere to this type interface for representing
+ * completed search paths.
+ */
 export interface CorrectionResultMapping<ResultType> {
+  /**
+   * Represents the "searchable" object through which the completed search path last traversed.
+   */
   readonly matchingSpace: CorrectionSearchable<ResultType, CorrectionResultMapping<ResultType>>;
+
+  /**
+   * The object representing the search path completed at the current search step.
+   */
   readonly matchedResult: ResultType;
 
   /**
diff --git a/web/src/engine/predictive-text/worker-thread/src/main/correction/correction-searchable.ts b/web/src/engine/predictive-text/worker-thread/src/main/correction/correction-searchable.ts
index b43e315833..addc5f2ccc 100644
--- a/web/src/engine/predictive-text/worker-thread/src/main/correction/correction-searchable.ts
+++ b/web/src/engine/predictive-text/worker-thread/src/main/correction/correction-searchable.ts
@@ -1,3 +1,13 @@
+/*
+ * Keyman is copyright (C) SIL Global. MIT License.
+ *
+ * Created by jahorton on 2026-04-02
+ *
+ * This file defines the interface required of objects that represent portions
+ * of a search graph or search quotient-graph compatible with the
+ * `getBestMatches` algorithm.
+ */
+
 import { CorrectionResultMapping } from "./correction-result-mapping.js";
 
 type NullPath = {
@@ -18,9 +28,24 @@ type CompleteSearchPath<MappingType> = {
 
 export type PathResult<MappingType> = NullPath | IntermediateSearchPath | CompleteSearchPath<MappingType>;
 
+/**
+ * Represents objects that support correction search via the `getBestMatches`
+ * method, providing metadata relative to optimizing the search process for
+ * their represented portion of the search-graph.
+ */
 export interface CorrectionSearchable<ResultType, ResultMapping extends CorrectionResultMapping<ResultType>> {
+  /**
+   * The best cost found for any search paths yet unprocessed by either this "searchable" or any of its ancestors.
+   */
   readonly currentCost: number;
+
+  /**
+   * A list of all search path results already found that terminate at this "searchable".
+   */
   readonly previousResults: ResultMapping[];
 
+  /**
+   * Processes the most likely currently-unprocessed search path represented by this "searchable".
+   */
   handleNextNode(): PathResult<ResultMapping>;
 }
\ No newline at end of file