docs(highlighter-helper): add jsdoc

tools/highlighter-helper/src/client/composables/setupCollapsedLines.ts

@@ -1,5 +1,26 @@
 import { useEventListener } from '@vueuse/core'
 
+/**
+ * Setup collapsed lines functionality for code blocks
+ *
+ * 为代码块设置折叠行功能
+ *
+ * @param options - Setup options / 设置选项
+ * @param options.selector - CSS selector for collapsed lines elements / 折叠行元素的 CSS 选择器
+ *
+ * @example
+ * ```ts
+ * import { setupCollapsedLines } from '@vuepress/highlighter-helper/client'
+ *
+ * // Use default selector
+ * setupCollapsedLines()
+ *
+ * // Use custom selector
+ * setupCollapsedLines({
+ *   selector: '.my-collapsed-lines'
+ * })
+ * ```
+ */
 export const setupCollapsedLines = ({
   selector = 'div[class*="language-"].has-collapsed-lines > .collapsed-lines',
 }: { selector?: string } = {}): void => {

tools/highlighter-helper/src/node/codeBlockTitle/options.ts

@@ -1,12 +1,33 @@
+/**
+ * Code block title render function
+ *
+ * 代码块标题渲染函数
+ *
+ * @param title - The title to render / 要渲染的标题
+ * @param code - The code block HTML / 代码块 HTML
+ * @returns The rendered HTML / 渲染后的 HTML
+ */
 export type CodeBlockTitleRender = (title: string, code: string) => string
 
+/**
+ * Options for markdown-it code block title plugin
+ *
+ * markdown-it 代码块标题插件选项
+ */
 export interface MarkdownItCodeBlockTitleOptions {
   /**
    * Whether to render the title of the code block
    *
+   * 是否渲染代码块的标题
+   *
    * - If `true`, enable the title render of the code block
    * - If `false`, disable the title render of the code block
    * - If `Function`, custom title render
+   *
+   * - 如果是 `true`，启用代码块标题渲染
+   * - 如果是 `false`，禁用代码块标题渲染
+   * - 如果是 `Function`，自定义标题渲染
+   *
    * @default true
    */
   codeBlockTitle?: CodeBlockTitleRender | boolean

tools/highlighter-helper/src/node/codeBlockTitle/plugin.ts

@@ -6,6 +6,11 @@ import type {
   MarkdownItCodeBlockTitleOptions,
 } from './options.js'
 
+/**
+ * Default title render function
+ *
+ * 默认标题渲染函数
+ */
 const defaultTitleRender: CodeBlockTitleRender = (title, code) =>
   `\
 <div class="code-block-with-title">
@@ -15,6 +20,23 @@ const defaultTitleRender: CodeBlockTitleRender = (title, code) =>
   ${code}
 </div>`
 
+/**
+ * Add code block title functionality to markdown-it
+ *
+ * 为 markdown-it 添加代码块标题功能
+ *
+ * @param md - The markdown-it instance / markdown-it 实例
+ * @param options - Plugin options / 插件选项
+ *
+ * @example
+ * ```ts
+ * import { codeBlockTitle } from '@vuepress/highlighter-helper'
+ *
+ * md.use(codeBlockTitle, {
+ *   codeBlockTitle: true
+ * })
+ * ```
+ */
 export const codeBlockTitle = (
   md: Markdown,
   {

tools/highlighter-helper/src/node/collapsedLines/options.ts

@@ -1,16 +1,33 @@
+/**
+ * Options for markdown-it collapsed lines plugin
+ *
+ * markdown-it 折叠行插件选项
+ */
 export interface MarkdownItCollapsedLinesOptions {
   /**
-   * Whether to collapse code blocks when they exceed a certain number of lines,
+   * Whether to collapse code blocks when they exceed a certain number of lines
+   *
+   * 当代码块超过一定行数时是否折叠
    *
    * - If `number`, collapse starts from line `number`.
    * - If `true`, collapse starts from line 15 by default.
    * - If `false`, do not enable code block collapsing globally, but you can enable it for individual code blocks using `:collapsed-lines`
    * - If `'disable'`, Completely disable code block collapsing
+   *
+   * - 如果是 `number`，从第 `number` 行开始折叠
+   * - 如果是 `true`，默认从第 15 行开始折叠
+   * - 如果是 `false`，不全局启用代码块折叠，但你可以为单个代码块使用 `:collapsed-lines` 启用
+   * - 如果是 `'disable'`，完全禁用代码块折叠
+   *
    * @default 'disable'
    */
   collapsedLines?: boolean | number | 'disable'
 
   /**
+   * Whether to remove the last line
+   *
+   * 是否移除最后一行
+   *
    * @default false
    */
   removeLastLine?: boolean

tools/highlighter-helper/src/node/collapsedLines/plugin.ts

@@ -2,6 +2,24 @@ import type { Markdown } from 'vuepress/markdown'
 import type { MarkdownItCollapsedLinesOptions } from './options.js'
 import { resolveCollapsedLines } from './resolveCollapsedLine.js'
 
+/**
+ * Add collapsed lines functionality to code blocks in markdown-it
+ *
+ * 为 markdown-it 中的代码块添加折叠行功能
+ *
+ * @param md - The markdown-it instance / markdown-it 实例
+ * @param options - Plugin options / 插件选项
+ *
+ * @example
+ * ```ts
+ * import { collapsedLines } from '@vuepress/highlighter-helper'
+ *
+ * md.use(collapsedLines, {
+ *   collapsedLines: 15,
+ *   removeLastLine: false
+ * })
+ * ```
+ */
 export const collapsedLines = (
   md: Markdown,
   {

tools/highlighter-helper/src/node/collapsedLines/resolveCollapsedLine.ts

@@ -1,9 +1,43 @@
+/**
+ * Regular expression to match `:collapsed-lines` directive in code block info
+ *
+ * 匹配代码块信息中 `:collapsed-lines` 指令的正则表达式
+ */
 const COLLAPSED_LINES_REGEXP = /:collapsed-lines\b/
+
+/**
+ * Regular expression to match `:collapsed-lines=num` directive in code block info
+ *
+ * 匹配代码块信息中 `:collapsed-lines=num` 指令的正则表达式
+ */
 const COLLAPSED_LINES_START_REGEXP = /:collapsed-lines=(\d+)\b/
+
+/**
+ * Regular expression to match `:no-collapsed-lines` directive in code block info
+ *
+ * 匹配代码块信息中 `:no-collapsed-lines` 指令的正则表达式
+ */
 const NO_COLLAPSED_LINES_REGEXP = /:no-collapsed-lines\b/
 
 /**
  * Resolve the `:collapsed-lines` `:collapsed-lines=num` / `:no-collapsed-lines` mark from token info
+ *
+ * 从 token 信息中解析 `:collapsed-lines` `:collapsed-lines=num` / `:no-collapsed-lines` 标记
+ *
+ * @param info - Code block info string / 代码块信息字符串
+ * @returns Collapsed lines configuration / 折叠行配置
+ *  - `number` - Start line number for collapsing / 折叠起始行号
+ *  - `true` - Enable collapsed lines / 启用折叠行
+ *  - `false` - Disable collapsed lines / 禁用折叠行
+ *  - `null` - No configuration found / 未找到配置
+ *
+ * @example
+ * ```ts
+ * resolveCollapsedLines('js :collapsed-lines') // true
+ * resolveCollapsedLines('js :collapsed-lines=20') // 20
+ * resolveCollapsedLines('js :no-collapsed-lines') // false
+ * resolveCollapsedLines('js') // null
+ * ```
  */
 export function resolveCollapsedLines(info: string): boolean | number | null {
   const lines = COLLAPSED_LINES_START_REGEXP.exec(info)?.[1]

tools/highlighter-helper/src/node/lineNumbers/options.ts

@@ -1,25 +1,46 @@
+/**
+ * Options for markdown-it line numbers plugin
+ *
+ * markdown-it 行号插件选项
+ */
 export interface MarkdownItLineNumbersOptions {
   /**
    * Show line numbers in code blocks
    *
+   * 在代码块中显示行号
+   *
    * - If `number`, show line numbers with code block lines not less than `number`.
    * - If `true`, show line number always
    * - If `false`, do not enable line numbers globally, but you can enable it for individual code blocks using `:line-numbers`
    * - If `'disable'`, Completely disable line number
+   *
+   * - 如果是 `number`，当代码块行数不少于该数字时显示行号
+   * - 如果是 `true`，总是显示行号
+   * - 如果是 `false`，不全局启用行号，但你可以为单个代码块使用 `:line-numbers` 启用
+   * - 如果是 `'disable'`，完全禁用行号
+   *
    * @default 'disable'
    */
   lineNumbers?: boolean | number | 'disable'
 
   /**
+   * Whether to remove the last line
+   *
+   * 是否移除最后一行
+   *
    * @default false
    */
   removeLastLine?: boolean
 
   /**
    * Custom resolving function that whether to enable line numbers for a single code block
+   *
+   * 自定义解析函数，用于决定是否为单个代码块启用行号
+   *
+   * @param info - Code block info string / 代码块信息字符串
    * @returns `boolean | undefined`
-   *  - `boolean` - Whether to enable line numbers
-   *  - `undefined` - built-in resolving
+   *  - `boolean` - Whether to enable line numbers / 是否启用行号
+   *  - `undefined` - built-in resolving / 使用内置解析
    */
   resolveLineNumbers?: (info: string) => boolean | undefined
 }

tools/highlighter-helper/src/node/lineNumbers/plugin.ts

@@ -2,6 +2,24 @@ import type { Markdown } from 'vuepress/markdown'
 import type { MarkdownItLineNumbersOptions } from './options.js'
 import { resolveLineNumbers } from './resolveLineNumbers.js'
 
+/**
+ * Add line numbers to code blocks in markdown-it
+ *
+ * 为 markdown-it 中的代码块添加行号
+ *
+ * @param md - The markdown-it instance / markdown-it 实例
+ * @param options - Plugin options / 插件选项
+ *
+ * @example
+ * ```ts
+ * import { lineNumbers } from '@vuepress/highlighter-helper'
+ *
+ * md.use(lineNumbers, {
+ *   lineNumbers: true,
+ *   removeLastLine: false
+ * })
+ * ```
+ */
 export const lineNumbers = (
   md: Markdown,
   {

tools/highlighter-helper/src/node/lineNumbers/resolveLineNumbers.ts

@@ -4,6 +4,23 @@ const LINE_NUMBERS_START_REGEXP = /:line-numbers=(\d+)\b/
 
 /**
  * Resolve the `:line-numbers` `:line-numbers=num` / `:no-line-numbers` mark from token info
+ *
+ * 从 token 信息中解析 `:line-numbers` `:line-numbers=num` / `:no-line-numbers` 标记
+ *
+ * @param info - Code block info string / 代码块信息字符串
+ * @returns Line numbers configuration / 行号配置
+ *  - `number` - Start line number / 起始行号
+ *  - `true` - Enable line numbers / 启用行号
+ *  - `false` - Disable line numbers / 禁用行号
+ *  - `null` - No configuration found / 未找到配置
+ *
+ * @example
+ * ```ts
+ * resolveLineNumbers('js :line-numbers') // true
+ * resolveLineNumbers('js :line-numbers=10') // 10
+ * resolveLineNumbers('js :no-line-numbers') // false
+ * resolveLineNumbers('js') // null
+ * ```
  */
 export const resolveLineNumbers = (info: string): boolean | number | null => {
   const lineNumber = LINE_NUMBERS_START_REGEXP.exec(info)?.[1]

tools/highlighter-helper/src/node/utils/resolveAttr.ts

@@ -1,3 +1,19 @@
+/**
+ * Resolve attribute value from code block info string
+ *
+ * 从代码块信息字符串中解析属性值
+ *
+ * @param info - Code block info string / 代码块信息字符串
+ * @param attr - Attribute name to resolve / 要解析的属性名
+ * @returns The attribute value or null if not found / 属性值，如果未找到则返回 null
+ *
+ * @example
+ * ```ts
+ * resolveAttr('js title="example.js"', 'title') // 'example.js'
+ * resolveAttr('js title=\'example.js\'', 'title') // 'example.js'
+ * resolveAttr('js', 'title') // null
+ * ```
+ */
 export const resolveAttr = (info: string, attr: string): string | null => {
   // try to match specified attr mark
   const pattern = `\\b${attr}\\s*=\\s*(?<quote>['"])(?<content>.+?)\\k<quote>(\\s|$)`

tools/highlighter-helper/src/node/whitespace.ts

@@ -1,10 +1,42 @@
+/**
+ * Regular expression to match `:whitespace` directive in code block info
+ *
+ * 匹配代码块信息中 `:whitespace` 指令的正则表达式
+ */
 export const WHITESPACE_REGEXP = /:whitespace(?:=(all|boundary|trailing)?)?\b/
+
+/**
+ * Regular expression to match `:no-whitespace` directive in code block info
+ *
+ * 匹配代码块信息中 `:no-whitespace` 指令的正则表达式
+ */
 export const NO_WHITESPACE_REGEXP = /:no-whitespace\b/
 
+/**
+ * Whitespace position types
+ *
+ * 空白符位置类型
+ */
 export type WhitespacePosition = 'all' | 'boundary' | 'trailing'
 
 const AVAILABLE_WHITESPACE_POSITIONS = ['all', 'boundary', 'trailing']
 
+/**
+ * Resolve whitespace position from code block info and global option
+ *
+ * 从代码块信息和全局选项中解析空白符位置
+ *
+ * @param info - Code block info string / 代码块信息字符串
+ * @param globalOption - Global whitespace option / 全局空白符选项
+ * @returns Resolved whitespace position or false if disabled / 解析的空白符位置，如果禁用则返回 false
+ *
+ * @example
+ * ```ts
+ * resolveWhitespacePosition('js :whitespace=all', 'boundary') // 'all'
+ * resolveWhitespacePosition('js :no-whitespace', 'boundary') // false
+ * resolveWhitespacePosition('js', 'boundary') // 'boundary'
+ * ```
+ */
 export const resolveWhitespacePosition = (
   info: string,
   globalOption: WhitespacePosition | true,