docs(text): refine documents in text module (#5425)

This commit refines the document in the `text` module. Namely,

- Move the note about word distance calculation possibly to change in the future
  to more visible place
- Fix the wrong doc comments (e.g. `possibleWords` description on
  `closestString`)
- Change `possibleWords` type from `string[]` to `ReadonlyArray<string>` to
  communicate to readers that the passed array won't be mutated
- Use `toSorted` instead of `sort` to ensure immutability

text/closest_string.ts

@@ -6,7 +6,12 @@ import { levenshteinDistance } from "./levenshtein_distance.ts";
 const getWordDistance = levenshteinDistance;
 
 /**
- * The the most similar string from an array of strings.
+ * Finds the most similar string from an array of strings.
+ *
+ * Note: the ordering of words may change with version-updates
+ * E.g. word-distance metric may change (improve)
+ * use a named-distance (e.g. levenshteinDistance) to
+ * guarantee a particular ordering.
  *
  * @example Usage
  * ```ts
@@ -20,19 +25,14 @@ const getWordDistance = levenshteinDistance;
  * ```
  *
  * @param givenWord The string to measure distance against
- * @param possibleWords The string-array that will be sorted
+ * @param possibleWords The string-array to pick the closest string from
  * @param options An options bag containing a `caseSensitive` flag indicating
  * whether the distance should include case. Default is false.
- * @returns A sorted copy of possibleWords
- * @note
- * the ordering of words may change with version-updates
- * e.g. word-distance metric may change (improve)
- * use a named-distance (e.g. levenshteinDistance) to
- * guarantee a particular ordering
+ * @returns The closest string
  */
 export function closestString(
   givenWord: string,
-  possibleWords: string[],
+  possibleWords: ReadonlyArray<string>,
   options?: {
     caseSensitive?: boolean;
   },

text/compare_similarity.ts

@@ -16,7 +16,13 @@ export interface CompareSimilarityOptions {
 }
 
 /**
- * Sort based on word similarity.
+ * Takes a string and generates a comparator function to determine which of two
+ * strings is more similar to the given one.
+ *
+ * Note: the ordering of words may change with version-updates
+ * E.g. word-distance metric may change (improve)
+ * use a named-distance (e.g. levenshteinDistance) to
+ * guarantee a particular ordering.
  *
  * @param givenWord The string to measure distance against.
  * @param options Options for the sort.
@@ -33,15 +39,10 @@ export interface CompareSimilarityOptions {
  * import { assertEquals } from "@std/assert";
  *
  * const words = ["hi", "hello", "help"];
- * const sortedWords = words.sort(compareSimilarity("hep"));
+ * const sortedWords = words.toSorted(compareSimilarity("hep"));
  *
  * assertEquals(sortedWords, ["help", "hi", "hello"]);
  * ```
- *
- * Note: the ordering of words may change with version-updates
- * E.g. word-distance metric may change (improve)
- * use a named-distance (e.g. levenshteinDistance) to
- * guarantee a particular ordering
  */
 export function compareSimilarity(
   givenWord: string,

text/word_similarity_sort.ts

@@ -11,6 +11,11 @@ export interface WordSimilaritySortOptions extends CompareSimilarityOptions {}
 /**
  * Sorts a string-array by similarity to a given string.
  *
+ * Note: the ordering of words may change with version-updates
+ * E.g. word-distance metric may change (improve)
+ * use a named-distance (e.g. levenshteinDistance) to
+ * guarantee a particular ordering.
+ *
  * @example Basic usage
  *
  * ```ts
@@ -36,17 +41,16 @@ export interface WordSimilaritySortOptions extends CompareSimilarityOptions {}
  * ```
  *
  * @param givenWord The string to measure distance against.
- * @param possibleWords The string-array that will be sorted.
+ * @param possibleWords The string-array that will be sorted. This array will
+ * not be mutated, but the sorted copy will be returned.
  * @param options Options for the sort.
- * @returns A sorted copy of possibleWords.
+ * @returns A sorted copy of `possibleWords`.
  */
 export function wordSimilaritySort(
   givenWord: string,
-  possibleWords: string[],
+  possibleWords: ReadonlyArray<string>,
   options?: WordSimilaritySortOptions,
 ): string[] {
   // This distance metric could be swapped/improved in the future
-  return [...possibleWords].sort(
-    compareSimilarity(givenWord, options),
-  );
+  return possibleWords.toSorted(compareSimilarity(givenWord, options));
 }