📝 Add documentation comments on mapping

Author: lambdalisue

denops_std/mapping/README.md

@@ -1,10 +1,15 @@
+/**
+ * A module to provide helper functions to manage mappings
+ *
+ * @module
+ */
 import type { Denops } from "https://deno.land/x/denops_core@v3.4.1/mod.ts";
 import * as fn from "../function/mod.ts";
 import * as batch from "../batch/mod.ts";
 import { Mapping, Mode } from "./types.ts";
 import { parse } from "./parser.ts";
 
-export type MapOptions = {
+export interface MapOptions {
   mode?: Mode | Mode[];
   noremap?: boolean;
   script?: boolean;
@@ -13,10 +18,35 @@ export type MapOptions = {
   nowait?: boolean;
   silent?: boolean;
   unique?: boolean;
-};
+}
 
 /**
  * Register a mapping for `lhs` to `rhs` with given options.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as mapping from "../mapping/mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   await mapping.map(denops, "<Plug>(test-denops-std)", "Hello");
+ *   await mapping.map(denops, "<Plug>(test-denops-std)", "Hello", {
+ *     mode: "i",
+ *   });
+ * }
+ * ```
+ *
+ * Users can specify multiple `mode` value like:
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as mapping from "../mapping/mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   await mapping.map(denops, "<Plug>(test-denops-std)", "Hello", {
+ *     mode: ["n", "i", "x"],
+ *   });
+ * }
+ * ```
  */
 export async function map(
   denops: Denops,
@@ -41,13 +71,47 @@ export async function map(
   });
 }
 
-export type UnmapOptions = {
+export interface UnmapOptions {
   buffer?: boolean;
   mode?: Mode | Mode[];
-};
+}
 
 /**
  * Remove a mapping for `lhs`.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as mapping from "../mapping/mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   await mapping.map(denops, "<Plug>(test-denops-std)", "Hello");
+ *   await mapping.map(denops, "<Plug>(test-denops-std)", "Hello", {
+ *     mode: "i",
+ *   });
+ *
+ *   await mapping.unmap(denops, "<Plug>(test-denops-std)");
+ *   await mapping.unmap(denops, "<Plug>(test-denops-std)", {
+ *     mode: "i",
+ *   });
+ * }
+ * ```
+ *
+ * Users can specify multiple `mode` value like:
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as mapping from "../mapping/mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   await mapping.map(denops, "<Plug>(test-denops-std)", "Hello", {
+ *     mode: ["n", "i", "x"],
+ *   });
+ *
+ *   await mapping.unmap(denops, "<Plug>(test-denops-std)", {
+ *     mode: ["n", "i", "x"],
+ *   });
+ * }
+ * ```
  */
 export async function unmap(
   denops: Denops,
@@ -63,13 +127,30 @@ export async function unmap(
   });
 }
 
-export type ReadOptions = {
+export interface ReadOptions {
   mode?: Mode;
-};
+}
 
 /**
  * Read a mapping and return a `Mapping` instance.
  *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as mapping from "../mapping/mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   await denops.cmd(`map <Plug>(test-denops-std) Hello`);
+ *
+ *   console.log(await mapping.read(denops, "<Plug>(test-denops-std)"));
+ *   // {
+ *   //   mode: "",
+ *   //   lhs: "<Plug>(test-denops-std)",
+ *   //   rhs: "Hello",
+ *   //   // ...
+ *   // }
+ * }
+ * ```
+ *
  * Note that prior to Vim 8.2.0491 or Neovim 0.5.0, `script` is
  * not detectable by `maparg` function internally used in this
  * function.
@@ -104,12 +185,30 @@ export async function read(
   };
 }
 
-export type ListOptions = {
+export interface ListOptions {
   mode?: Mode;
-};
+}
 
 /**
  * List mappings which starts from `lhs`.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as mapping from "../mapping/mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   const result = await mapping.list(denops, "<Plug>");
+ *   console.log(result);
+ *   // [
+ *   //   {
+ *   //     mode: "",
+ *   //     lhs: "<Plug>(...)",
+ *   //     // ...
+ *   //   },
+ *   //   // ...
+ *   // ]
+ * }
+ * ```
  */
 export async function list(
   denops: Denops,

denops_std/mapping/mod.ts

@@ -20,7 +20,7 @@ export type Mode =
   | "nox"
   | "nos";
 
-export type Mapping = {
+export interface Mapping {
   // Modes for which the mapping is defined
   mode: Mode;
   // The {lhs} of the mapping
@@ -49,4 +49,4 @@ export type Mapping = {
   // True for a :map-silent mapping, else False
   // This attribute is missing if the Mapping is returned from `list()`
   silent?: boolean;
-};
+}