Merge pull request #173 from vim-denops/fix-docs

📝 Improve documentation on deno doc

Author: lambdalisue

README.md

@@ -11,8 +11,8 @@
 used in denops plugin and the code is assumed to be called in a worker thread
 for a plugin.
 
-See [Module README](./denops_std/README.md) for quick usage and API
-documentations and see
+See [deno doc](https://doc.deno.land/https/deno.land/x/denops_std/mod.ts) for
+quick usage and API documentations and see
 [Denops Documentation](https://vim-denops.github.io/denops-documentation/) for
 learning how to write Vim/Neovim plugins.
 

denops_std/README.md

@@ -5,65 +5,7 @@
 [![Documentation](https://img.shields.io/badge/denops-Documentation-yellow.svg)](https://vim-denops.github.io/denops-documentation/)
 [![deno land](http://img.shields.io/badge/available%20on-deno.land/x/denops__std-lightgrey.svg?logo=deno)](https://deno.land/x/denops_std)
 
-[Deno][deno] module for [denops.vim][denops.vim]. This module is assumed to be
-used in denops plugin and the code is assumed to be called in a worker thread
-for a plugin.
-
-By using this module, developers can write Vim/Neovim denops plugins like:
-
-```typescript
-import { Denops } from "./mod.ts";
-import * as fn from "./function/mod.ts";
-import * as vars from "./variable/mod.ts";
-import * as helper from "./helper/mod.ts";
-
-import { assertString } from "https://deno.land/x/unknownutil/mod.ts";
-
-export async function main(denops: Denops): Promise<void> {
-  denops.dispatcher = {
-    async say(where: unknown): Promise<void> {
-      // Ensure that `where` is `string` here
-      assertString(where);
-      const name = await fn.input(denops, "Your name: ");
-      const progname = await vars.v.get(denops, "progname");
-      const messages = [
-        `Hello ${where}.`,
-        `Your name is ${name}.`,
-        `This is ${progname}.`,
-      ];
-      await helper.echo(denops, messages.join("\n"));
-    },
-  };
-
-  await helper.execute(
-    denops,
-    `
-    command! HelloWorld call denops#notify("${denops.name}", "say", ["World"])
-    command! HelloDenops call denops#notify("${denops.name}", "say", ["Denops"])
-    `,
-  );
-}
-```
-
-See [Denops Documentation](https://vim-denops.github.io/denops-documentation/)
-or [denops-helloworld.vim](https://github.com/vim-denops/denops-helloworld.vim)
-for more details.
+[Deno][deno] module for [denops.vim][denops.vim].
 
 [deno]: https://deno.land/
 [denops.vim]: https://github.com/vim-denops/denops.vim
-
-## Index
-
-| Name                       | Description                                                            |
-| -------------------------- | ---------------------------------------------------------------------- |
-| [`anonymous`](./anonymous) | A module to provide anonymous function                                 |
-| [`argument`](./argument)   | A module to provide helper functions to manage Vim's command arguments |
-| [`autocmd`](./autocmd)     | A module to provide helper functions to manage `autocmd`               |
-| [`batch`](./batch)         | A module to provide wrapper functions of `denops.batch()`              |
-| [`buffer`](./buffer)       | A module to provide helper functions to manage buffers                 |
-| [`bufname`](./bufname)     | A module to provide helper functions to manage Vim's buffer name       |
-| [`function`](./function)   | A module to provide functions of Vim and Neovim native functions       |
-| [`helper`](./helper)       | A module to provide helper functions                                   |
-| [`mapping`](./mapping)     | A module to provide helper functions to manage mappings                |
-| [`option`](./option)       | A module to provide helper functions to manage options                 |
-| [`variable`](./variable)   | A module to provide helper accessor functions to variables             |

denops_std/anonymous/README.md

@@ -1,3 +1,9 @@
+/**
+ * A module to provide anonymous function which is callable from
+ * outside of the plugin (Vim or other plugins.)
+ *
+ * @module
+ */
 import type { Denops } from "https://deno.land/x/denops_core@v3.4.1/mod.ts";
 
 // https://github.com/microsoft/TypeScript/issues/26223#issuecomment-674500430
@@ -19,7 +25,36 @@ export type Identifier = string;
 export type Callback = (...args: unknown[]) => Promise<unknown> | unknown;
 
 /**
- * Add anonymous functions as a denops API and return the identifiers
+ * Add anonymous functions as denops API and return the identifiers
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as anonymous from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   // Add anonymous functions
+ *   const ids = anonymous.add(
+ *     denops,
+ *     () => {
+ *       // Do what ever you want.
+ *     },
+ *     () => {
+ *       // Do what ever you want.
+ *     },
+ *     // You can add as many callbacks as you want...
+ *   );
+ *
+ *   // Use ids to dispatch added functions from Deno
+ *   await denops.dispatch(denops.name, ids[0]);
+ *   await denops.dispatch(denops.name, ids[1]);
+ *
+ *   // Or from Vim
+ *   await denops.cmd("call denops#notify(name, id, [])", {
+ *     name: denops.name,
+ *     id: ids[1],
+ *   });
+ * }
+ * ```
  */
 export function add<N extends number>(
   denops: Denops,
@@ -36,7 +71,33 @@ export function add<N extends number>(
 }
 
 /**
- * Add oneshot anonymous functions as a denops API and return the identifiers
+ * Add oneshot anonymous functions as denops API and return the identifiers
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as anonymous from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   // Add anonymous functions
+ *   const ids = anonymous.once(
+ *     denops,
+ *     () => {
+ *       // Do what ever you want.
+ *     },
+ *     () => {
+ *       // Do what ever you want.
+ *     },
+ *     // You can add as many callbacks as you want...
+ *   );
+ *
+ *   // First calls complete normally
+ *   await denops.dispatch(denops.name, ids[0]);
+ *   await denops.dispatch(denops.name, ids[1]);
+ *
+ *   // But second call would throw errors
+ *   await denops.dispatch(denops.name, ids[0]);
+ * }
+ * ```
  */
 export function once<N extends number>(
   denops: Denops,
@@ -57,7 +118,35 @@ export function once<N extends number>(
 }
 
 /**
- * Remove anonymous functions identified by names from a denops API
+ * Remove anonymous functions from denops API identified by the identifiers
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as anonymous from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   // Add anonymous functions
+ *   const ids = anonymous.add(
+ *     denops,
+ *     () => {
+ *       // Do what ever you want.
+ *     },
+ *     () => {
+ *       // Do what ever you want.
+ *     },
+ *     // You can add as many callbacks as you want...
+ *   );
+ *
+ *   // Remove ids[1]
+ *   anonymous.remove(denops, ids[1]);
+ *
+ *   // Call of ids[0] complete normally
+ *   await denops.dispatch(denops.name, ids[0]);
+ *
+ *   // But ids[1] is already removed
+ *   await denops.dispatch(denops.name, ids[1]);
+ * }
+ * ```
  */
 export function remove<N extends number>(
   denops: Denops,