From c6c077b011898068ee04c9b9b2ef036acc87749f Mon Sep 17 00:00:00 2001
From: Ansolve <rNonameBusiness@yeah.net>
Date: Thu, 16 Nov 2023 18:15:54 +0800
Subject: [PATCH] docs(lib): add `lib.announce` docs.

---
 game/game.js | 51 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/game/game.js b/game/game.js
index 0986cd877..1325446c7 100644
--- a/game/game.js
+++ b/game/game.js
@@ -355,7 +355,29 @@
 			}],
 		},
 		/**
+		 * **无名杀消息推送库**
 		 * 
+		 * 通过`EventTarget`机制，实现消息推送和接收的解耦，
+		 * 从而使消息接收方无需依赖发布方，发布方也无需考虑接收方
+		 * 
+		 * > `lib.announce`不是`actor`模型，若不存在订阅者，则消息发送将无意义
+		 * 
+		 * @example
+		 * // 甲扩展（如《千幻聆音》）在角色皮肤切换后，调用：
+		 * lib.announce.publish("skinChange", {
+		 * 	player,
+		 * 	playerName: "zhangfei",
+		 * 	originSkin: "image/xxx.jpg",
+		 * 	currentSkin: "image/yyy.jpg"
+		 * });
+		 * 
+		 * // 乙扩展监听此`skinChange`事件，并修改自己扩展相关界面的图片：
+		 * const method = lib.announce.subscribe("skinChange", (e) => {
+		 * 	div.setBackgroundImage(e.currentSkin);
+		 * });
+		 * 
+		 * // 若此时乙扩展不想继续订阅`skinChange`事件，可以通过`unsubscribe`解除订阅
+		 * lib.announce.unsubscribe("skinChange", method);
 		 */
 		announce:new class{
 			constructor(){
@@ -370,7 +392,14 @@
 			}
 
 			/**
-			 * 推送一个对象给所有监听了name的订阅者
+			 * 推送任意数据给所有监听了指定事件的订阅者，并返回给定的数据
+			 * 
+			 * 若不存在订阅指定事件的订阅者，则推送的数据将无意义
+			 * 
+			 * @template T
+			 * @param {string} name - 要推送事件的名称
+			 * @param {T} values - 要推送的数据
+			 * @returns {T}
 			 */
 			publish(name,values){
 				if(this._announce) this._announce.dispatchEvent(new CustomEvent(name,{
@@ -380,7 +409,16 @@
 			}
 
 			/**
-			 * 订阅name相关的事件
+			 * 订阅给定名字的事件，并返回给定的函数
+			 * 
+			 * 在事件触发时执行给定的函数
+			 * 
+			 * 给定的函数将被存储至当前实例中，用于取消订阅时获取
+			 * 
+			 * @template T
+			 * @param {string} name - 要订阅事件的名称
+			 * @param {(values: T) => void} method - 事件触发时执行的函数
+			 * @returns {(values: T) => void}
 			 */
 			subscribe(name,method){
 				if(this._announce&&this._announce_cache) {
@@ -403,7 +441,14 @@
 			}
 
 			/**
-			 * 取消对事件name的订阅
+			 * 取消指定事件某一函数的订阅，并返回该函数
+			 * 
+			 * 给定的函数将不再于事件触发时执行，其余同事件需触发的函数不受限制
+			 * 
+			 * @template T
+			 * @param {string} name - 要取消订阅事件的名称
+			 * @param {(values: T) => void} method - 订阅指定事件的函数
+			 * @returns {(values: T) => void}
 			 */
 			unsubscribe(name,method){
 				if(this._announce&&this._announce_cache&&this._announce_cache.has(method)){