Added doc comment to alert()

packages/frontend/src/os.ts

@@ -136,7 +136,16 @@ export function promiseDialog<T extends Promise<any>>(
 	return promise;
 }
 
+/**
+ * Counter for generating unique popup IDs.
+ * @type {number}
+ */
 let popupIdCount = 0;
+
+/**
+ * A reactive list of the currently opened popups. This is used in a Vue component
+ * in a v-for loop to render the popups.
+ */
 export const popups = ref<{
 	id: number;
 	component: Component;
@@ -144,12 +153,23 @@ export const popups = ref<{
 	events: Record<string, any>;
 }[]>([]);
 
+/**
+ * An object containing z-index values for different priority levels.
+ */
 const zIndexes = {
 	veryLow: 500000,
 	low: 1000000,
 	middle: 2000000,
 	high: 3000000,
 };
+
+/**
+ * Claims a z-index value for a given priority level.
+ * Increments the z-index value for the specified priority by 100 and returns the new value.
+ *
+ * @param {keyof typeof zIndexes} [priority='low'] - The priority level for which to claim a z-index.
+ * @returns {number} The new z-index value for the specified priority.
+ */
 export function claimZIndex(priority: keyof typeof zIndexes = 'low'): number {
 	zIndexes[priority] += 100;
 	return zIndexes[priority];
@@ -177,6 +197,15 @@ type EmitsExtractor<T> = {
 	[K in keyof T as K extends `onVnode${string}` ? never : K extends `on${infer E}` ? Uncapitalize<E> : K extends string ? never : K]: T[K];
 };
 
+/**
+ * Opens a popup with the specified component, props, and events.
+ *
+ * @template T - The type of the component.
+ * @param {T} component - The Vue component to display in the popup.
+ * @param {ComponentProps<T>} props - The props to pass to the component.
+ * @param {ComponentEmit<T>} [events={}] - The events to bind to the component.
+ * @returns {{ dispose: () => void }} An object containing a dispose function to close the popup.
+ */
 export function popup<T extends Component>(
 	component: T,
 	props: ComponentProps<T>,
@@ -184,13 +213,18 @@ export function popup<T extends Component>(
 ): { dispose: () => void } {
 	markRaw(component);
 
+	// Generate a unique ID for this popup.
 	const id = ++popupIdCount;
+
+	// On disposal, remove this popup from the list of open popups.
 	const dispose = () => {
 		// このsetTimeoutが無いと挙動がおかしくなる(autocompleteが閉じなくなる)。Vueのバグ？
 		window.setTimeout(() => {
 			popups.value = popups.value.filter(p => p.id !== id);
 		}, 0);
 	};
+
+	// Bundle the component, props, and events into a state object.
 	const state = {
 		component,
 		props,
@@ -198,13 +232,19 @@ export function popup<T extends Component>(
 		id,
 	};
 
+	// Add the popup to the list of open popups.
 	popups.value.push(state);
 
+	// Return a function that can be called to close the popup.
 	return {
 		dispose,
 	};
 }
 
+/**
+ * Open the page with the given path in a pop-up window.
+ * @param path The path of the page to open.
+ */
 export function pageWindow(path: string) {
 	const { dispose } = popup(MkPageWindow, {
 		initialPath: path,
@@ -213,6 +253,11 @@ export function pageWindow(path: string) {
 	});
 }
 
+/**
+ * Displays a toast message to the user.
+ *
+ * @param {string} message - The message to display in the toast.
+ */
 export function toast(message: string) {
 	const { dispose } = popup(MkToast, {
 		message,
@@ -221,6 +266,15 @@ export function toast(message: string) {
 	});
 }
 
+/**
+ * Displays an alert dialog to the user.
+ *
+ * @param {Object} props - The properties for the alert dialog.
+ * @param {'error' | 'info' | 'success' | 'warning' | 'waiting' | 'question'} [props.type] - The type of the alert.
+ * @param {string} [props.title] - The title of the alert dialog.
+ * @param {string} [props.text] - The text content of the alert dialog.
+ * @returns {Promise<void>} A promise that resolves when the alert dialog is closed.
+ */
 export function alert(props: {
 	type?: 'error' | 'info' | 'success' | 'warning' | 'waiting' | 'question';
 	title?: string;