refactor(plugin-append-date): add jsdoc

docs/plugins/markdown/append-date.md

@@ -6,7 +6,7 @@ icon: calendar
 
 <NpmBadge package="@vuepress/plugin-append-date" />
 
-This plugin will append writing date to frontmatter with [@vuepress/plugin-git](../development/git.md).
+This plugin will append writing date to frontmatter based on [@vuepress/plugin-git](../development/git.md).
 
 ## Usage
 
@@ -28,14 +28,16 @@ export default {
 
 - Type: `string`
 - Default: `"date"`
-- Details:
-
-  Frontmatter key to use when appending date.
+- Details: Frontmatter key to use when appending date
 
 ### format
 
 - Type: `"date" | "time" | "full"`
 - Default: `"date"`
 - Details:
 
-  Format of the date value when appending date.
+  Format of the date value when appending date:
+
+  - `"date"`: YYYY-MM-DD format
+  - `"time"`: HH:MM:SS format
+  - `"full"`: YYYY-MM-DD HH:MM:SS format

docs/zh/plugins/markdown/append-date.md

@@ -28,10 +28,16 @@ export default {
 
 - 类型：`string`
 - 默认值：`"date"`
-- 详情：追加时间时使用的 frontmatter 键名。
+- 详情：追加时间时使用的 frontmatter 键名
 
 ### format
 
 - 类型：`"date" | "time" | "full"`
 - 默认值：`"date"`
-- 详情：追加时间时使用的日期格式。
+- 详情：
+
+  追加时间时使用的日期格式：
+
+  - `"date"`：YYYY-MM-DD 格式
+  - `"time"`：HH:MM:SS 格式
+  - `"full"`：YYYY-MM-DD HH:MM:SS 格式

plugins/markdown/plugin-append-date/src/node/appendDate.ts

@@ -9,6 +9,16 @@ import {
 } from './formatDate.js'
 import type { AppendDatePluginOptions } from './options.js'
 
+/**
+ * Append date to page frontmatter
+ *
+ * 向页面 frontmatter 追加日期
+ *
+ * @param options - Plugin options / 插件选项
+ * @param options.key - Frontmatter key to use / 使用的 frontmatter 键名
+ * @param options.format - Date format to use / 使用的日期格式
+ * @param page - Page object / 页面对象
+ */
 export const appendDateToPage = async (
   { key = 'date', format = 'date' }: AppendDatePluginOptions,
   { data, filePath, frontmatter }: Page<GitPluginPageData>,

plugins/markdown/plugin-append-date/src/node/appendDatePlugin.ts

@@ -5,6 +5,27 @@ import { isGitPluginEnabled } from './checkGitPlugin.js'
 import { PLUGIN_NAME } from './logger.js'
 import type { AppendDatePluginOptions } from './options.js'
 
+/**
+ * Append date plugin
+ *
+ * 追加日期插件
+ *
+ * @param [options={}] - Plugin options / 插件选项
+ *
+ * @example
+ * ```ts
+ * import { appendDatePlugin } from '@vuepress/plugin-append-date'
+ *
+ * export default {
+ *   plugins: [
+ *     appendDatePlugin({
+ *       key: 'date',
+ *       format: 'date'
+ *     })
+ *   ]
+ * }
+ * ```
+ */
 export const appendDatePlugin = (
   options: AppendDatePluginOptions = {},
 ): PluginObject => ({

plugins/markdown/plugin-append-date/src/node/checkGitPlugin.ts

@@ -4,6 +4,13 @@ import { logger } from './logger.js'
 
 const GIT_PLUGIN_NAME = '@vuepress/plugin-git'
 
+/**
+ * Check if git plugin is enabled
+ *
+ * 检查 git 插件是否已启用
+ *
+ * @param app - VuePress app instance / VuePress 应用实例
+ */
 export const isGitPluginEnabled = (app: App): boolean => {
   if (
     app.pluginApi.plugins.every((plugin) => plugin.name !== GIT_PLUGIN_NAME)

plugins/markdown/plugin-append-date/src/node/formatDate.ts

@@ -13,11 +13,32 @@ const getMinutes = (date: Date): string => padZero(date.getMinutes())
 
 const getSeconds = (date: Date): string => padZero(date.getSeconds())
 
+/**
+ * Get date string in YYYY-MM-DD format
+ *
+ * 获取 YYYY-MM-DD 格式的日期字符串
+ *
+ * @param date - Date object / 日期对象
+ */
 export const getDateString = (date: Date): string =>
   `${getFullYear(date)}-${getMonth(date)}-${getDate(date)}`
 
+/**
+ * Get time string in HH:mm:ss format
+ *
+ * 获取 HH:mm:ss 格式的时间字符串
+ *
+ * @param date - Date object / 日期对象
+ */
 export const getTimeString = (date: Date): string =>
   `${getHours(date)}:${getMinutes(date)}:${getSeconds(date)}`
 
+/**
+ * Get full date string in YYYY-MM-DD HH:mm:ss format
+ *
+ * 获取 YYYY-MM-DD HH:mm:ss 格式的完整日期时间字符串
+ *
+ * @param date - Date object / 日期对象
+ */
 export const getFullDateString = (date: Date): string =>
   `${getDateString(date)} ${getTimeString(date)}`

plugins/markdown/plugin-append-date/src/node/options.ts

@@ -1,19 +1,24 @@
+/**
+ * Plugin options
+ *
+ * 插件选项
+ */
 export interface AppendDatePluginOptions {
   /**
-   * Frontmatter key to use when appending date.
+   * Frontmatter key to use when appending date
    *
-   * 追加时间时使用的 frontmatter 键名。
+   * 追加时间时使用的 frontmatter 键名
    *
-   * @default 'date'
+   * @default "date"
    */
   key?: string
 
   /**
-   * Format of the date value when appending date.
+   * Format of the date value when appending date
    *
-   * 追加时间时使用的日期格式。
+   * 追加时间时使用的日期格式
    *
-   * @default 'date'
+   * @default "date"
    */
   format?: 'date' | 'full' | 'time'
 }