fix: replace eslint-disable stubs with real JSDoc in group/threadDrawer

steve02081504 · steve02081504 · commit 2100382932ff · 2026-04-14T18:56:49.000+08:00
- Remove blanket jsdoc suppressions; document factory option callbacks with @returns/@param descriptions
- Fix threadDrawer loadMessagesRef formatting and late-binding JSDoc
- standalone_message.html: keep file-level eslint-disable with explanation comment
diff --git a/src/public/parts/shells/chat/public/src/group.mjs b/src/public/parts/shells/chat/public/src/group.mjs
@@ -387,19 +387,16 @@ async function applyGroupHash() {
 	// ─── 文件处理（uploadGroupFile / downloadGroupFile / fetchGroupFileAsBlob / enqueuePendingFile）──
 
 	// loadMessages / scheduleMessagePatch 由下方 createChannelView 赋值，此处先声明供晚绑定
-	// eslint-disable-next-line prefer-const
 	let loadMessages, scheduleMessagePatch
 
 	// loadMessages 在此处尚未定义，使用晚绑定包装，确保实际调用时已初始化
-	/* eslint-disable jsdoc/require-returns */
 	const { uploadGroupFile, downloadGroupFile, fetchGroupFileAsBlob, enqueuePendingFile, pendingFiles } = createFileHandlers({
 		groupId, Sentry, showToastI18n, escapeHtml,
 		/**
-		 *
+		 * @returns {Promise<void>} 重新加载当前频道消息
 		 */
 		loadMessages: () => loadMessages(),
 	})
-	/* eslint-enable jsdoc/require-returns */
 
 	// ─── 表情回应（toggleReaction）────────────────────────────────────────────
 
@@ -409,38 +406,37 @@ async function applyGroupHash() {
 	/** @type {{ open: Function, close: Function, destroy: Function } | null} */
 	let threadDrawerInstance = null
 
-	/* eslint-disable jsdoc/require-returns, jsdoc/require-param-description, jsdoc/require-param-type */
 	const { renderMessageItem, attachLastMessageTimeline } = createMessageItemRenderer({
 		groupId,
 		channelId,
 		msgBox,
 		/**
-		 *
+		 * @returns {Promise<void>} 重新加载当前频道消息
 		 */
 		loadMessages: () => loadMessages(),
 		/**
-		 *
+		 * @returns {unknown[]} 当前展示用消息数组
 		 */
 		getDisplayMessages: () => channelState.displayMessages,
 		/**
-		 *
+		 * @returns {Record<string, string>} 成员头像 URL 缓存
 		 */
 		getMemberAvatarCache: () => memberAvatarCache,
 		toggleReaction,
 		fetchGroupFileAsBlob,
 		downloadGroupFile,
 		loadBookmarks,
 		/**
-		 *
+		 * @returns {unknown[]} DM 拉黑列表
 		 */
 		getDmBlocklist: () => dmBlocklist,
 		/**
-		 *
-		 * @param next
+		 * @param {unknown} next 新的拉黑列表
+		 * @returns {void}
 		 */
 		setDmBlocklist: next => { dmBlocklist = next },
 		/**
-		 *
+		 * @returns {Set<string>} 已被编辑过的消息 ID 集合
 		 */
 		getEditedIds: () => {
 			const s = new Set()
@@ -451,7 +447,7 @@ async function applyGroupHash() {
 			return s
 		},
 		/**
-		 *
+		 * @returns {void} 内容高度变化时滚动到底部
 		 */
 		onContentResize: () => {
 			if (!channelState.msgScrollContainer) return
@@ -460,18 +456,17 @@ async function applyGroupHash() {
 				channelState.msgScrollContainer.scrollTop = channelState.msgScrollContainer.scrollHeight
 		},
 		/**
-		 * @param {string} threadChannelId
+		 * @param {string} threadChannelId 子线程频道 ID
+		 * @returns {void}
 		 */
 		onOpenThread: threadChannelId => { threadDrawerInstance?.open(threadChannelId) },
 	})
-	/* eslint-enable jsdoc/require-returns, jsdoc/require-param-description, jsdoc/require-param-type */
 
 	// ─── Thread Drawer ────────────────────────────────────────────────────────
 
-	/* eslint-disable jsdoc/require-returns, jsdoc/require-param-description, jsdoc/require-param-type */
 	/**
 	 * 为指定线程频道创建专用消息渲染器（复用群组级共享依赖）。
-	 * @param {object} threadCtx
+	 * @param {object} threadCtx 线程上下文
 	 * @param {string} threadCtx.channelId 线程频道 ID
 	 * @param {HTMLElement} threadCtx.msgBox 线程消息容器元素
 	 * @param {Function} threadCtx.loadMessages 线程消息刷新函数
@@ -482,45 +477,42 @@ async function applyGroupHash() {
 			groupId,
 			channelId: threadChannelId,
 			msgBox: threadMsgBox,
-			/**
-			 *
-			 */
 			loadMessages: threadLoadMessages,
 			/**
-			 *
+			 * @returns {unknown[]} 线程视图无合并展示列表，恒为空
 			 */
 			getDisplayMessages: () => [],
 			/**
-			 *
+			 * @returns {Record<string, string>} 成员头像 URL 缓存
 			 */
 			getMemberAvatarCache: () => memberAvatarCache,
 			toggleReaction,
 			fetchGroupFileAsBlob,
 			downloadGroupFile,
 			loadBookmarks,
 			/**
-			 *
+			 * @returns {unknown[]} DM 拉黑列表
 			 */
 			getDmBlocklist: () => dmBlocklist,
 			/**
-			 *
-			 * @param {object} next
+			 * @param {unknown} next 新的拉黑列表
+			 * @returns {void}
 			 */
 			setDmBlocklist: next => { dmBlocklist = next },
 			/**
-			 *
+			 * @returns {Set<string>} 线程内不跟踪编辑态，恒为空集
 			 */
 			getEditedIds: () => new Set(),
 			/**
-			 *
+			 * @returns {void} 线程内无内容自适应滚动
 			 */
 			onContentResize: () => {},
 			/**
-			 * @param {string} nestedThreadId 嵌套子线程 ID
+			 * @param {string} nestedThreadId 嵌套子线程频道 ID
+			 * @returns {void}
 			 */
 			onOpenThread: nestedThreadId => { threadDrawerInstance?.open(nestedThreadId) },
 		})
-	/* eslint-enable jsdoc/require-returns, jsdoc/require-param-description, jsdoc/require-param-type */
 
 	threadDrawerInstance = createThreadDrawer({
 		groupId,
@@ -577,7 +569,6 @@ async function applyGroupHash() {
 	}
 
 	// 创建频道视图（含 loadMessages 和 scheduleMessagePatch）
-	/* eslint-disable jsdoc/require-returns */
 	;({ loadMessages, scheduleMessagePatch } = createChannelView({
 		groupId,
 		channelId,
@@ -586,19 +577,19 @@ async function applyGroupHash() {
 		signal,
 		state: channelState,
 		/**
-		 *
+		 * @returns {object | null} 最近一次拉取的频道元数据
 		 */
 		getLastChannelMeta: () => lastChannelMeta,
 		/**
-		 *
+		 * @returns {object | null} 最近一次拉取的群设置
 		 */
 		getLastGroupSettings: () => lastGroupSettings,
 		/**
-		 *
+		 * @returns {string[]} @ 提及可用的角色名列表
 		 */
 		getMentionCharNames: () => mentionCharNames,
 		/**
-		 *
+		 * @returns {Record<string, object>} 已打开频道缓存
 		 */
 		getOpenedChannels: () => openedChannels,
 		enqueuePendingFile,
@@ -607,7 +598,6 @@ async function applyGroupHash() {
 		renderMessageItem,
 		attachLastMessageTimeline,
 	}))
-	/* eslint-enable jsdoc/require-returns */
 
 	await pullIncrementalDagEvents()
 	await loadState()
@@ -634,7 +624,7 @@ async function applyGroupHash() {
 	groupWs.addEventListener('open', () => {
 		sendWebsocketMessage({ type: 'group_ws_rpc_identity', clientNodeId: wsClientId })
 	}, { once: true })
-	/* eslint-disable jsdoc/require-returns */
+
 	groupWs.onmessage = createWsMessageHandler({
 		groupId,
 		channelId,
@@ -649,48 +639,46 @@ async function applyGroupHash() {
 		loadState,
 		loadBookmarks,
 		/**
-		 *
+		 * @returns {WebSocket} 当前群 WebSocket 实例
 		 */
 		getGroupWs: () => groupWs,
 		shouldLoadChannel,
 		handleGroupWebSocketRpc,
 		handleSessionEvent,
 		msgBox,
 	})
-	/* eslint-enable jsdoc/require-returns */
 
-	/* eslint-disable jsdoc/require-returns, jsdoc/require-param-description, jsdoc/require-param-type, no-unused-vars */
 	const { postMessage, startAvSession } = createMessageInputHandlers({
 		groupId,
 		channelId,
 		signal,
 		input,
 		wsClientId,
 		/**
-		 *
+		 * @returns {unknown[]} 待发送附件队列
 		 */
 		getPendingFiles: () => pendingFiles,
 		/**
-		 *
+		 * @returns {void} 清空待发送附件队列
 		 */
 		clearPendingFiles: () => { pendingFiles.length = 0 },
 		enqueuePendingFile,
 		uploadGroupFile,
 		/**
-		 *
+		 * @returns {unknown} 当前音视频会话句柄
 		 */
 		getAvSession: () => channelState.avSession,
 		/**
-		 *
-		 * @param s
+		 * @param {unknown} s 新的音视频会话句柄
+		 * @returns {void}
 		 */
 		setAvSession: s => { channelState.avSession = s },
 		/**
-		 *
+		 * @returns {object | null} 最近一次频道元数据
 		 */
 		getLastChannelMeta: () => lastChannelMeta,
 		/**
-		 *
+		 * @returns {Record<string, object>} 频道列表快照
 		 */
 		getLastChannels: () => lastChannels,
 		loadMessages,
@@ -700,12 +688,8 @@ async function applyGroupHash() {
 		updateMentionPopover,
 		sendTypingBroadcast,
 	})
-	/* eslint-enable jsdoc/require-returns, jsdoc/require-param-description, jsdoc/require-param-type, no-unused-vars */
 }
 
-/**
- * @returns {Promise<void>}
- */
 /** DM 拉黑列表（本地缓存，sessionStorage 为辅） */
 let dmBlocklist = []
 /**
diff --git a/src/public/parts/shells/chat/public/src/templates/standalone_message.html b/src/public/parts/shells/chat/public/src/templates/standalone_message.html
@@ -1,5 +1,6 @@
 <!DOCTYPE html>
 <!-- eslint-disable -->
+<!-- 模板引擎 HTML，非独立脚本；须整文件禁用 eslint 避免误解析内嵌语法 -->
 <html lang="${main_locale}">
 ${
 	let messageHtml = setValue('messageHtml', await renderMarkdownAsStandAloneHtmlString(message.content_for_show || message.content))
diff --git a/src/public/parts/shells/chat/public/src/ui/threadDrawer.mjs b/src/public/parts/shells/chat/public/src/ui/threadDrawer.mjs
@@ -186,22 +186,30 @@ export function createThreadDrawer({ groupId, panel, createThreadRenderer }) {
 		msgVirtualList = null
 		msgBox.innerHTML = '<div class="flex justify-center items-center flex-1 p-6"><span class="loading loading-spinner loading-sm opacity-60"></span></div>'
 
-		/* eslint-disable jsdoc/require-returns, jsdoc/require-jsdoc */
-		// 晚绑定：loadMessages 需先于 renderMessageItem 声明，通过包装器延迟调用
-		// eslint-disable-next-line prefer-const
-		let loadFn = () => Promise.resolve()
+		// 晚绑定：renderMessageItem 在 createThreadRenderer 之后才存在，用可替换的 run 避免 let 重赋值
+		const loadMessagesRef = {
+			/**
+			 * @returns {Promise<void>} 加载或刷新线程消息（占位实现）
+			 */
+			run: () => Promise.resolve(),
+		}
 
 		const { renderMessageItem } = createThreadRenderer({
 			channelId: threadChannelId,
 			msgBox,
-			loadMessages: () => loadFn(),
+			/**
+			 * @returns {Promise<void>} 调用当前绑定的线程加载函数
+			 */
+			loadMessages: () => loadMessagesRef.run(),
 		})
 
-		loadFn = () => fetchAndRender(threadChannelId, renderMessageItem, signal)
-		/* eslint-enable jsdoc/require-returns, jsdoc/require-jsdoc */
+		/**
+		 * @returns {Promise<void>} 拉取并渲染线程频道消息
+		 */
+		loadMessagesRef.run = () => fetchAndRender(threadChannelId, renderMessageItem, signal)
 
 		try {
-			await loadFn()
+			await loadMessagesRef.run()
 		}
 		catch (e) {
 			if (!signal.aborted) {
