feat(Dialog): add JSDoc for utility functions (#12343)

youzan · Oct 6, 2023 · f1d5376 · f1d5376
1 parent d56623e
commit f1d5376
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 15 deletions.
diff --git a/packages/vant/src/dialog/README.md b/packages/vant/src/dialog/README.md
@@ -32,7 +32,7 @@ showDialog({ message: 'Content' });
 
 ### Alert dialog
 
-Used to prompt for some messages, only including one confirm button.
+Used to prompt for some messages, only including one confirm button by default.
 
 ```js
 showDialog({
@@ -51,7 +51,7 @@ showDialog({
 
 ### Confirm dialog
 
-Used to confirm some messages, including a confirm button and a cancel button.
+Used to confirm some messages, including a confirm button and a cancel button by default.
 
 ```js
 showConfirmDialog({
@@ -68,7 +68,7 @@ showConfirmDialog({
 
 ### Round Button Style
 
-Use round button style.
+Setting the `theme` option to `round-button` will display the Dialog with a rounded button style.
 
 ```js
 showDialog({
@@ -89,6 +89,8 @@ showDialog({
 
 ### Async Close
 
+You can pass a callback function through the `beforeClose` option to perform specific operations before closing the Dialog.
+
 ```js
 const beforeClose = (action) =>
   new Promise((resolve) => {
@@ -106,7 +108,7 @@ showConfirmDialog({
 
 ### Use Dialog Component
 
-If you need to render Vue components within a Dialog, you can use the Dialog component.
+If you need to embed components or other custom content within a Dialog, you can directly use the Dialog component and customize it using the default slot. Before using it, you need to register the component using `app.use` or other methods.
 
 ```html
 <van-dialog v-model:show="show" title="Title" show-cancel-button>
@@ -133,11 +135,11 @@ Vant exports following Dialog utility functions:
 
 | Name | Description | Attribute | Return value |
 | --- | --- | --- | --- |
-| showDialog | Show dialog | _options: DialogOptions_ | `Promise<void>` |
-| showConfirmDialog | Show confirm dialog | _options: DialogOptions_ | `Promise<void>` |
-| closeDialog | Close dialog | - | `void` |
-| setDialogDefaultOptions | Set default options of all dialogs | _options: DialogOptions_ | `void` |
-| resetDialogDefaultOptions | Reset default options of all dialogs | - | `void` |
+| showDialog | Display a message prompt dialog with a default confirm button | _options: DialogOptions_ | `Promise<void>` |
+| showConfirmDialog | Display a message confirmation dialog with default confirm and cancel buttons | _options: DialogOptions_ | `Promise<void>` |
+| closeDialog | Close the currently displayed dialog | - | `void` |
+| setDialogDefaultOptions | Modify the default configuration that affects all `showDialog` calls | _options: DialogOptions_ | `void` |
+| resetDialogDefaultOptions | Reset the default configuration that affects all `showDialog` calls | - | `void` |
 
 ### DialogOptions
 

diff --git a/packages/vant/src/dialog/README.zh-CN.md b/packages/vant/src/dialog/README.zh-CN.md
@@ -32,7 +32,7 @@ showDialog({ message: '提示' });
 
 ### 消息提示
 
-用于提示一些消息，只包含一个确认按钮。
+用于提示一些消息，默认只包含一个确认按钮。
 
 ```js
 import { showDialog } from 'vant';
@@ -53,7 +53,7 @@ showDialog({
 
 ### 消息确认
 
-用于确认消息，包含取消和确认按钮。
+用于确认消息，默认包含确认和取消按钮。
 
 ```js
 import { showConfirmDialog } from 'vant';
@@ -123,7 +123,7 @@ showConfirmDialog({
 
 ### 使用 Dialog 组件
 
-如果需要在 Dialog 内嵌入组件或其他自定义内容，可以直接使用 Dialog 组件，并使用默认插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。
+如果你需要在 Dialog 内嵌入组件或其他自定义内容，可以直接使用 Dialog 组件，并使用默认插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。
 
 ```html
 <van-dialog v-model:show="show" title="标题" show-cancel-button>
@@ -150,9 +150,9 @@ Vant 中导出了以下 Dialog 相关的辅助函数：
 
 | 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
-| showDialog | 展示弹窗 | _options: DialogOptions_ | `Promise<void>` |
-| showConfirmDialog | 展示消息确认弹窗 | _options: DialogOptions_ | `Promise<void>` |
-| closeDialog | 关闭弹窗 | - | `void` |
+| showDialog | 展示消息提示弹窗，默认包含确认按钮 | _options: DialogOptions_ | `Promise<void>` |
+| showConfirmDialog | 展示消息确认弹窗，默认包含确认和取消按钮 | _options: DialogOptions_ | `Promise<void>` |
+| closeDialog | 关闭当前展示的弹窗 | - | `void` |
 | setDialogDefaultOptions | 修改默认配置，影响所有的 `showDialog` 调用 | _options: DialogOptions_ | `void` |
 | resetDialogDefaultOptions | 重置默认配置，影响所有的 `showDialog` 调用 | - | `void` |
 

diff --git a/packages/vant/src/dialog/function-call.tsx b/packages/vant/src/dialog/function-call.tsx
@@ -46,6 +46,9 @@ function initInstance() {
   ({ instance } = mountComponent(Wrapper));
 }
 
+/**
+ * Display a message prompt dialog with a default confirm button
+ */
 export function showDialog(
   options: DialogOptions,
 ): Promise<DialogAction | undefined> {
@@ -69,17 +72,29 @@ export function showDialog(
   });
 }
 
+/**
+ * Modify the default configuration that affects all `showDialog` calls
+ */
 export const setDialogDefaultOptions = (options: DialogOptions) => {
   extend(currentOptions, options);
 };
 
+/**
+ * Reset the default configuration that affects all `showDialog` calls
+ */
 export const resetDialogDefaultOptions = () => {
   currentOptions = extend({}, DEFAULT_OPTIONS);
 };
 
+/**
+ * Display a message confirmation dialog with default confirm and cancel buttons
+ */
 export const showConfirmDialog = (options: DialogOptions) =>
   showDialog(extend({ showCancelButton: true }, options));
 
+/**
+ * Close the currently displayed dialog
+ */
 export const closeDialog = () => {
   if (instance) {
     instance.toggle(false);