docs: Improve documentation comments

Author: lambdalisue

README.md

@@ -1,17 +1,19 @@
 # 🍂 fall-core
 
+[![JSR](https://jsr.io/badges/@vim-fall/core)](https://jsr.io/@vim-fall/core)
 [![Test](https://github.com/vim-fall/fall-core/actions/workflows/test.yml/badge.svg)](https://github.com/vim-fall/fall-core/actions/workflows/test.yml)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Core types for [Fall](https://github.com/vim-fall/fall), a Vim/Neovim Fuzzy
-Finder plugin powered by [Denops](https://github.com/vim-denops/denops.vim).
+Core types for [Fall](https://github.com/vim-fall/fall), a Vim/Neovim fuzzy
+finder plugin powered by [Denops](https://github.com/vim-denops/denops.vim).
 
 > [!WARNING]
 >
-> This module is for internal use only. It is not intended to be used by others.
+> This module is intended for internal use only and is not meant for external
+> use.
 
 ## License
 
-The code in this repository follows the MIT license, as detailed in
-[LICENSE](./LICENSE). Contributors must agree that any modifications submitted
-to this repository also adhere to the license.
+This repository is licensed under the MIT License, as detailed in the
+[LICENSE](./LICENSE) file. By contributing, you agree that any modifications you
+submit will also be licensed under the MIT License.

_typeutil.ts

@@ -1 +1,4 @@
+/**
+ * Promish<T> represents a value that can be either of type T or a Promise of type T.
+ */
 export type Promish<T> = T | Promise<T>;

action.ts

@@ -3,29 +3,39 @@ import type { Denops } from "@denops/std";
 import type { Promish } from "./_typeutil.ts";
 import type { IdItem } from "./item.ts";
 
+/**
+ * Parameters for invoking an action.
+ */
 export type InvokeParams<T> = {
   /**
-   * The item under the cursor.
+   * The item currently under the cursor.
+   *
+   * If `filteredItems` is empty, this will be `undefined`.
    */
   readonly item?: IdItem<T> | undefined;
   /**
-   * The selected items.
+   * The items selected by the user.
+   *
+   * If no items were selected, this will be `undefined`.
    */
   readonly selectedItems?: readonly IdItem<T>[] | undefined;
   /**
-   * The filtered items.
+   * The items after filtering.
    */
   readonly filteredItems: readonly IdItem<T>[];
 };
 
+/**
+ * An action that can be invoked from the picker.
+ */
 export type Action<T> = {
   /**
    * Invoke the action.
    *
-   * @param denops The Denops instance.
-   * @param params The parameters for invoking the action.
-   * @param options The options.
-   * @returns If the picker should not be closed, return `true`.
+   * @param denops - The Denops instance.
+   * @param params - Parameters for the action invocation.
+   * @param options - Additional options.
+   * @returns If the picker should remain open, return `true`.
    */
   invoke(
     denops: Denops,

coordinator.ts

@@ -1,35 +1,74 @@
 import type { Border, Theme } from "./theme.ts";
 
+/**
+ * Represents the width and height dimensions.
+ */
 export type Size = {
   width: number;
   height: number;
 };
 
+/**
+ * Dimension: size with position (col, row).
+ */
 export type Dimension = Size & {
   col: number;
   row: number;
 };
 
+/**
+ * Styles for the picker components.
+ */
 export type Style = {
+  /**
+   * The border style for the input component.
+   */
   input: Border;
+  /**
+   * The border style for the list component.
+   */
   list: Border;
+  /**
+   * The border style for the preview component, if applicable.
+   */
   preview?: Border;
 };
 
+/**
+ * Layout for the picker components.
+ */
 export type Layout = {
+  /**
+   * Dimensions of the input component.
+   */
   input: Dimension;
+  /**
+   * Dimensions of the list component.
+   */
   list: Dimension;
+  /**
+   * Dimensions of the preview component, if applicable.
+   */
   preview?: Dimension;
 };
 
+/**
+ * Coordinator for managing the layout and style of picker components.
+ */
 export type Coordinator = {
   /**
-   * Style of the picker components.
+   * Retrieves the style for the picker components.
+   *
+   * @param theme - The theme used to style the components.
+   * @returns The style configuration for the picker components.
    */
   style(theme: Theme): Style;
 
   /**
-   * Layout of the picker components.
+   * Determines the layout for the picker components based on screen size.
+   *
+   * @param screen - The size of the screen.
+   * @returns The layout configuration for the picker components.
    */
   layout(screen: Size): Layout;
 };

curator.ts

@@ -2,25 +2,33 @@ import type { Denops } from "@denops/std";
 
 import type { IdItem } from "./item.ts";
 
+/**
+ * Parameters for curating items.
+ */
 export type CurateParams = {
   /**
-   * The arguments passed to the picker.
+   * Arguments passed to the picker.
    */
   readonly args: readonly string[];
   /**
-   * User input query.
+   * User input query for filtering items.
    */
   readonly query: string;
 };
 
+/**
+ * Curator that collects and filters items based on user input.
+ *
+ * Acts as an interactive `Source`.
+ */
 export type Curator<T> = {
   /**
-   * Curate items.
+   * Curates items based on the provided parameters.
    *
-   * @param denops The Denops instance.
-   * @param params The parameters to curate items.
-   * @param options The options.
-   * @param options.signal The signal to cancel the operation.
+   * @param denops - The Denops instance.
+   * @param params - Parameters for curating items.
+   * @param options - Optional settings, including an abort signal.
+   * @returns An async iterator over curated `IdItem` elements.
    */
   curate(
     denops: Denops,

item.ts

@@ -1,98 +1,106 @@
+/**
+ * An item processed by the picker.
+ */
 export type IdItem<T> = {
   /**
-   * The unique identifier of the item.
+   * Unique identifier for the item.
    */
-  readonly id: number;
+  readonly id: unknown;
 
   /**
-   * The value of the item.
+   * Item's primary value.
    */
   readonly value: string;
 
   /**
-   * The detailed information of the item.
+   * Detailed information about the item.
    *
-   * This information is used in further processing.
-   * Developers should verify if the `detail` has the expected structure before using it
-   * and ignore the item if it does not.
+   * Used for further processing.
    */
   readonly detail: T;
 
   /**
-   * The display label of the item.
+   * Display label for the item in the picker.
    *
-   * This label is used to display the item in the picker.
-   * If not specified, `value` is used.
+   * If not specified, `value` is used as the label.
    */
   label?: string;
 
   /**
-   * Decorations to be applied to the line of the item in the picker.
+   * Decorations applied to the item's line in the picker.
    *
-   * These decorations highlight the matched part of the item, or are used for better visualization.
-   * Developers should respect existing `decorations` and extend them.
+   * These decorations highlight matched parts or improve visualization.
+   * Developers should respect and extend existing `decorations`.
    *
-   * Note: If `highlight` is not specified, the picker will use the default highlight group
-   * for highlighting the matched part.
+   * Note: If `highlight` is unspecified, the picker uses a default highlight
+   * group to emphasize matched parts.
    */
   decorations?: readonly ItemDecoration[];
 };
 
+/**
+ * An item displayed in the picker.
+ */
 export type DisplayItem<T> = IdItem<T> & {
   /**
-   * The display label of the item.
+   * Display label for the item in the picker.
    *
-   * This label is used to display the item in the picker.
-   * If not specified, `value` is used.
+   * If unspecified, `value` is used as the label.
    */
   label: string;
 
   /**
-   * Decorations to be applied to the line of the item in the picker.
+   * Decorations applied to the item's line in the picker.
    *
-   * These decorations highlight the matched part of the item, or are used for better visualization.
-   * Developers should respect existing `decorations` and extend them.
+   * These decorations highlight matched parts or improve visualization.
+   * Developers should respect and extend existing `decorations`.
    *
-   * Note: If `highlight` is not specified, the picker will use the default highlight group
-   * for highlighting the matched part.
+   * Note: If `highlight` is unspecified, the picker uses a default highlight
+   * group to emphasize matched parts.
    */
   decorations: readonly ItemDecoration[];
 };
 
+/**
+ * An item used for previewing content in the picker.
+ */
 export type PreviewItem = {
   /**
-   * The content to preview.
+   * Content to preview.
    */
   readonly content: string[];
   /**
-   * The line number to jump to.
+   * Line number to jump to.
    */
   readonly line?: number;
   /**
-   * The column number to jump to.
+   * Column number to jump to.
    */
   readonly column?: number;
   /**
-   * The filetype used for highlighting.
+   * Filetype for syntax highlighting.
    */
   readonly filetype?: string;
   /**
-   * The filename used in the buffer name.
+   * Filename displayed in the buffer name.
    */
   readonly filename?: string;
 };
 
+/**
+ * Decoration applied to an item's line in the picker.
+ */
 export type ItemDecoration = {
   /**
-   * Column number (bytes)
+   * Column number (in bytes).
    */
   readonly column: number;
   /**
-   * Length (bytes)
+   * Length of the decoration (in bytes).
    */
   readonly length: number;
   /**
-   * Highlight name
+   * Name of the highlight group.
    */
   readonly highlight?: string;
 };

matcher.ts

@@ -1,25 +1,31 @@
 import type { Denops } from "@denops/std";
-
 import type { IdItem } from "./item.ts";
 
+/**
+ * Parameters for matching items.
+ */
 export type MatchParams<T> = {
   /**
-   * User input query.
+   * User input query for filtering.
    */
   readonly query: string;
   /**
-   * Items to match.
+   * Array of items to match against the query.
    */
   readonly items: readonly IdItem<T>[];
 };
 
+/**
+ * Matcher that filters items based on user input.
+ */
 export type Matcher<T> = {
   /**
-   * Match items.
+   * Matches items against the provided query.
    *
-   * @param denops Denops instance.
-   * @param params Parameters to match items.
-   * @param options Options.
+   * @param denops - The Denops instance.
+   * @param params - Parameters for matching items.
+   * @param options - Additional options, including an abort signal.
+   * @returns An async iterator over matched `IdItem` elements.
    */
   match(
     denops: Denops,