docs: Improve documentation comments

Author: lambdalisue

action.ts

@@ -5,10 +5,10 @@ import type { Promish } from "./util/_typeutil.ts";
 import { type DerivableArray, deriveArray } from "./util/derivable.ts";
 
 /**
- * Define an action.
+ * Defines an action.
  *
- * @param invoke The function to invoke the action.
- * @returns The action.
+ * @param invoke - The function to invoke the action.
+ * @returns The defined action.
  */
 export function defineAction<T>(
   invoke: (
@@ -23,11 +23,11 @@ export function defineAction<T>(
 }
 
 /**
- * Compose multiple actions.
+ * Composes multiple actions.
  *
- * The actions are invoked in the order they are passed.
+ * The actions are invoked sequentially in the order they are passed.
  *
- * @param actions The actions to compose.
+ * @param actions - The actions to compose.
  * @returns The composed action.
  */
 export function composeActions<

builtin/action/buffer.ts

@@ -8,6 +8,12 @@ type Detail = {
   path: string;
 };
 
+/**
+ * Retrieves the appropriate attribute (either `bufname` or `path`) from the item's detail.
+ *
+ * @param item - The item containing either a `bufname` or a `path`.
+ * @returns The `path` if present; otherwise, the `bufname`.
+ */
 function attrGetter({ detail }: IdItem<Detail>): string {
   if ("path" in detail) {
     return detail.path;
@@ -16,6 +22,9 @@ function attrGetter({ detail }: IdItem<Detail>): string {
   }
 }
 
+/**
+ * Unloads the buffer without deleting it.
+ */
 export const bunload: Action<Detail> = cmd({
   attrGetter,
   immediate: true,
@@ -24,6 +33,9 @@ export const bunload: Action<Detail> = cmd({
   fnameescape: true,
 });
 
+/**
+ * Deletes the buffer, removing it from the buffer list.
+ */
 export const bdelete: Action<Detail> = cmd({
   attrGetter,
   immediate: true,
@@ -32,6 +44,9 @@ export const bdelete: Action<Detail> = cmd({
   fnameescape: true,
 });
 
+/**
+ * Wipes out the buffer, clearing it from memory.
+ */
 export const bwipeout: Action<Detail> = cmd({
   attrGetter,
   immediate: true,
@@ -40,6 +55,9 @@ export const bwipeout: Action<Detail> = cmd({
   fnameescape: true,
 });
 
+/**
+ * Opens the buffer in a new tab, writes any changes, and then closes the tab.
+ */
 export const write: Action<Detail> = cmd({
   attrGetter,
   immediate: true,
@@ -48,6 +66,9 @@ export const write: Action<Detail> = cmd({
   fnameescape: true,
 });
 
+/**
+ * A collection of default actions for buffer management.
+ */
 export const defaultBufferActions: {
   bunload: Action<Detail>;
   bdelete: Action<Detail>;

builtin/action/cd.ts

@@ -8,14 +8,19 @@ type Detail = {
   bufname: string;
 };
 
+/**
+ * Retrieves the appropriate attribute (`path` or `bufname`) from the item's detail.
+ *
+ * @param item - The item containing either a `path` or a `bufname`.
+ * @returns The `path` if present; otherwise, the `bufname`.
+ */
 function attrGetter({ detail }: IdItem<Detail>): string {
-  if ("path" in detail) {
-    return detail.path;
-  } else {
-    return detail.bufname;
-  }
+  return "path" in detail ? detail.path : detail.bufname;
 }
 
+/**
+ * Changes the current working directory globally to the specified path.
+ */
 export const cd: Action<Detail> = cmd({
   attrGetter,
   immediate: true,
@@ -24,6 +29,9 @@ export const cd: Action<Detail> = cmd({
   fnameescape: true,
 });
 
+/**
+ * Changes the current working directory locally for the window to the specified path.
+ */
 export const lcd: Action<Detail> = cmd({
   attrGetter,
   immediate: true,
@@ -32,6 +40,9 @@ export const lcd: Action<Detail> = cmd({
   fnameescape: true,
 });
 
+/**
+ * Changes the current working directory locally for the tab to the specified path.
+ */
 export const tcd: Action<Detail> = cmd({
   attrGetter,
   immediate: true,
@@ -40,6 +51,9 @@ export const tcd: Action<Detail> = cmd({
   fnameescape: true,
 });
 
+/**
+ * A collection of default actions for changing directories.
+ */
 export const defaultCdActions: {
   cd: Action<Detail>;
   lcd: Action<Detail>;

builtin/action/cmd.ts

@@ -9,38 +9,66 @@ import { type Action, defineAction } from "../../action.ts";
 type Restriction = "file" | "directory" | "directory-or-parent" | "buffer";
 
 type Options<T> = {
+  /**
+   * Function to retrieve the attribute from an item. Defaults to `item.value`.
+   */
   attrGetter?: (item: IdItem<T>) => string | undefined;
+  /**
+   * Executes the command immediately without prompting.
+   */
   immediate?: boolean;
+  /**
+   * Template for the command, with `{}` as a placeholder for the attribute.
+   */
   template?: string;
+  /**
+   * Restriction on the type of items to process (e.g., only files or directories).
+   */
   restriction?: Restriction;
+  /**
+   * Escapes the filename if true.
+   */
   fnameescape?: boolean;
+  /**
+   * Escapes the value for shell execution if true.
+   */
   shellescape?: boolean;
 };
 
+/**
+ * Creates an action that executes a command based on specified options.
+ *
+ * @param options - Configuration options for the command execution.
+ * @returns An action that executes the command.
+ */
 export function cmd<T>(options: Options<T> = {}): Action<T> {
   const attrGetter = options.attrGetter ?? ((item) => item.value);
   const immediate = options.immediate ?? false;
   const template = options.template ?? "{}";
   const restriction = options.restriction;
   const fnameescape = options.fnameescape ?? false;
   const shellescape = options.shellescape ?? false;
+
   return defineAction<T>(
     async (denops, { item, selectedItems }, { signal }) => {
       const items = selectedItems ?? [item];
       for (const item of items.filter((v) => !!v)) {
         signal?.throwIfAborted();
         let value = attrGetter(item);
         if (value == undefined) continue;
+
         if (restriction) {
           value = await applyRestriction(denops, value, restriction);
           if (value == undefined) continue;
         }
+
         if (fnameescape) {
           value = await fn.fnameescape(denops, value);
         }
         if (shellescape) {
           value = await fn.shellescape(denops, value);
         }
+
         const cmd = template.replaceAll("{}", value);
         try {
           await execute(denops, cmd, immediate);
@@ -52,6 +80,14 @@ export function cmd<T>(options: Options<T> = {}): Action<T> {
   );
 }
 
+/**
+ * Applies a restriction to an item, ensuring it meets the specified criteria.
+ *
+ * @param denops - The Denops instance.
+ * @param value - The item to check.
+ * @param restriction - The restriction type to enforce.
+ * @returns The original or modified value if it meets the restriction, otherwise `undefined`.
+ */
 async function applyRestriction(
   denops: Denops,
   value: string,
@@ -65,37 +101,36 @@ async function applyRestriction(
         const stat = await Deno.stat(value);
         switch (restriction) {
           case "file":
-            if (stat.isFile) {
-              return value;
-            }
+            if (stat.isFile) return value;
             break;
           case "directory":
-            if (stat.isDirectory) {
-              return value;
-            }
+            if (stat.isDirectory) return value;
             break;
           case "directory-or-parent":
-            if (!stat.isDirectory) {
-              value = dirname(value);
-            }
+            if (!stat.isDirectory) value = dirname(value);
             return value;
         }
       } catch (err) {
-        if (!(err instanceof Deno.errors.NotFound)) {
-          throw err;
-        }
+        if (!(err instanceof Deno.errors.NotFound)) throw err;
       }
       return;
     }
     case "buffer": {
-      if (!await fn.bufloaded(denops, value)) {
-        return;
+      if (await fn.bufloaded(denops, value)) {
+        return value;
       }
-      return value;
+      return;
     }
   }
 }
 
+/**
+ * Executes a command in Denops. If immediate execution is disabled, prompts for confirmation.
+ *
+ * @param denops - The Denops instance.
+ * @param cmd - The command to execute.
+ * @param immediate - Whether to execute the command immediately.
+ */
 async function execute(
   denops: Denops,
   cmd: string,
@@ -107,12 +142,15 @@ async function execute(
     completion: "command",
   });
   if (command == null) {
-    // Cancelled
+    // Command was cancelled
     return;
   }
   await denops.cmd(command);
 }
 
+/**
+ * Default command actions.
+ */
 export const defaultCmdActions: {
   cmd: Action<unknown>;
 } = {

builtin/action/echo.ts

@@ -1,11 +1,21 @@
 import { type Action, defineAction } from "../../action.ts";
 
+/**
+ * Creates an action that logs the item to the console.
+ *
+ * This action serializes the item to a JSON string with indentation and logs it.
+ *
+ * @returns An action that logs the item.
+ */
 export function echo<T>(): Action<T> {
   return defineAction((_denops, { item }, _options) => {
     console.log(JSON.stringify(item, null, 2));
   });
 }
 
+/**
+ * Default action for echoing items to the console.
+ */
 export const defaultEchoActions: {
   echo: Action<unknown>;
 } = {

builtin/action/help.ts

@@ -7,18 +7,28 @@ type Detail = {
   lang?: string;
 };
 
+/**
+ * Constructs the help tag with an optional language suffix.
+ *
+ * @param item - The item containing help details.
+ * @returns The helptag string, with language suffix if available.
+ */
 function attrGetter({ detail }: IdItem<Detail>): string {
   return detail.lang ? `${detail.helptag}@${detail.lang}` : detail.helptag;
 }
 
-export const help: Action<Detail> = cmd(
-  {
-    attrGetter,
-    immediate: true,
-    template: "help {}",
-  },
-);
+/**
+ * Opens help documentation based on the helptag and optional language.
+ */
+export const help: Action<Detail> = cmd({
+  attrGetter,
+  immediate: true,
+  template: "help {}",
+});
 
+/**
+ * Default action for accessing help documentation.
+ */
 export const defaultHelpActions: {
   help: Action<Detail>;
 } = {

builtin/action/noop.ts

@@ -1,9 +1,19 @@
 import { type Action, defineAction } from "../../action.ts";
 
+/**
+ * Creates a no-operation (noop) action.
+ *
+ * This action performs no operation when invoked and is useful as a placeholder.
+ *
+ * @returns An action that does nothing.
+ */
 export function noop<T>(): Action<T> {
   return defineAction(() => {});
 }
 
+/**
+ * Default action set containing the noop action.
+ */
 export const defaultNoopActions: {
   noop: Action<unknown>;
 } = {