From 5797bb7f8cb7eb750514abc28580951d0512ea9c Mon Sep 17 00:00:00 2001
From: Slinetrac <realakayuki@gmail.com>
Date: Sat, 6 Dec 2025 11:16:26 +0800
Subject: [PATCH] docs: add JSDoc for showNotice API

---
 src/services/noticeService.ts | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/services/noticeService.ts b/src/services/noticeService.ts
index f0e316c76..1da700263 100644
--- a/src/services/noticeService.ts
+++ b/src/services/noticeService.ts
@@ -311,6 +311,17 @@ const baseShowNotice = (
   return id;
 };
 
+/**
+ * Shows a global notice; `showNotice.success / error / info` are the usual entry points.
+ *
+ * - `message`: i18n key string, `{ key, params }`, ReactNode, Error/any value (message is extracted)
+ * - `extras` parsed left-to-right: first plain object is i18n params; next value is raw payload; first number overrides duration (ms, 0 = persistent; defaults: success 3000 / info 5000 / error 8000)
+ * - Returns a notice id for manual closing via `hideNotice(id)`
+ *
+ * @example showNotice.success("profiles.page.feedback.notifications.batchDeleted");
+ * @example showNotice.error(err); // pass an Error directly
+ * @example showNotice.error("profiles.page.feedback.errors.invalidUrl", { url }, 4000);
+ */
 export const showNotice: ShowNotice = Object.assign(baseShowNotice, {
   success: (message: NoticeContent, ...extras: NoticeExtra[]) =>
     baseShowNotice("success", message, ...extras),