docs: mutex.

noname/util/mutex.js

@@ -1,18 +1,24 @@
 /**
- * 
+ * 一个非常普通的“锁”
  */
 export class Mutex {
 	/**
+	 * 锁目前的状态，只有“unlocked”和“locked”两种情况
+	 * 
 	 * @type {'locked' | 'unlocked'}
 	 */
 	#status;
 
 	/**
+	 * 上锁后用于等待的锁Promise
+	 * 
 	 * @type {null | Promise<void>}
 	 */
 	#promise;
 
 	/**
+	 * 上锁后用于触发锁Promise的resolve函数
+	 * 
 	 * @type {null | function(): void}
 	 */
 	#resolve;
@@ -23,6 +29,11 @@ export class Mutex {
 		this.#resolve = null;
 	}
 
+	/**
+	 * 上锁
+	 * 
+	 * 请时刻记住使用`await Mutex#lock()`来使锁正常工作
+	 */
 	async lock() {
 		switch (this.#status) {
 			case 'locked':
@@ -36,6 +47,11 @@ export class Mutex {
 		}
 	}
 
+	/**
+	 * 解锁
+	 * 
+	 * 请不要在未上锁的情况下解锁
+	 */
 	unlock() {
 		if (this.#status === 'unlocked') throw new Error('This Mutex is not locked.');
 
@@ -44,6 +60,7 @@ export class Mutex {
 	}
 
 	/**
+	 * 启用锁的try-finally封装，用于在函数执行完后自动解放锁的控制权（就算发生错误）
 	 * 
 	 * @param {function(): void | Promise<void>} content
 	 */