refactor: improve codes and update jsdoc (#668)

Author: Mister-Hope

.ncurc.cjs

@@ -14,13 +14,10 @@ module.exports = defineConfig({
     )
       return '@next'
 
+    if (name === '@types/node') return 'minor'
+
     if (['vite'].includes(name)) return 'patch'
 
     return 'latest'
   },
-  reject: (name) => {
-    if (name === '@types/node') return true
-
-    return false
-  },
 })

AGENTS.md

@@ -135,25 +135,23 @@ All source files are in `src/`. Compiled output goes to `dist/` (git-ignored).
 
 **JSDoc template:**
 
-````typescript
+```typescript
 /**
  * English description
  *
- * 中文描述
+ * (optional) English detailed description
  *
- * @description (optional) English detailed description
+ * 中文描述
  *
- * 中文详细描述
+ * （可选）中文详细描述
  *
  * @param paramName - English description / 中文描述
  *
  * @default defaultValue
  * @example
- * ```ts
- * // Example code in TypeScript
- * ```
+ *   // Example code in TypeScript
  */
-````
+```
 
 ### Commit Messages
 

docs/.vuepress/components/NpmBadge.vue

@@ -2,9 +2,9 @@
 import { computed } from 'vue'
 
 const { package: pkg, distTag = 'next' } = defineProps<{
-  /** package name */
+  /** Package name */
   package: string
-  /** dist tag */
+  /** Dist tag */
   distTag?: string
 }>()
 

docs/.vuepress/components/VPAutoLink.vue

@@ -8,9 +8,7 @@ export interface AutoLinkConfigWithIcon extends AutoLinkConfig {
 }
 
 const { config } = defineProps<{
-  /**
-   * The auto link config
-   */
+  /** The auto link config */
   config: AutoLinkConfigWithIcon
 }>()
 

docs/.vuepress/components/VPNavbarDropdown.vue

@@ -11,7 +11,7 @@ import VPAutoLink from '@theme/VPAutoLink.vue'
 import '@vuepress/helper/transition/fade-in-height-expand.css'
 
 const { config } = defineProps<{
-  /** dropdown config */
+  /** Dropdown config */
   config: NavGroup<AutoLinkOptions | NavGroup<AutoLinkOptions>>
 }>()
 
@@ -25,8 +25,8 @@ const isLastItemOfArray = (arrayItem: unknown, array: unknown[]): boolean =>
 /**
  * Open the dropdown when user tab and click from keyboard.
  *
- * Use event.detail to detect tab and click from keyboard.
- * The Tab + Click is UIEvent > KeyboardEvent, so the detail is 0.
+ * Use event.detail to detect tab and click from keyboard. The Tab + Click is
+ * UIEvent > KeyboardEvent, so the detail is 0.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail
  */

docs/.vuepress/components/VPSidebarItem.vue

@@ -12,13 +12,9 @@ import VPAutoLink from '@theme/VPAutoLink.vue'
 import VPDropdownTransition from '@theme/VPDropdownTransition.vue'
 
 const { item, depth = 0 } = defineProps<{
-  /**
-   * The sidebar item to be rendered
-   */
+  /** The sidebar item to be rendered */
   item: SidebarItem
-  /**
-   * The depth of the current sidebar item
-   */
+  /** The depth of the current sidebar item */
   depth?: number
 }>()
 

docs/.vuepress/theme.ts

@@ -13,8 +13,8 @@ export default defaultTheme({
     /**
      * English locale config
      *
-     * As the default locale of `@vuepress/theme-default` is English,
-     * we don't need to set all of the locale fields
+     * As the default locale of `@vuepress/theme-default` is English, we don't
+     * need to set all of the locale fields
      */
     '/': {
       // navbar
@@ -25,9 +25,7 @@ export default defaultTheme({
       editLinkText: 'Edit this page on GitHub',
     },
 
-    /**
-     * Chinese locale config
-     */
+    /** Chinese locale config */
     '/zh/': {
       // navbar
       navbar: navbarZh,

docs/.vuepress/utils/resolveAutoLink.ts

@@ -4,14 +4,13 @@ import { resolveRoute } from 'vuepress/client'
 /**
  * Resolve AutoLink props from string
  *
- * @param config AutoLink config string
- * @param currentPath current page path, used to resolve relative link
+ * @example
+ *   - Input: '/README.md'
+ *   - Output: { text: 'Home', icon: 'home', link: '/' }
  *
+ * @param config AutoLink config string
+ * @param currentPath Current page path, used to resolve relative link
  * @returns AutoLink options
- *
- * @example
- * - Input: '/README.md'
- * - Output: { text: 'Home', icon: 'home', link: '/' }
  */
 export const resolveAutoLink = (
   config: string,

docs/plugins/blog/blog/config.md

@@ -166,7 +166,7 @@ interface BlogCategoryOptions {
   /**
    * The path pattern for the registered page
    *
-   * @description `:key` will be replaced by the "slugify" result of the original key
+   * `:key` will be replaced by the "slugify" result of the original key
    *
    * @default `/:key/`
    */
@@ -187,7 +187,7 @@ interface BlogCategoryOptions {
   /**
    * The path pattern or custom function for the item page
    *
-   * @description When providing a string, `:key` and `:name` will be replaced by the "slugify" result of the original key and name
+   * When providing a string, `:key` and `:name` will be replaced by the "slugify" result of the original key and name
    *
    * @default `/:key/:name/`
    */

docs/plugins/blog/blog/guide.md

@@ -148,7 +148,7 @@ interface BlogFrontmatterOptions {
   /**
    * Current category name
    *
-   * @description Only available in category item page
+   * Only available in category item page
    */
   name?: string
 }