Fixes #2634 - Comments gate.ts

While reading the codebase, I was briefly confused by the gate decorator.
Here, I've added comments to the decorator to make it easier to understand.
I'm hoping these comments will help others dive through the codebase as well 🙂

src/system/decorators/gate.ts

@@ -2,8 +2,14 @@
 import { isPromise } from '../promise';
 import { resolveProp } from './resolver';
 
+/**
+ * A decorator that gates the execution of a method or getter.
+ * It ensures that the decorated method is executed only once at a time
+ * by forcing subsequent calls to wait for the previous execution to complete.
+ */
 export function gate<T extends (...arg: any) => any>(resolver?: (...args: Parameters<T>) => string) {
 	return (target: any, key: string, descriptor: PropertyDescriptor) => {
+		// Stores the original method or getter function in fn variable
 		let fn: Function | undefined;
 		if (typeof descriptor.value === 'function') {
 			fn = descriptor.value;
@@ -12,10 +18,15 @@ export function gate<T extends (...arg: any) => any>(resolver?: (...args: Parame
 		}
 		if (fn == null) throw new Error('Not supported');
 
+		// Creates a unique gate key
 		const gateKey = `$gate$${key}`;
 
+		// Replaces the descriptor value with a new function
 		descriptor.value = function (this: any, ...args: any[]) {
+			// Resolves the gate key using the resolver function
 			const prop = resolveProp(gateKey, resolver, ...(args as Parameters<T>));
+
+			// Checks if a promise has already been created for the method
 			if (!Object.prototype.hasOwnProperty.call(this, prop)) {
 				Object.defineProperty(this, prop, {
 					configurable: false,
@@ -25,15 +36,21 @@ export function gate<T extends (...arg: any) => any>(resolver?: (...args: Parame
 				});
 			}
 
+			// If a promise exists, return it
 			let promise = this[prop];
 			if (promise === undefined) {
 				let result;
 				try {
+					// Call the original method
 					result = fn!.apply(this, args);
+
+					// If the result is not a promise, return it
 					if (result == null || !isPromise(result)) {
 						return result;
 					}
 
+					// If the result is a promise, set up .then and .catch
+					// handlers to clear the promise on completion
 					this[prop] = promise = result
 						.then((r: any) => {
 							this[prop] = undefined;
@@ -49,6 +66,7 @@ export function gate<T extends (...arg: any) => any>(resolver?: (...args: Parame
 				}
 			}
 
+			// Return the ongoing promise
 			return promise;
 		};
 	};