Fix empty JSDoc stubs across codebase (#279)

Author: steve02081504

.github/pages/test/frontend/fixtures.mjs

@@ -82,11 +82,7 @@ export function createPagesFixtures(options = {}) {
 }
 
 const fixtures = createPagesFixtures()
-/**
- *
- */
+/** 默认 Pages E2E 用例（`createPagesFixtures()` 产物）。 */
 export const test = fixtures.test
-/**
- *
- */
+/** 重导出 Playwright `expect` 断言。 */
 export { expect }

.github/pages/wait/install/index.mjs

@@ -613,9 +613,7 @@ const checkFountInstallerAlive = async () => {
  */
 const whenFountInstallerFails = () => {
 	return new Promise(resolve => {
-		/**
-		 *
-		 */
+		/** 轮询直至安装程序进程退出。 */
 		const check = async () => {
 			if (await checkFountInstallerAlive()) setTimeout(check, 1000)
 			else resolve()

src/decl/chatLog.ts

@@ -216,7 +216,5 @@ export class chatLogEntry_t {
 	}
 }
 
-/**
- *
- */
+/** 聊天日志条目数组。 */
 export type chatLog_t = chatLogEntry_t[]

src/decl/p2pAPI.ts

@@ -105,9 +105,7 @@ export type PermissionBitmap = bigint
 
 // ---- Denylist（节点连接拒绝 deny，`denylist.mjs`；非 Social block / 群 ban）----
 
-/**
- *
- */
+/** denylist 拒绝粒度：主体、实体或节点。 */
 export type DenyScope = 'subject' | 'entity' | 'node'
 
 /** 磁盘/API 单条 denylist 条目。 */
@@ -125,13 +123,9 @@ export interface SerializedDenylist {
 
 // ---- Personal lists（`personal_block.mjs`：block=联邦公开拉黑，hide=纯本地）----
 
-/**
- *
- */
+/** 个人列表作用域：实体或主体。 */
 export type PersonalListScope = 'entity' | 'subject'
-/**
- *
- */
+/** 个人列表类型：联邦公开拉黑或纯本地隐藏。 */
 export type PersonalListKind = 'block' | 'hide'
 
 /** `GET /api/parts/shells:chat/personal-lists` 与 Social profile 共用条目形状。 */
@@ -141,9 +135,7 @@ export interface PersonalListEntry {
 	value: string
 }
 
-/**
- *
- */
+/** `GET …/personal-lists` 响应体。 */
 export interface PersonalListsResponse {
 	entries: PersonalListEntry[]
 }
@@ -155,9 +147,7 @@ export interface MailboxSummaryResponse {
 
 // ---- 群成员 / 频道 ----
 
-/**
- *
- */
+/** 群成员物化记录。 */
 export interface Member {
 	pubKeyHash: string
 	homeNodeHash?: string | null
@@ -172,9 +162,7 @@ export interface Member {
 	pubKeyHex?: string | null
 }
 
-/**
- *
- */
+/** 群角色定义（权限、排序与展示）。 */
 export interface Role {
 	name: string
 	color: string
@@ -184,17 +172,13 @@ export interface Role {
 	isHoisted: boolean
 }
 
-/**
- *
- */
+/** 频道级权限允许/拒绝覆写。 */
 export interface ChannelPermissionOverride {
 	allow: Partial<PermissionFlags>
 	deny: Partial<PermissionFlags>
 }
 
-/**
- *
- */
+/** 群频道元数据（文本、列表或流媒体）。 */
 export interface Channel {
 	id: string
 	type: 'text' | 'list' | 'streaming'
@@ -208,27 +192,21 @@ export interface Channel {
 	manualItems?: ListItem[]
 }
 
-/**
- *
- */
+/** 列表频道中的手动条目。 */
 export interface ListItem {
 	title: string
 	desc?: string
 	targetChannelId?: string
 	url?: string
 }
 
-/**
- *
- */
+/** 群文件区文件夹节点。 */
 export interface FileFolder {
 	name: string
 	parentFolderId: string | null
 }
 
-/**
- *
- */
+/** 群展示元数据（名称、头像与分叉信息）。 */
 export interface GroupMeta {
 	name: string
 	description: string
@@ -284,9 +262,7 @@ export interface GroupSettings {
 
 // ---- 信誉账本 / 邀请边 / 文件主密钥轮换 ----
 
-/**
- *
- */
+/** 信誉账本条目（slash 或 reset）。 */
 export interface ReputationLedgerEntry {
 	targetPubKeyHash: string
 	sender: string
@@ -296,9 +272,7 @@ export interface ReputationLedgerEntry {
 	payloadRef?: string
 }
 
-/**
- *
- */
+/** 邀请图边（入群关系与可选信誉边）。 */
 export interface InviteEdge {
 	from: string
 	to: string
@@ -308,19 +282,15 @@ export interface InviteEdge {
 	fileKeyWraps?: boolean
 }
 
-/**
- *
- */
+/** 文件主密钥轮换事件摘要。 */
 export interface FileMasterKeyRotationEntry {
 	eventId: string
 	generation: number
 	nonce: string
 	type: 'kick' | 'rotate'
 }
 
-/**
- *
- */
+/** 群共享文件元数据与分块清单。 */
 export interface FileInfo {
 	name: string
 	size: number
@@ -332,9 +302,7 @@ export interface FileInfo {
 	key_generation?: number
 }
 
-/**
- *
- */
+/** 加密文件单个分块的存储定位与哈希。 */
 export interface ChunkInfo {
 	chunkIndex: number
 	chunkHash: string
@@ -415,14 +383,10 @@ export interface SerializedGroupState extends GroupStateCore {
 	bannedNodes: string[]
 }
 
-/**
- *
- */
+/** checkpoint `members_record` 字段形态（序列化群状态）。 */
 export type CheckpointMembersRecord = SerializedGroupState
 
-/**
- *
- */
+/** DAG checkpoint 快照（epoch、overlay 与文件树等）。 */
 export interface Checkpoint {
 	local_node_id: string | null
 	members_record: CheckpointMembersRecord
@@ -441,18 +405,14 @@ export interface Checkpoint {
 	checkpoint_signature?: string
 }
 
-/**
- *
- */
+/** 入群 PoW 挑战（难度与时间戳）。 */
 export interface PowChallenge {
 	challenge: string
 	difficulty: number
 	timestamp: number
 }
 
-/**
- *
- */
+/** PoW 解答（nonce 与哈希）。 */
 export interface PowSolution {
 	nonce: number
 	hash: string

src/decl/socialAPI.ts

@@ -56,9 +56,7 @@ export interface SocialPostRef {
 	postId: string
 }
 
-/**
- *
- */
+/** 群 ref（群 id 与可选频道 id）。 */
 export interface SocialGroupRef {
 	groupId: string
 	channelId?: string
@@ -165,35 +163,25 @@ export interface SocialPollVoteContent extends SocialEngagementTarget {
 	choices: number[]
 }
 
-/**
- *
- */
+/** 点赞事件 content（复用互动 target 字段）。 */
 export type SocialLikeContent = SocialEngagementTarget
 
-/**
- *
- */
+/** 转发事件 content，可选附言。 */
 export interface SocialRepostContent extends SocialEngagementTarget {
 	comment?: string
 }
 
-/**
- *
- */
+/** 关注事件 content。 */
 export interface SocialFollowContent {
 	targetEntityHash: string
 }
 
-/**
- *
- */
+/** 拉黑事件 content。 */
 export interface SocialBlockContent {
 	targetEntityHash: string
 }
 
-/**
- *
- */
+/** 删帖事件 content。 */
 export interface SocialPostDeleteContent {
 	targetPostId: string
 }
@@ -329,9 +317,7 @@ export interface SocialRepostFeedItem extends SocialFeedItemBase {
 	repostComment: string
 }
 
-/**
- *
- */
+/** 时间线 feed 条目：原创帖或转发。 */
 export type SocialFeedItem = SocialPostFeedItem | SocialRepostFeedItem
 
 /** `GET /feed` 等分页响应。 */
@@ -364,9 +350,7 @@ export interface SocialNotificationItem {
 	aggregateKey?: string | null
 }
 
-/**
- *
- */
+/** 通知分页响应（含未读数与游标）。 */
 export interface SocialNotificationsPage {
 	notifications: SocialNotificationItem[]
 	nextCursor: string | null
@@ -383,17 +367,13 @@ export interface SocialFollowResponse {
 	isFollowing: boolean
 }
 
-/**
- *
- */
+/** 拉黑写操作响应。 */
 export interface SocialBlockResponse {
 	entityHash: string
 	blocked: boolean
 }
 
-/**
- *
- */
+/** 隐藏写操作响应。 */
 export interface SocialHideResponse {
 	entityHash: string
 	hidden: boolean
@@ -464,28 +444,22 @@ export interface SocialRpcDiscoverRequest {
 	cursor?: string
 }
 
-/**
- *
- */
+/** 联邦 RPC：账号发现响应。 */
 export interface SocialRpcDiscoverResponse {
 	type: 'social_discover_response'
 	accounts: SocialDiscoverAccount[]
 	nextCursor?: string | null
 }
 
-/**
- *
- */
+/** 联邦 RPC：帖子发现请求。 */
 export interface SocialRpcPostDiscoverRequest {
 	type: 'social_post_discover_request'
 	n?: number
 	mediaOnly?: boolean
 	cursor?: string
 }
 
-/**
- *
- */
+/** 联邦 RPC：帖子发现响应。 */
 export interface SocialRpcPostDiscoverResponse {
 	type: 'social_post_discover_response'
 	posts: SocialDiscoverPost[]
@@ -506,9 +480,7 @@ export interface SocialMessageEvent {
 	lang: string
 }
 
-/**
- *
- */
+/** char 社交接口入站关注事件。 */
 export interface SocialFollowEvent {
 	username: string
 	charPartName: string
@@ -517,9 +489,7 @@ export interface SocialFollowEvent {
 	targetEntityHash: string
 }
 
-/**
- *
- */
+/** char.interfaces.social 可选回调面。 */
 export interface SocialCharInterface {
 	OnMessage?: (event: SocialMessageEvent) => Promise<boolean>
 	OnFollow?: (event: SocialFollowEvent) => Promise<void>