docs: translate Japanese comments in non-test files and refine doc strings

Author: devin-ai-integration[bot]

browser/dom/cache.ts

@@ -5,8 +5,7 @@
  *
  * > [!NOTE]
  * > Implementation inspired by Scrapbox's ServiceWorker and Cache usage pattern.
- * > {@see https://scrapbox.io/daiiz/ScrapboxでのServiceWorkerとCacheの活用#5d2efaffadf4e70000651173}
-
+ * > 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)

browser/dom/extractCodeFiles.ts

@@ -35,10 +35,10 @@ export interface CodeBlock {
   lines: string[];
 }
 
-/** `scrapbox.Page.lines`からcode blocksを取り出す
+/** Extract code blocks from {@linkcode scrapbox.Page.lines}
  *
- * @param lines ページの行
- * @return filenameをkeyにしたソースコードのMap
+ * @param lines Page lines to process
+ * @return A Map of source code files with filename as key
  */
 export const extractCodeFiles = (
   lines: Iterable<Line>,

browser/dom/motion.ts

@@ -33,66 +33,66 @@ export const focusEnd = async (holding = 1000): Promise<void> => {
   await holdDown(target, { X: right + 1, Y: top + height / 2, holding });
 };
 
-/** カーソルを左に動かす
+/** Move the cursor left using `ArrowLeft` key
  *
- * @param [count=1] 動かす回数
+ * @param [count=1] Number of moves to perform
  */
 export const moveLeft = (count = 1): void => {
   for (const _ of range(0, count)) {
     press("ArrowLeft");
   }
 };
-/** カーソルを上に動かす
+/** Move the cursor up using `ArrowUp` key
  *
- * @param [count=1] 動かす回数
+ * @param [count=1] Number of moves to perform
  */
 export const moveUp = (count = 1): void => {
   for (const _ of range(0, count)) {
     press("ArrowUp");
   }
 };
-/** カーソルを下に動かす
+/** Move the cursor down using `ArrowDown` key
  *
- * @param [count=1] 動かす回数
+ * @param [count=1] Number of moves to perform
  */
 export const moveDown = (count = 1): void => {
   for (const _ of range(0, count)) {
     press("ArrowDown");
   }
 };
-/** カーソルを右に動かす
+/** Move the cursor right using `ArrowRight` key
  *
- * @param [count=1] 動かす回数
+ * @param [count=1] Number of moves to perform
  */
 export const moveRight = (count = 1): void => {
   for (const _ of range(0, count)) {
     press("ArrowRight");
   }
 };
 
-/** インデントを除いた行頭に移動する */
+/** Move to the start of line excluding indentation */
 export const goHeadWithoutBlank = (): void => {
   press("End");
   press("Home");
 };
-/** 最後の非空白文字に移動する */
+/** Move to the last non-whitespace character */
 export const goEndWithoutBlank = (): void => {
   press("End");
   moveLeft(
     getText(caret().position.line)?.match?.(/(\s*)$/)?.[1]?.length ?? 0,
   );
 };
-/** 行頭に移動する */
+/** Move to the start of line */
 export const goHead = (): void => {
   press("Home");
   press("Home");
 };
-/** 行末に移動する */
+/** Move to the end of line */
 export const goEnd = (): void => {
   press("End");
 };
 
-/** 最初の行の行頭に移動する */
+/** Move to the start of the first line */
 export const goHeadLine = async (): Promise<void> => {
   const target = getHeadLineDOM();
   if (!target) throw Error(".line:first-of-type can't be found.");
@@ -103,13 +103,13 @@ export const goHeadLine = async (): Promise<void> => {
   const { left, top } = charDOM.getBoundingClientRect();
   await click(target, { X: left, Y: top });
 };
-/** 最後の行の行末に移動する */
+/** Move to the end of the last line */
 export const goLastLine = async (): Promise<void> => {
   await _goLine(getTailLineDOM());
 };
-/** 任意の行の行末に移動する
+/** Move to the end of a specified line
  *
- * @param value 移動したい行の行番号 or 行ID or 行のDOM
+ * @param value Target line number, line ID, or {@linkcode HTMLElement}
  */
 export const goLine = async (
   value: string | number | HTMLElement | undefined,
@@ -160,9 +160,9 @@ const getVisibleLineCount = (): number => {
   return Math.round(globalThis.innerHeight / clientHeight);
 };
 
-/** 半ページ上にスクロールする
+/** Scroll half a page up
  *
- * @param [count=1] スクロール回数
+ * @param [count=1] Number of scroll operations to perform
  */
 export const scrollHalfUp = async (count = 1): Promise<void> => {
   const lineNo = getLineNo(caret().position.line);
@@ -174,9 +174,9 @@ export const scrollHalfUp = async (count = 1): Promise<void> => {
   );
   await goLine(Math.max(index, 0));
 };
-/** 半ページ下にスクロールする
+/** Scroll half a page down
  *
- * @param [count=1] スクロール回数
+ * @param [count=1] Number of scroll operations to perform
  */
 export const scrollHalfDown = async (count = 1): Promise<void> => {
   const lineNo = getLineNo(caret().position.line);
@@ -188,18 +188,18 @@ export const scrollHalfDown = async (count = 1): Promise<void> => {
   );
   await goLine(Math.min(index, getLineCount() - 1));
 };
-/** 1ページ上にスクロールする
+/** Scroll one page up using `PageUp` key
  *
- * @param [count=1] スクロール回数
+ * @param [count=1] Number of scroll operations to perform
  */
 export const scrollUp = (count = 1): void => {
   for (const _ of range(0, count)) {
     press("PageUp");
   }
 };
-/** 1ページ下にスクロールする
+/** Scroll one page down using `PageDown` key
  *
- * @param [count=1] スクロール回数
+ * @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

@@ -31,11 +31,11 @@ export interface OpenOptions {
   context?: Omit<PageTransitionContext, "to">;
 }
 
-/** ページを開く
+/** Open a page
  *
- * @param project 開くページのproject名
- * @param title 開くページのタイトル
- * @param options
+ * @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,
@@ -74,13 +74,13 @@ export const open = (
   a.remove();
 };
 
-/** 同じタブでページを開く
+/** Open a page in the same tab
  *
- * このとき、ページは再読み込みされない
+ * The page will not be reloaded when opened
  *
- * @param project 開くページのproject名
- * @param title 開くページのタイトル
- * @param [body] ページに追記するテキスト
+ * @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/websocket/emit.ts

@@ -91,7 +91,7 @@ export const emit = <EventName extends keyof WrapperdEmitEvents>(
       reject(new Error("io client disconnect"));
       return;
     }
-    // 復帰不能なエラー
+    // Unrecoverable error state
     if (reason === "io server disconnect") {
       dispose();
       resolve(createErr({ name: "SocketIOError" }));

browser/websocket/updateCodeFile.ts

@@ -125,7 +125,7 @@ export const updateCodeFile = (
   title: string,
   options?: UpdateCodeFileOptions,
 ): Promise<Result<string, PushError>> => {
-  /** optionsの既定値はこの中に入れる */
+  /** Set default values for options here */
   const defaultOptions: Required<
     Omit<UpdateCodeFileOptions, "maxAttempts" | "socket">
   > = {
@@ -225,13 +225,13 @@ function* makeCommits(
   >[] = [..._codeBlocks];
   const codeBodies = flatCodeBodies(_codeBlocks);
   if (codeBlocks.length <= 0) {
-    // ページ内にコードブロックが無かった場合は新しく作成
+    // Create a new code block if none exists in the page
     if (insertPositionIfNotExist === "notInsert") return;
     const nextLine = insertPositionIfNotExist === "top" && lines.length > 1
       ? lines[1]
       : null;
     const title = {
-      // コードブロックのタイトル行
+      // Code block title line
       _insert: nextLine?.id ?? "_end",
       lines: {
         id: createNewLineId(userId),

rest/getCodeBlock.ts

@@ -50,13 +50,13 @@ const getCodeBlock_fromResponse: GetCodeBlock["fromResponse"] = async (res) =>
   );
 
 export interface GetCodeBlock {
-  /** `/api/code/:project/:title/:filename` の要求を組み立てる
+  /** Build a request for `/api/code/:project/:title/:filename`
    *
-   * @param project 取得したいページのproject名
-   * @param title 取得したいページのtitle 大文字小文字は問わない
-   * @param filename 取得したいコードブロックのファイル名
-   * @param options オプション
-   * @return request
+   * @param project Name of the project containing the target page
+   * @param title Title of the target page (case-insensitive)
+   * @param filename Name of the code block file to retrieve
+   * @param options Configuration options
+   * @return {@linkcode Request} object
    */
   toRequest: (
     project: string,
@@ -65,10 +65,10 @@ export interface GetCodeBlock {
     options?: BaseOptions,
   ) => Request;
 
-  /** 帰ってきた応答からコードを取得する
+  /** Extract code from the response
    *
-   * @param res 応答
-   * @return コード
+   * @param res Response from the API
+   * @return Code content as a string
    */
   fromResponse: (res: Response) => Promise<Result<string, CodeBlockError>>;
 
@@ -85,12 +85,12 @@ export type CodeBlockError =
   | NotMemberError
   | HTTPError;
 
-/** 指定したコードブロック中のテキストを取得する
+/** Retrieve text content from a specified code block
  *
- * @param project 取得したいページのproject名
- * @param title 取得したいページのtitle 大文字小文字は問わない
- * @param filename 取得したいコードブロックのファイル名
- * @param options オプション
+ * @param project Name of the project containing the target page
+ * @param title Title of the target page (case-insensitive)
+ * @param filename Name of the code block file to retrieve
+ * @param options Configuration options
  */
 export const getCodeBlock: GetCodeBlock = /* @__PURE__ */ (() => {
   const fn: GetCodeBlock = async (

rest/link.ts

@@ -24,7 +24,7 @@ export interface InvalidFollowingIdError extends ErrorLike {
 }
 
 export interface GetLinksOptions extends BaseOptions {
-  /** 次のリンクリストを示すID */
+  /** ID indicating the next list of links */
   followingId?: string;
 }