Improve documentation across the project

README.md

@@ -16,11 +16,30 @@ colorscheme)</sup>
 
 </div>
 
-Fall is a fuzzy finder for Vim and Neovim, implemented in [Denops], and stands
-for **"Filter All."**
+Fall is a powerful, flexible fuzzy finder framework for Vim and Neovim,
+implemented in [Denops], and stands for **"Filter All."** It provides an
+extensible architecture that allows users to search, filter, and act on various
+data sources including files, buffers, lines, help tags, and more through a
+unified interface.
+
+## Key Features
+
+- **Extensible Architecture**: Modular design allows custom sources, matchers,
+  sorters, renderers, and previewers
+- **Interactive Interface**: Quick help via F1, real-time filtering, and action
+  selection
+- **Multiple Processing Stages**: Sophisticated pipeline with collection,
+  matching, sorting, rendering, and preview stages
+- **Session Management**: Save and resume picker sessions with `:FallSession`
+  and `:FallResume`
+- **Submatch Capabilities**: Refine searches with multiple filter criteria
+- **Performance Optimized**: Asynchronous processing with intelligent scheduling
+  and chunking
+- **Rich Customization**: Configure behavior through TypeScript extensions and
+  Vim script settings
 
 See [Features](https://github.com/vim-fall/fall.vim/wiki/Features) for more
-information about Fall's features.
+detailed information.
 
 > [!WARNING]
 >
@@ -62,16 +81,44 @@ following arguments:
 Fall {source} {source_args}...
 ```
 
-For example, if you'd like to use the `file` source, you can use the following:
+### Common Examples
 
-```
-Fall file
-```
+```vim
+" Find files in current directory
+:Fall file
 
-Or use the `line` source with `README.md` as an argument:
+" Find files in specific directory
+:Fall file /path/to/directory
 
-```
-Fall line README.md
+" Search file contents with grep
+:Fall grep
+
+" Search in git repository
+:Fall git-grep
+
+" Search with ripgrep (faster)
+:Fall rg
+
+" Filter lines in current buffer
+:Fall line
+
+" Filter lines in specific file
+:Fall line README.md
+
+" Switch between buffers
+:Fall buffer
+
+" Browse help tags
+:Fall help
+
+" Browse command history
+:Fall history
+
+" Resume previous picker
+:FallResume
+
+" Manage picker sessions
+:FallSession
 ```
 
 ### Mappings
@@ -103,14 +150,28 @@ Visit the
 [Customization](https://github.com/vim-fall/fall.vim/wiki/Customization) page on
 the GitHub Wiki for more information.
 
+## Architecture
+
+Fall follows a modular architecture with these core components:
+
+- **Sources**: Data providers (files, buffers, grep results, etc.)
+- **Matchers**: Filter algorithms (fuzzy, substring, regex)
+- **Sorters**: Result ordering strategies (alphabetical, length, score)
+- **Renderers**: Display formatters (with optional NerdFont icons)
+- **Previewers**: Content preview generators
+- **Actions**: Operations on selected items (open, edit, split, etc.)
+
+Components communicate through a well-defined pipeline, allowing for extensive
+customization and extension.
+
 ## Related Projects
 
-| Repository                                                                | Package                                               | Description                                      |
-| ------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------ |
-| [vim-fall/deno-fall-core](https://github.com/vim-fall/deno-fall-core)     | [`@vim-fall/core`](https://jsr.io/@vim-fall/core)     | Core types for Fall. Not meant for external use. |
-| [vim-fall/deno-fall-custom](https://github.com/vim-fall/deno-fall-custom) | [`@vim-fall/custom`](https://jsr.io/@vim-fall/custom) | Library to customize Fall.                       |
-| [vim-fall/deno-fall-std](https://github.com/vim-fall/deno-fall-std)       | [`@vim-fall/std`](https://jsr.io/@vim-fall/std)       | Standard library for using Fall.                 |
-| [vim-fall/deno-fall-extra](https://github.com/vim-fall/deno-fall-extra)   | [`@vim-fall/extra`](https://jsr.io/@vim-fall/extra)   | Extra library for using Fall.                    |
+| Repository                                                                | Package                                               | Description                                   |
+| ------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------- |
+| [vim-fall/deno-fall-core](https://github.com/vim-fall/deno-fall-core)     | [`@vim-fall/core`](https://jsr.io/@vim-fall/core)     | Core types and interfaces for Fall extensions |
+| [vim-fall/deno-fall-custom](https://github.com/vim-fall/deno-fall-custom) | [`@vim-fall/custom`](https://jsr.io/@vim-fall/custom) | Customization utilities and helpers           |
+| [vim-fall/deno-fall-std](https://github.com/vim-fall/deno-fall-std)       | [`@vim-fall/std`](https://jsr.io/@vim-fall/std)       | Standard built-in components                  |
+| [vim-fall/deno-fall-extra](https://github.com/vim-fall/deno-fall-extra)   | [`@vim-fall/extra`](https://jsr.io/@vim-fall/extra)   | Additional sources and extensions             |
 
 ## Similar Projects
 

denops/fall/component/help.ts

@@ -1,3 +1,20 @@
+/**
+ * @module component/help
+ *
+ * Help component for the vim-fall picker UI.
+ *
+ * This module provides the HelpComponent class which displays interactive help
+ * information to users. It supports:
+ *
+ * - Multi-page help content with navigation
+ * - Syntax highlighting through decorations
+ * - Dynamic content generation based on current mappings
+ * - Toggle visibility with F1 key
+ *
+ * The help component provides contextual assistance, showing available
+ * keyboard shortcuts and commands for the current picker.
+ */
+
 import type { Denops } from "jsr:@denops/std@^7.3.2";
 import type { Decoration } from "jsr:@denops/std@^7.3.2/buffer";
 import * as mapping from "jsr:@denops/std@^7.3.2/mapping";

denops/fall/component/input.ts

@@ -1,3 +1,13 @@
+/**
+ * @module component/input
+ *
+ * Input component for the vim-fall picker UI.
+ *
+ * This module provides the InputComponent class which manages the user input area
+ * of the picker. It displays the current query, cursor position, collection/processing
+ * status, and provides visual feedback through spinners and status indicators.
+ */
+
 import type { Denops } from "jsr:@denops/std@^7.3.2";
 import * as fn from "jsr:@denops/std@^7.3.2/function";
 import * as buffer from "jsr:@denops/std@^7.3.2/buffer";

denops/fall/component/list.ts

@@ -1,3 +1,20 @@
+/**
+ * @module component/list
+ *
+ * List component for the vim-fall picker UI.
+ *
+ * This module provides the ListComponent class which manages the main list area
+ * of the picker where filtered and rendered items are displayed. It handles:
+ *
+ * - Rendering items with syntax highlighting
+ * - Managing item selection with visual indicators
+ * - Executing commands on the list buffer
+ * - Handling decorations for match highlighting
+ *
+ * The list component works closely with the render processor to display
+ * items in a scrollable, interactive list format.
+ */
+
 import type { Denops } from "jsr:@denops/std@^7.3.2";
 import type { Decoration } from "jsr:@denops/std@^7.3.2/buffer";
 import { batch } from "jsr:@denops/std@^7.3.2/batch";

denops/fall/component/preview.ts

@@ -1,3 +1,20 @@
+/**
+ * @module component/preview
+ *
+ * Preview component for the vim-fall picker UI.
+ *
+ * This module provides the PreviewComponent class which displays previews of
+ * selected items in the picker. It supports:
+ *
+ * - Content preview with optional syntax highlighting
+ * - Cursor positioning at specific lines/columns
+ * - File type detection for proper highlighting
+ * - Command execution within the preview context
+ *
+ * The preview component enhances the user experience by showing item details
+ * before selection, making it easier to identify the desired item.
+ */
+
 import type { Denops } from "jsr:@denops/std@^7.3.2";
 import * as fn from "jsr:@denops/std@^7.3.2/function";
 import * as buffer from "jsr:@denops/std@^7.3.2/buffer";