From a8b2c82c9ffb897e58ad572bc68719616c5e45ab Mon Sep 17 00:00:00 2001
From: Mister-Hope <mister-hope@outlook.com>
Date: Wed, 4 Jun 2025 04:12:25 +0800
Subject: [PATCH] refactor(plugin-back-to-top): add jsdoc and improve docs

---
 docs/plugins/features/back-to-top.md               |  6 +++---
 docs/zh/plugins/features/back-to-top.md            | 10 +++++-----
 .../plugin-back-to-top/src/node/backToTopPlugin.ts | 14 ++++++++++++++
 .../plugin-back-to-top/src/node/options.ts         |  6 +++---
 .../plugin-back-to-top/src/shared/locales.ts       |  2 +-
 5 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/docs/plugins/features/back-to-top.md b/docs/plugins/features/back-to-top.md
index 8749d99001..2aac83a0a2 100644
--- a/docs/plugins/features/back-to-top.md
+++ b/docs/plugins/features/back-to-top.md
@@ -6,7 +6,7 @@ icon: arrow-up-to-line
 
 <NpmBadge package="@vuepress/plugin-back-to-top" />
 
-This plugin will add a _back to top_ button to your site. The button will be displayed in the bottom right corner of the page when scrolling down. By clicking the button, the page will scroll to the top.
+This plugin adds a _back to top_ button to your site. The button appears in the bottom right corner when scrolling down and scrolls the page to the top when clicked.
 
 This plugin has been integrated into the default theme.
 
@@ -30,13 +30,13 @@ export default {
 
 - Type: `number`
 - Default: `100`
-- Details: Scroll threshold distance to display back to top button (in pixels)
+- Details: Scroll threshold distance to display the back to top button (in pixels)
 
 ### progress
 
 - Type: `boolean`
 - Default: `true`
-- Details: Whether display progress bar around icon
+- Details: Whether to display scroll progress
 
 ## Styles
 
diff --git a/docs/zh/plugins/features/back-to-top.md b/docs/zh/plugins/features/back-to-top.md
index 379c3b1cf8..52ef01e068 100644
--- a/docs/zh/plugins/features/back-to-top.md
+++ b/docs/zh/plugins/features/back-to-top.md
@@ -6,7 +6,7 @@ icon: arrow-up-to-line
 
 <NpmBadge package="@vuepress/plugin-back-to-top" />
 
-该插件会给你的站点添加一个 _返回顶部_ 按钮。当页面向下滚动时，该按钮会显示在页面的右下角，点击它就会滚动到页面顶部。
+该插件会给你的站点添加一个 _返回顶部_ 按钮。当页面向下滚动时，该按钮会显示在页面的右下角。点击该按钮，页面会滚动到顶部。
 
 该插件已经集成到默认主题中。
 
@@ -28,15 +28,15 @@ export default {
 
 ### threshold
 
-- 类型：`数字`
+- 类型：`number`
 - 默认值：`100`
-- 详情：显示返回顶部按钮的滚动阈值距离（以像素为单位）
+- 详情：滚动距离阈值，用于显示返回顶部按钮（单位：像素）
 
 ### progress
 
-- 类型：`布尔值`
+- 类型：`boolean`
 - 默认值：`true`
-- 详情：是否在图标周围显示进度条
+- 详情：是否显示滚动进度
 
 ## 样式
 
diff --git a/plugins/features/plugin-back-to-top/src/node/backToTopPlugin.ts b/plugins/features/plugin-back-to-top/src/node/backToTopPlugin.ts
index d41ab859c3..b866e9dff8 100644
--- a/plugins/features/plugin-back-to-top/src/node/backToTopPlugin.ts
+++ b/plugins/features/plugin-back-to-top/src/node/backToTopPlugin.ts
@@ -7,6 +7,20 @@ import type { BackToTopPluginOptions } from './options.js'
 
 const __dirname = import.meta.dirname || getDirname(import.meta.url)
 
+/**
+ * Back to top plugin
+ *
+ * 返回顶部插件
+ *
+ * @example
+ * ```ts
+ * import { backToTopPlugin } from '@vuepress/plugin-back-to-top'
+ *
+ * export default {
+ *   plugins: [backToTopPlugin()]
+ * }
+ * ```
+ */
 export const backToTopPlugin =
   (options: BackToTopPluginOptions = {}): Plugin =>
   (app) => {
diff --git a/plugins/features/plugin-back-to-top/src/node/options.ts b/plugins/features/plugin-back-to-top/src/node/options.ts
index 7865d2d4d7..dda5651bf2 100644
--- a/plugins/features/plugin-back-to-top/src/node/options.ts
+++ b/plugins/features/plugin-back-to-top/src/node/options.ts
@@ -3,16 +3,16 @@ import type { BackToTopPluginLocaleData } from '../shared/index.js'
 
 export interface BackToTopPluginOptions {
   /**
-   * Scroll threshold distance to display back to top button (in pixels)
+   * Scroll threshold distance to display the back to top button (in pixels)
    *
-   * 滚动距离阈值，用于显示返回顶部按钮 (单位: 像素)
+   * 滚动距离阈值，用于显示返回顶部按钮（单位：像素）
    *
    * @default 100
    */
   threshold?: number
 
   /**
-   * Whether display scroll progress
+   * Whether to display scroll progress
    *
    * 是否显示滚动进度
    *
diff --git a/plugins/features/plugin-back-to-top/src/shared/locales.ts b/plugins/features/plugin-back-to-top/src/shared/locales.ts
index d5d323a979..27032f879e 100644
--- a/plugins/features/plugin-back-to-top/src/shared/locales.ts
+++ b/plugins/features/plugin-back-to-top/src/shared/locales.ts
@@ -2,7 +2,7 @@ export interface BackToTopPluginLocaleData {
   /**
    * Back to top button label text
    *
-   * 返回顶部文字
+   * 返回顶部按钮标签文字
    */
   backToTop: string
 }