📝 Improve documentation comments

Author: lambdalisue

autocmd/types.ts

@@ -119,19 +119,19 @@ export type AutocmdEvent =
   | "WinNew"
   | "WinScrolled";
 
-type CommonOptions = {
+interface CommonOptions {
   group?: string;
-};
+}
 
-export type DefineOptions = CommonOptions & {
+export interface DefineOptions extends CommonOptions {
   once?: boolean;
   nested?: boolean;
-};
+}
 
 export type RemoveOptions = CommonOptions;
 
 export type ListOptions = CommonOptions;
 
-export type EmitOptions = CommonOptions & {
+export interface EmitOptions extends CommonOptions {
   nomodeline?: boolean;
-};
+}

batch/batch.ts

@@ -94,7 +94,7 @@ class BatchHelper implements Denops {
  *
  * ```typescript
  * import type { Denops } from "https://deno.land/x/denops_std@$MODULE_VERSION/mod.ts";
- * import { batch } from "./batch.ts";
+ * import { batch } from "https://deno.land/x/denops_std@$MODULE_VERSION/batch/mod.ts";
  *
  * export async function main(denops: Denops): Promise<void> {
  *   await batch(denops, async (denops) => {
@@ -110,7 +110,7 @@ class BatchHelper implements Denops {
  *
  * ```typescript
  * import type { Denops } from "https://deno.land/x/denops_std@$MODULE_VERSION/mod.ts";
- * import { batch } from "./batch.ts";
+ * import { batch } from "https://deno.land/x/denops_std@$MODULE_VERSION/batch/mod.ts";
  *
  * async function replace(denops: Denops, content: string): Promise<void> {
  *   await batch(denops, async (denops) => {
@@ -135,7 +135,7 @@ class BatchHelper implements Denops {
  *
  * ```typescript
  * import type { Denops } from "https://deno.land/x/denops_std@$MODULE_VERSION/mod.ts";
- * import { batch } from "./batch.ts";
+ * import { batch } from "https://deno.land/x/denops_std@$MODULE_VERSION/batch/mod.ts";
  *
  * export async function main(denops: Denops): Promise<void> {
  *   await batch(denops, async (denops) => {
@@ -154,8 +154,8 @@ class BatchHelper implements Denops {
  *
  * ```typescript
  * import type { Denops } from "https://deno.land/x/denops_std@$MODULE_VERSION/mod.ts";
- * import { batch } from "./batch.ts";
  * import * as lambda from "https://deno.land/x/denops_std@$MODULE_VERSION/lambda/mod.ts";
+ * import { batch } from "https://deno.land/x/denops_std@$MODULE_VERSION/batch/mod.ts";
  *
  * export async function main(denops: Denops): Promise<void> {
  *   await batch(denops, async (denops) => {

batch/collect.ts

@@ -87,7 +87,7 @@ class CollectHelper implements Denops {
  *
  * ```typescript
  * import type { Denops } from "https://deno.land/x/denops_std@$MODULE_VERSION/mod.ts";
- * import { collect } from "./collect.ts";
+ * import { collect } from "https://deno.land/x/denops_std@$MODULE_VERSION/batch/mod.ts";
  *
  * export async function main(denops: Denops): Promise<void> {
  *   const results = await collect(denops, (denops) => [
@@ -106,7 +106,7 @@ class CollectHelper implements Denops {
  *
  * ```typescript
  * import type { Denops } from "https://deno.land/x/denops_std@$MODULE_VERSION/mod.ts";
- * import { collect } from "./collect.ts";
+ * import { collect } from "https://deno.land/x/denops_std@$MODULE_VERSION/batch/mod.ts";
  *
  * export async function main(denops: Denops): Promise<void> {
  *   const results = await collect(denops, (denops) => {

batch/mod.ts

@@ -1,6 +1,28 @@
 /**
  * A module to provide `denops.batch()` helper functions
  *
+ * ```typescript
+ * import type { Denops } from "https://deno.land/x/denops_std@$MODULE_VERSION/mod.ts";
+ * import { batch, collect } from "https://deno.land/x/denops_std@$MODULE_VERSION/batch/mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   // Call multiple denops functions sequentially in a signle RPC call
+ *   await batch(denops, async (denops) => {
+ *     await denops.cmd("setlocal modifiable");
+ *     await denops.cmd("setlocal noswap");
+ *     await denops.cmd("setlocal nobackup");
+ *   });
+ *
+ *   // Call multiple denops functions sequentially and get the return values in a single RPC call
+ *   const results = await collect(denops, (denops) => [
+ *     denops.eval("&modifiable"),
+ *     denops.eval("&modified"),
+ *     denops.eval("&filetype"),
+ *   ]);
+ *   // results contains the value of modifiable, modified, and filetype
+ * }
+ * ```
+ *
  * @module
  */
 export * from "./batch.ts";

buffer/buffer.ts

@@ -223,7 +223,7 @@ export interface OpenResult {
  *
  * export async function main(denops: Denops): Promise<void> {
  *   await open(denops, "README.md");
- *   const bufnr = (await fn.bufnr(denops)) as number;
+ *   const bufnr = await fn.bufnr(denops);
  *   // ...
  *   // Reload the content of the `bufnr` buffer.
  *   await reload(denops, bufnr);
@@ -251,7 +251,7 @@ export async function reload(denops: Denops, bufnr: number): Promise<void> {
  *
  * export async function main(denops: Denops): Promise<void> {
  *   await open(denops, "README.md");
- *   const bufnr = (await fn.bufnr(denops)) as number;
+ *   const bufnr = await fn.bufnr(denops);
  *   const data = await Deno.readFile("README.md");
  *   const { content } = await decode(denops, bufnr, data);
  *   await replace(denops, bufnr, content);
@@ -315,7 +315,7 @@ export interface DecodeResult {
  *
  * export async function main(denops: Denops): Promise<void> {
  *   await open(denops, "README.md");
- *   const bufnr = (await fn.bufnr(denops)) as number;
+ *   const bufnr = await fn.bufnr(denops);
  *   // Append the content under the cursor position of the `bufnr` buffer
  *   await append(denops, bufnr, ["Hello", "World"]);
  * }
@@ -355,7 +355,7 @@ export interface AppendOptions {
  *
  * export async function main(denops: Denops): Promise<void> {
  *   await open(denops, "README.md");
- *   const bufnr = (await fn.bufnr(denops)) as number;
+ *   const bufnr = await fn.bufnr(denops);
  *   // Set the content of the `bufnr` buffer
  *   await replace(denops, bufnr, ["Hello", "World"]);
  * }
@@ -403,7 +403,7 @@ export interface ReplaceOptions {
  *
  * export async function main(denops: Denops): Promise<void> {
  *   await open(denops, "README.md");
- *   const bufnr = (await fn.bufnr(denops)) as number;
+ *   const bufnr = await fn.bufnr(denops);
  *   await fn.setbufvar(denops, bufnr, "&buftype", "nofile");
  *   await replace(denops, bufnr, ["Hello", "World"]);
  *   await concrete(denops, bufnr);
@@ -454,7 +454,7 @@ export async function concrete(
  *
  * export async function main(denops: Denops): Promise<void> {
  *   await open(denops, "README.md");
- *   const bufnr = (await fn.bufnr(denops)) as number;
+ *   const bufnr = await fn.bufnr(denops);
  *   // ...
  *   await ensure(denops, bufnr, async () => {
  *     await option.buftype.set(denops, "nofile");
@@ -510,7 +510,7 @@ export async function ensure<T>(
  *
  * export async function main(denops: Denops): Promise<void> {
  *   await open(denops, "README.md");
- *   const bufnr = (await fn.bufnr(denops)) as number;
+ *   const bufnr = await fn.bufnr(denops);
  *   // ...
  *   await modifiable(denops, bufnr, async () => {
  *     await fn.setline(denops, 1, ["Hello", "World"]);

buffer/decoration.ts

@@ -8,13 +8,21 @@ import { unreachable } from "https://deno.land/x/unreachable@v0.1.0/mod.ts";
 const cacheKey = "denops_std/buffer/decoration/vimDecorate/rs@1";
 
 export interface Decoration {
-  // Line number
+  /**
+   * Line number
+   */
   line: number;
-  // Column number (bytes)
+  /**
+   * Column number (bytes)
+   */
   column: number;
-  // Length (bytes)
+  /**
+   * Length (bytes)
+   */
   length: number;
-  // Highlight name
+  /**
+   * Highlight name
+   */
   highlight: string;
 }
 

buffer/mod.ts

@@ -1,6 +1,55 @@
 /**
  * A module to provide Vim buffer utility functions
  *
+ * ```typescript
+ * import type { Denops } from "https://deno.land/x/denops_std@$MODULE_VERSION/mod.ts";
+ * import * as fn from "https://deno.land/x/denops_std@$MODULE_VERSION/function/mod.ts";
+ * import * as buffer from "https://deno.land/x/denops_std@$MODULE_VERSION/buffer/mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   // Open `README.md`
+ *   // Same as `:edit README.md`
+ *   await buffer.open(denops, "README.md");
+ *
+ *   // Open `LICENSE` with given options
+ *   // Same as `:keepjumps keepalt edit ++enc=sjis ++ff=dos LICENSE`
+ *   await buffer.open(denops, "LICENSE", {
+ *     mods: "keepjumps keepalt",
+ *     cmdarg: "++enc=sjis ++ff=dos",
+ *   });
+ *
+ *   const bufnr = await fn.bufnr(denops);
+ *
+ *   // Append the content under the cursor position of the `bufnr` buffer
+ *   await buffer.append(denops, bufnr, ["Hello", "World"]);
+ *
+ *   // Set the content of the `bufnr` buffer
+ *   await buffer.replace(denops, bufnr, ["Hello", "World"]);
+ *
+ *   // Concrete the buffer.
+ *   // - The `buftype` option become "nofile"
+ *   // - The `swapfile` become disabled
+ *   // - The `modifiable` become disabled
+ *   // - The content of the buffer is restored on `BufReadCmd` synchronously
+ *   await buffer.concrete(denops, bufnr);
+ *
+ *   // Decorate the specified buffer with decorations
+ *   await buffer.decorate(denops, bufnr, [
+ *     {
+ *       line: 1,
+ *       column: 1,
+ *       length: 10,
+ *       highlight: "Special",
+ *     },
+ *     {
+ *       line: 2,
+ *       column: 2,
+ *       length: 3,
+ *       highlight: "Comment",
+ *     },
+ *   ]);
+ * }
+ * ```
  * @module
  */
 export * from "./buffer.ts";

bufname/bufname.ts

@@ -45,13 +45,21 @@ export type BufnameParams = Record<string, string | string[] | undefined>;
  * ```
  */
 export interface Bufname {
-  // Scheme part of a buffer name. Note that Vim supports only alphabets in scheme part.
+  /**
+   * Scheme part of a buffer name. Note that Vim supports only alphabets in scheme part.
+   */
   scheme: string;
-  // Expression part of a buffer name. Note that '<>|?*' are not supported in Vim on Windows.
+  /**
+   * Expression part of a buffer name. Note that '<>|?*' are not supported in Vim on Windows.
+   */
   expr: string;
-  // Params part of a buffer name. While '?' is not supported, the params part are splitted by ';' instead.
+  /**
+   * Params part of a buffer name. While '?' is not supported, the params part are splitted by ';' instead.
+   */
   params?: BufnameParams;
-  // Fragment part of a buffer name. This is mainly used to regulate the suffix of the buffer name.
+  /**
+   * Fragment part of a buffer name. This is mainly used to regulate the suffix of the buffer name.
+   */
   fragment?: string;
 }
 
@@ -78,7 +86,7 @@ const exprPattern = /^(.*?)(?:;(.*?))?(?:#(.*))?$/;
  * percent-encoded characters. It's required to distinguish `params` and or `fragment`.
  *
  * ```typescript
- * import { assertEquals } from "https://deno.land/std@0.205.0/assert/mod.ts";
+ * import { assertEquals } from "https://deno.land/std@0.211.0/assert/mod.ts";
  * import { format } from "https://deno.land/x/denops_std@$MODULE_VERSION/bufname/mod.ts";
  *
  * assertEquals(
@@ -130,8 +138,8 @@ const exprPattern = /^(.*?)(?:;(.*?))?(?:#(.*))?$/;
  * constructing a buffer name from a real path. For example
  *
  * ```typescript
- * import { assertEquals } from "https://deno.land/std@0.205.0/assert/mod.ts";
- * import * as path from "https://deno.land/std/path/mod.ts";
+ * import { assertEquals } from "https://deno.land/std@0.211.0/assert/mod.ts";
+ * import * as path from "https://deno.land/std@0.211.0/path/mod.ts";
  * import { format } from "https://deno.land/x/denops_std@$MODULE_VERSION/bufname/mod.ts";
  *
  * // NOTE:
@@ -170,7 +178,7 @@ export function format(
  * For example, if it contains unusable characters ("<>|?*).
  *
  * ```typescript
- * import { assertEquals } from "https://deno.land/std@0.205.0/assert/mod.ts";
+ * import { assertEquals } from "https://deno.land/std@0.211.0/assert/mod.ts";
  * import { parse } from "https://deno.land/x/denops_std@$MODULE_VERSION/bufname/mod.ts";
  *
  * assertEquals(
@@ -224,8 +232,8 @@ export function format(
  * was constructed from a real path. For example
  *
  * ```typescript
- * import { assertEquals } from "https://deno.land/std@0.205.0/assert/mod.ts";
- * import * as path from "https://deno.land/std/path/mod.ts";
+ * import { assertEquals } from "https://deno.land/std@0.211.0/assert/mod.ts";
+ * import * as path from "https://deno.land/std@0.211.0/path/mod.ts";
  * import { parse } from "https://deno.land/x/denops_std@$MODULE_VERSION/bufname/mod.ts";
  *
  * const bufname = parse("denops:///C:/Users/John%2520Titor/test.git");

bufname/mod.ts

@@ -42,6 +42,59 @@
  *   scheme             expr                       params            fragment
  * ```
  *
+ * Developers can use `format` and `parse` functions like below:
+ *
+ * ```typescript
+ * import { assertEquals } from "https://deno.land/std@0.211.0/assert/mod.ts";
+ * import { format, parse } from "https://deno.land/x/denops_std@$MODULE_VERSION/bufname/mod.ts";
+ *
+ * // Format
+ * assertEquals(
+ *   format({
+ *     scheme: "denops",
+ *     expr: "/Users/John Titor/test.git",
+ *   }),
+ *   "denops:///Users/John Titor/test.git",
+ * );
+ * // Parse
+ * assertEquals(
+ *   parse("denops:///Users/John Titor/test.git"),
+ *   {
+ *     scheme: "denops",
+ *     expr: "/Users/John Titor/test.git",
+ *   },
+ * );
+ *
+ * // Format (complex)
+ * assertEquals(
+ *   format({
+ *     scheme: "denops",
+ *     expr: "/Users/John Titor/test.git",
+ *     params: {
+ *       foo: "foo",
+ *       bar: ["bar1", "bar2"],
+ *     },
+ *     fragment: "README.md",
+ *   }),
+ *   "denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2#README.md",
+ * );
+ * // Parse (complex)
+ * assertEquals(
+ *   parse(
+ *     "denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2#README.md",
+ *   ),
+ *   {
+ *     scheme: "denops",
+ *     expr: "/Users/John Titor/test.git",
+ *     params: {
+ *       foo: "foo",
+ *       bar: ["bar1", "bar2"],
+ *     },
+ *     fragment: "README.md",
+ *   },
+ * );
+ * ```
+ *
  * @module
  */
 export * from "./bufname.ts";