📝 Add documentation comments on batch

Author: lambdalisue

denops_std/batch/README.md

@@ -95,7 +95,95 @@ class BatchHelper implements Denops {
 }
 
 /**
- * Perform batch call
+ * Call multiple denops functions sequentially without RPC overhead
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { batch } from "./batch.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   await batch(denops, async (denops) => {
+ *     await denops.cmd("setlocal modifiable");
+ *     await denops.cmd("setlocal noswap");
+ *     await denops.cmd("setlocal nobackup");
+ *   });
+ * }
+ * ```
+ *
+ * The function can be nested thus users can use functions which may internally use
+ * `batch()` like:
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { batch } from "./batch.ts";
+ *
+ * async function replace(denops: Denops, content: string): Promise<void> {
+ *   await batch(denops, async (denops) => {
+ *     await denops.cmd("setlocal modifiable");
+ *     await denops.cmd("setlocal foldmethod=manual");
+ *     await denops.call("setline", 1, content.split(/\r?\n/));
+ *     await denops.cmd("setlocal nomodifiable");
+ *     await denops.cmd("setlocal nomodified");
+ *   });
+ * }
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   await batch(denops, async (denops) => {
+ *     await denops.cmd("edit Hello");
+ *     await replace(denops, "Hello Darkness My Old Friend");
+ *   });
+ * }
+ * ```
+ *
+ * Note that `denops.call()`, `denops.batch()`, or `denops.eval()` always return
+ * falsy value in `batch()`, indicating that you **cannot** write code like below:
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { batch } from "./batch.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   await batch(denops, async (denops) => {
+ *     // !!! DON'T DO THIS !!!
+ *     if (await denops.eval("&verbose")) {
+ *       await denops.cmd("echomsg 'VERBOSE'");
+ *     }
+ *     await denops.cmd("echomsg 'Hello world'");
+ *   });
+ * }
+ * ```
+ *
+ * The `denops` instance passed to the `batch` block is available even outside of
+ * the block. It works like a real `denops` instance, mean that you can write code
+ * like:
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { batch } from "./batch.ts";
+ * import * as anonymous from "../anonymous/mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   await batch(denops, async (denops) => {
+ *     const [id] = anonymous.add(denops, async () => {
+ *       // This code is called outside of 'batch' block
+ *       // thus the 'denops' instance works like a real one.
+ *       // That's why you can write code like below
+ *       if (await denops.eval("&verbose")) {
+ *         await denops.cmd("echomsg 'VERBOSE'");
+ *       }
+ *       await denops.cmd("echomsg 'Hello world'");
+ *     });
+ *     await denops.cmd(
+ *       `command! Test call denops#request('${denops.name}', '${id}', [])`,
+ *     );
+ *   });
+ * }
+ * ```
+ *
+ * Note that `denops.redraw()` is executed only once after the batch is actually
+ * executed, no matter how many times it is called in the `batch()`. If the `force`
+ * option is specified even once, the last call will be the one with the force
+ * option specified.
  */
 export async function batch(
   denops: Denops,

denops_std/batch/batch.ts

@@ -88,7 +88,50 @@ class GatherHelper implements Denops {
 }
 
 /**
- * Perform gather call
+ * Call multiple denops functions sequentially without RPC overhead and return values
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { gather } from "./gather.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   const results = await gather(denops, async (denops) => {
+ *     await denops.eval("&modifiable");
+ *     await denops.eval("&modified");
+ *     await denops.eval("&filetype");
+ *   });
+ *   // results contains the value of modifiable, modified, and filetype
+ * }
+ * ```
+ *
+ * Not like `batch`, the function can NOT be nested.
+ *
+ * Note that `denops.call()` or `denops.eval()` always return falsy value in
+ * `gather()`, indicating that you **cannot** write code like below:
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { gather } from "./gather.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   const results = await gather(denops, async (denops) => {
+ *     // !!! DON'T DO THIS !!!
+ *     if (await denops.call("has", "nvim")) {
+ *       // deno-lint-ignore no-explicit-any
+ *       await (denops.call("api_info") as any).version;
+ *     } else {
+ *       await denops.eval("v:version");
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * The `denops` instance passed to the `gather` block is NOT available outside of
+ * the block. An error is thrown when `denops.call()`, `denops.cmd()`, or
+ * `denops.eval()` is called.
+ *
+ * Note that `denops.redraw()` cannot be called within `gather()`. If it is called,
+ * an error is raised.
  */
 export async function gather(
   denops: Denops,

denops_std/batch/gather.ts

@@ -1,2 +1,7 @@
+/**
+ * A module to provide `denops.batch()` helper functions
+ *
+ * @module
+ */
 export * from "./batch.ts";
 export * from "./gather.ts";