docs: standardize param and returns documentation across files

Author: devin-ai-integration[bot]

browser/dom/_internal.ts

@@ -25,7 +25,7 @@ export const encode = (
  * - `0`: returns `undefined`
  *
  * @param encoded The number containing encoded {@linkcode AddEventListenerOptions} flags
- * @returns An {@linkcode AddEventListenerOptions} object or `undefined` if encoded value is 0
+ * @returns An {@linkcode AddEventListenerOptions} object or {@linkcode undefined} if encoded value is 0
  */
 export const decode = (
   encoded: number,

browser/dom/cache.ts

@@ -7,9 +7,9 @@
  * > Implementation inspired by Scrapbox's ServiceWorker and Cache usage pattern.
  * > For details, see the article "ServiceWorker and Cache Usage in Scrapbox" {@see https://scrapbox.io/daiiz/ScrapboxでのServiceWorkerとCacheの活用#5d2efaffadf4e70000651173}
  *
- * @param request The request to find a cached response for
- * @param options Cache query options (e.g., to ignore search params)
- * @return The cached response if found, otherwise `undefined`
+ * @param request - The {@linkcode Request} to find a cached response for
+ * @param options - {@linkcode CacheQueryOptions} (e.g., to ignore search params)
+ * @returns A {@linkcode Response} if found, otherwise {@linkcode undefined}
  */
 export const findLatestCache = async (
   request: Request,
@@ -26,8 +26,8 @@ export const findLatestCache = async (
 
 /** Saves a response to the REST API cache storage managed by scrapbox.io
  *
- * @param request The request to associate with the cached response
- * @param response The response to cache
+ * @param request The {@linkcode Request} to associate with the cached response
+ * @param response The {@linkcode Response} to cache
  */
 export const saveApiCache = async (
   request: Request,

browser/dom/caret.ts

@@ -39,8 +39,10 @@ interface ReactFiber {
 
 /** Retrieves the current cursor position and text selection information
  *
- * @return Information about cursor position and text selection
- * @throws {Error} When `#text-input` element or React Component's internal properties are not found
+ * @returns A {@linkcode CaretPosition} containing cursor position and text selection information
+ * @throws {@linkcode Error} when:
+ *         - `#text-input` element is not found
+ *         - React Component's internal properties are not found
  * @see {@linkcode CaretInfo} for return type details
  */
 export const caret = (): CaretInfo => {

browser/dom/cursor.d.ts

@@ -1,17 +1,23 @@
+/** @module cursor */
 import { type BaseLine, BaseStore } from "@cosense/types/userscript";
 import type { Position } from "./position.ts";
 import type { Page } from "./page.d.ts";
 
+/** Options for setting cursor position
+ * @interface
+ */
 export interface SetPositionOptions {
   /** Whether to auto-scroll the page when the cursor moves outside the viewport
    *
    * @default true
+   * @type {boolean}
    */
   scrollInView?: boolean;
 
   /** Source of the cursor movement event
    *
    * `"mouse"` indicates the cursor was moved by mouse interaction
+   * @type {"mouse"}
    */
   source?: "mouse";
 }
@@ -20,6 +26,7 @@ export interface SetPositionOptions {
  *
  * @see {@linkcode Position} for cursor position type details
  * @see {@linkcode Page} for page data type details
+ * @extends {@linkcode BaseStore}<{ source: "mouse" | undefined } | "focusTextInput" | "scroll" | undefined>
  */
 export declare class Cursor extends BaseStore<
   { source: "mouse" | undefined } | "focusTextInput" | "scroll" | undefined
@@ -31,13 +38,24 @@ export declare class Cursor extends BaseStore<
   /** Reset cursor position and remove cursor focus from the editor */
   clear(): void;
 
-  /** Get the current cursor position */
+  /** Get the current cursor position
+   * @returns A {@linkcode Position} containing:
+   *          - Success: The current cursor coordinates and line information
+   *          - Error: Never throws or returns an error
+   */
   getPosition(): Position;
 
-  /** Check if the cursor is currently visible */
+  /** Check if the cursor is currently visible
+   * @returns A {@linkcode boolean} indicating:
+   *          - Success: `true` if the cursor is visible, `false` otherwise
+   *          - Error: Never throws or returns an error
+   */
   getVisible(): boolean;
 
-  /** Move the cursor to the specified position */
+  /** Move the cursor to the specified position
+   * @param position - The target position to move the cursor to
+   * @param option - Optional settings for the cursor movement. See {@linkcode SetPositionOptions}
+   */
   setPosition(
     position: Position,
     option?: SetPositionOptions,
@@ -67,10 +85,18 @@ export declare class Cursor extends BaseStore<
   /** Adjust cursor position to stay within valid line and column boundaries */
   fixPosition(): void;
 
-  /** Returns `true` if the cursor is visible and at the start of a line */
+  /** Check if the cursor is at the start of a line
+   * @returns A {@linkcode boolean} indicating:
+   *          - Success: `true` if the cursor is visible and at line start, `false` otherwise
+   *          - Error: Never throws or returns an error
+   */
   isAtLineHead(): boolean;
 
-  /** Returns `true` if the cursor is visible and at the end of a line */
+  /** Check if the cursor is at the end of a line
+   * @returns A {@linkcode boolean} indicating:
+   *          - Success: `true` if the cursor is visible and at line end, `false` otherwise
+   *          - Error: Never throws or returns an error
+   */
   isAtLineTail(): boolean;
 
   /** Make the cursor visible
@@ -87,6 +113,7 @@ export declare class Cursor extends BaseStore<
 
   /** Cursor movement commands
    *
+   * @param action - The movement command to execute. Available commands:
    * | Command | Description |
    * | ------ | ----------- |
    * | go-up | Move cursor up one line |
@@ -122,10 +149,18 @@ export declare class Cursor extends BaseStore<
       | "go-pageup",
   ): void;
 
-  /** Get the content of the current page */
+  /** Get the content of the current page
+   * @returns An array of {@linkcode BaseLine} objects containing:
+   *          - Success: The current page's content as an array of line objects
+   *          - Error: Never throws or returns an error
+   */
   get lines(): BaseLine[];
 
-  /** Get the current page data */
+  /** Get the current page data
+   * @returns A {@linkcode Page} object containing:
+   *          - Success: The current page's metadata and content
+   *          - Error: Never throws or returns an error
+   */
   get page(): Page;
 
   private goUp(): void;
@@ -134,7 +169,16 @@ export declare class Cursor extends BaseStore<
   private goPageDown(): void;
   private getNextLineHead(): void;
   private getPrevLineTail(): void;
+  /** Move cursor backward one character
+   * @param init - Optional configuration object
+   * @param init.scrollInView - Whether to scroll the view to keep cursor visible
+   */
   private goBackward(init?: { scrollInView: boolean }): void;
+
+  /** Move cursor forward one character
+   * @param init - Optional configuration object
+   * @param init.scrollInView - Whether to scroll the view to keep cursor visible
+   */
   private goForward(init?: { scrollInView: boolean }): void;
   private goLeft(): void;
   private goRight(): void;
@@ -143,8 +187,18 @@ export declare class Cursor extends BaseStore<
   /** Jump to the end of the last line */
   private goBottom(): void;
   private goWordHead(): void;
+  /** Get the position of the next word's start
+   * @returns A {@linkcode Position} containing:
+   *          - Success: The coordinates and line information of the next word's start
+   *          - Error: Never throws or returns an error
+   */
   private getWordHead(): Position;
   private goWordTail(): void;
+  /** Get the position of the previous word's end
+   * @returns A {@linkcode Position} containing:
+   *          - Success: The coordinates and line information of the previous word's end
+   *          - Error: Never throws or returns an error
+   */
   private getWordTail(): Position;
   /** Jump to the position after indentation
    *

browser/dom/extractCodeFiles.ts

@@ -37,8 +37,10 @@ export interface CodeBlock {
 
 /** Extract code blocks from {@linkcode scrapbox.Page.lines}
  *
- * @param lines Page lines to process
- * @return A Map of source code files with filename as key
+ * @param lines - Page lines to process
+ * @returns A {@linkcode Map}<{@linkcode string}, {@linkcode string}> containing:
+ *          - Key: The filename
+ *          - Value: The source code content
  */
 export const extractCodeFiles = (
   lines: Iterable<Line>,

browser/dom/motion.ts

@@ -19,7 +19,7 @@ import { range } from "../../range.ts";
  *
  * This function is specifically for mobile version of Scrapbox
  *
- * @param [holding=1000] Duration of long press in milliseconds
+ * @param [holding=1000] - Duration of long press in milliseconds
  */
 export const focusEnd = async (holding = 1000): Promise<void> => {
   const target = getLineDOM(caret().position.line)
@@ -35,7 +35,7 @@ export const focusEnd = async (holding = 1000): Promise<void> => {
 
 /** Move the cursor left using `ArrowLeft` key
  *
- * @param [count=1] Number of moves to perform
+ * @param [count=1] - Number of moves to perform
  */
 export const moveLeft = (count = 1): void => {
   for (const _ of range(0, count)) {
@@ -44,7 +44,7 @@ export const moveLeft = (count = 1): void => {
 };
 /** Move the cursor up using `ArrowUp` key
  *
- * @param [count=1] Number of moves to perform
+ * @param [count=1] - Number of moves to perform
  */
 export const moveUp = (count = 1): void => {
   for (const _ of range(0, count)) {
@@ -53,7 +53,7 @@ export const moveUp = (count = 1): void => {
 };
 /** Move the cursor down using `ArrowDown` key
  *
- * @param [count=1] Number of moves to perform
+ * @param [count=1] - Number of moves to perform
  */
 export const moveDown = (count = 1): void => {
   for (const _ of range(0, count)) {
@@ -62,7 +62,7 @@ export const moveDown = (count = 1): void => {
 };
 /** Move the cursor right using `ArrowRight` key
  *
- * @param [count=1] Number of moves to perform
+ * @param [count=1] - Number of moves to perform
  */
 export const moveRight = (count = 1): void => {
   for (const _ of range(0, count)) {
@@ -109,7 +109,7 @@ export const goLastLine = async (): Promise<void> => {
 };
 /** Move to the end of a specified line
  *
- * @param value Target line number, line ID, or {@linkcode HTMLElement}
+ * @param value - Target line number, line ID, or {@linkcode HTMLElement}
  */
 export const goLine = async (
   value: string | number | HTMLElement | undefined,
@@ -129,8 +129,8 @@ const _goLine = async (target: HTMLDivElement | undefined) => {
  *
  * Note: This operation will fail if attempting to move to characters that cannot be clicked in the UI
  *
- * @param line Target line (can be line number, line ID, or line DOM element)
- * @param pos Character position (column) in the target line
+ * @param line - Target line (can be line number, line ID, or line DOM element)
+ * @param pos - Character position (column) in the target line
  */
 export const goChar = async (
   line: string | number | HTMLElement,
@@ -162,7 +162,7 @@ const getVisibleLineCount = (): number => {
 
 /** Scroll half a page up
  *
- * @param [count=1] Number of scroll operations to perform
+ * @param [count=1] - Number of scroll operations to perform
  */
 export const scrollHalfUp = async (count = 1): Promise<void> => {
   const lineNo = getLineNo(caret().position.line);
@@ -176,7 +176,7 @@ export const scrollHalfUp = async (count = 1): Promise<void> => {
 };
 /** Scroll half a page down
  *
- * @param [count=1] Number of scroll operations to perform
+ * @param [count=1] - Number of scroll operations to perform
  */
 export const scrollHalfDown = async (count = 1): Promise<void> => {
   const lineNo = getLineNo(caret().position.line);
@@ -190,7 +190,7 @@ export const scrollHalfDown = async (count = 1): Promise<void> => {
 };
 /** Scroll one page up using `PageUp` key
  *
- * @param [count=1] Number of scroll operations to perform
+ * @param [count=1] - Number of scroll operations to perform
  */
 export const scrollUp = (count = 1): void => {
   for (const _ of range(0, count)) {
@@ -199,7 +199,7 @@ export const scrollUp = (count = 1): void => {
 };
 /** Scroll one page down using `PageDown` key
  *
- * @param [count=1] Number of scroll operations to perform
+ * @param [count=1] - Number of scroll operations to perform
  */
 export const scrollDown = (count = 1): void => {
   for (const _ of range(0, count)) {

browser/dom/open.ts

@@ -17,7 +17,7 @@ export interface OpenOptions {
    * - `true`: open in a new tab
    * - `false`: open in the same tab
    *
-   * @default {false}
+   * @default false
    */
   newTab?: boolean;
 
@@ -33,9 +33,9 @@ export interface OpenOptions {
 
 /** Open a page
  *
- * @param project Project name of the page to open
- * @param title Title of the page to open
- * @param options Configuration options for opening the page
+ * @param project - Project name of the page to open
+ * @param title - Title of the page to open
+ * @param options - Configuration options for opening the page
  */
 export const open = (
   project: string,
@@ -78,9 +78,9 @@ export const open = (
  *
  * The page will not be reloaded when opened
  *
- * @param project Project name of the page to open
- * @param title Title of the page to open
- * @param [body] Text to append to the page
+ * @param project - Project name of the page to open
+ * @param title - Title of the page to open
+ * @param [body] - Text to append to the page
  */
 export const openInTheSameTab = (
   project: string,

browser/dom/page.d.ts

@@ -5,7 +5,7 @@ export interface SetPositionOptions {
   /** Whether to auto-scroll the page when the cursor moves outside the viewport
    * When `true`, the page will automatically scroll to keep the cursor visible
    *
-   * @default {true}
+   * @default true
    */
   scrollInView?: boolean;
 

browser/dom/press.ts

@@ -16,8 +16,8 @@ export interface PressOptions {
  * > This function appears to block synchronously until Scrapbox's event listeners
  * finish processing the keyboard event.
  *
- * @param key The name of the key to simulate pressing
- * @param pressOptions Additional options for the key press (modifiers, etc.)
+ * @param key - The name of the key to simulate pressing
+ * @param pressOptions - Additional options for the key press (modifiers, etc.)
  */
 export const press = (
   key: KeyName,

browser/dom/selection.d.ts

@@ -22,7 +22,7 @@ export declare class Selection extends BaseStore<undefined> {
    *
    * @param init Set `init.normalizeOrder` to `true` to ensure Range.start is
    *            the beginning of the selection (useful for consistent text processing)
-   * @return The current selection range
+   * @returns The current {@linkcode Range} object representing the selection
    */
   getRange(init?: { normalizeOrder: boolean }): Range;
 
@@ -34,8 +34,8 @@ export declare class Selection extends BaseStore<undefined> {
 
   /** Normalize the selection range order to ensure start position comes before end
    *
-   * @param range The selection range to normalize
-   * @return The normalized range with start position at the beginning
+   * @param range - The selection range to normalize
+   * @returns A normalized {@linkcode Range} with start position at the beginning
    *
    * This is useful when you need consistent text processing regardless of
    * whether the user selected text from top-to-bottom or bottom-to-top.