📝 Add clear documentation for differences between batch functions

Author: Milly

batch/mod.ts

@@ -1,6 +1,39 @@
 /**
  * A module to provide `denops.batch()` helper functions
  *
+ * ## Functions Overview
+ *
+ * This module provides these functions for batching RPC calls, each serving different purposes:
+ *
+ * ### `batch()`
+ * - **Purpose**: Manual batching for side-effects only (commands, settings)
+ * - **Returns**: Always returns falsy values (void/undefined)
+ * - **Use case**: When you need to execute multiple commands/settings without needing return values
+ * - **Nesting**: Can be nested
+ * - **Best for**: Most efficient when return values aren't needed
+ *
+ * ### `collect()`
+ * - **Purpose**: Simple parallel value collection with type-safe returns
+ * - **Returns**: Array of return values with proper types
+ * - **Use case**: When you need to fetch multiple fixed values at once
+ * - **Nesting**: Cannot be nested
+ * - **Best for**: Cleanest API for fetching multiple values in parallel
+ *
+ * ### `accumulate()`
+ * - **Purpose**: Automatic batching for complex async flows with loops and conditions
+ * - **Returns**: Whatever the executor function returns
+ * - **Use case**: When you need natural async/await code with automatic RPC optimization
+ * - **Nesting**: Can be nested
+ * - **Best for**: Complex flows with dynamic branching, loops, or conditional logic
+ *
+ * ## Choosing the Right Function
+ *
+ * - Use `batch()` when you only need to execute commands/settings and don't need return values
+ * - Use `collect()` when you need to fetch multiple known values with clean, type-safe API
+ * - Use `accumulate()` when you have complex async logic with conditionals, loops, or dynamic flows
+ *
+ * ## Examples
+ *
  * ```typescript
  * import type { Entrypoint } from "jsr:@denops/std";
  * import * as fn from "jsr:@denops/std/function";