chore(client): add some documentation

eliandoran · eliandoran · commit 4ec46a2ebd92 · 2025-08-20T20:34:00.000+03:00
diff --git a/apps/client/src/services/options.ts b/apps/client/src/services/options.ts
@@ -77,6 +77,10 @@ class Options {
         await server.put(`options`, payload);
     }
 
+    /**
+     * Saves multiple options at once, by supplying a record where the keys are the option names and the values represent the stringified value to set.
+     * @param newValues the record of keys and values.
+     */
     async saveMany<T extends OptionNames>(newValues: Record<T, OptionValue>) {
         await server.put<void>("options", newValues);
     }
diff --git a/apps/client/src/services/utils.ts b/apps/client/src/services/utils.ts
@@ -378,6 +378,12 @@ async function openInAppHelp($button: JQuery<HTMLElement>) {
     }
 }
 
+/**
+ * Opens the in-app help at the given page in a split note. If there already is a split note open with a help page, it will be replaced by this one.
+ *
+ * @param inAppHelpPage the ID of the help note (excluding the `_help_` prefix).
+ * @returns a promise that resolves once the help has been opened.
+ */
 export async function openInAppHelpFromUrl(inAppHelpPage: string) {
     // Dynamic import to avoid import issues in tests.
     const appContext = (await import("../components/app_context.js")).default;
@@ -738,6 +744,14 @@ function isLaunchBarConfig(noteId: string) {
     return ["_lbRoot", "_lbAvailableLaunchers", "_lbVisibleLaunchers", "_lbMobileRoot", "_lbMobileAvailableLaunchers", "_lbMobileVisibleLaunchers"].includes(noteId);
 }
 
+/**
+ * Adds a class to the <body> of the page, where the class name is formed via a prefix and a value.
+ * Useful for configurable options such as `heading-style-markdown`, where `heading-style` is the prefix and `markdown` is the dynamic value.
+ * There is no separator between the prefix and the value, if needed it has to be supplied manually to the prefix.
+ *
+ * @param prefix the prefix.
+ * @param value the value to be appended to the prefix.
+ */
 export function toggleBodyClass(prefix: string, value: string) {
     const $body = $("body");
     for (const clazz of Array.from($body[0].classList)) {
@@ -750,6 +764,13 @@ export function toggleBodyClass(prefix: string, value: string) {
     $body.addClass(prefix + value);
 }
 
+/**
+ * Basic comparison for equality between the two arrays. The values are strictly checked via `===`.
+ *
+ * @param a the first array to compare.
+ * @param b the second array to compare.
+ * @returns `true` if both arrays are equals, `false` otherwise.
+ */
 export function arrayEqual<T>(a: T[], b: T[]) {
     if (a === b) {
         return true;
diff --git a/apps/client/src/widgets/react/hooks.tsx b/apps/client/src/widgets/react/hooks.tsx
@@ -145,6 +145,13 @@ export function useTriliumOption(name: OptionNames, needsRefresh?: boolean): [st
     ]
 }
 
+/**
+ * Similar to {@link useTriliumOption}, but the value is converted to and from a boolean instead of a string.
+ * 
+ * @param name the name of the option to listen for.
+ * @param needsRefresh whether to reload the frontend whenever the value is changed.
+ * @returns an array where the first value is the current option value and the second value is the setter.
+ */
 export function useTriliumOptionBool(name: OptionNames, needsRefresh?: boolean): [boolean, (newValue: boolean) => Promise<void>] {
     const [ value, setValue ] = useTriliumOption(name, needsRefresh);
     return [
@@ -153,6 +160,13 @@ export function useTriliumOptionBool(name: OptionNames, needsRefresh?: boolean):
     ]
 }
 
+/**
+ * Similar to {@link useTriliumOption}, but the value is converted to and from a int instead of a string.
+ * 
+ * @param name the name of the option to listen for.
+ * @param needsRefresh whether to reload the frontend whenever the value is changed.
+ * @returns an array where the first value is the current option value and the second value is the setter.
+ */
 export function useTriliumOptionInt(name: OptionNames): [number, (newValue: number) => Promise<void>] {
     const [ value, setValue ] = useTriliumOption(name);
     return [
@@ -161,6 +175,12 @@ export function useTriliumOptionInt(name: OptionNames): [number, (newValue: numb
     ]
 }
 
+/**
+ * Similar to {@link useTriliumOption}, but the object value is parsed to and from a JSON instead of a string.
+ * 
+ * @param name the name of the option to listen for.
+ * @returns an array where the first value is the current option value and the second value is the setter.
+ */
 export function useTriliumOptionJson<T>(name: OptionNames): [ T, (newValue: T) => Promise<void> ] {
     const [ value, setValue ] = useTriliumOption(name);
     return [
@@ -169,6 +189,12 @@ export function useTriliumOptionJson<T>(name: OptionNames): [ T, (newValue: T) =
     ];
 }
 
+/**
+ * Similar to {@link useTriliumOption}, but operates with multiple options at once. 
+ * 
+ * @param names the name of the option to listen for.
+ * @returns an array where the first value is a map where the keys are the option names and the values, and the second value is the setter which takes in the same type of map and saves them all at once.
+ */
 export function useTriliumOptions<T extends OptionNames>(...names: T[]) {
     const values: Record<string, string> = {};
     for (const name of names) {

Original file line number	Diff line number	Diff line change
`@@ -77,6 +77,10 @@ class Options {`
`77`	`77`	await server.put(`options`, payload);
`78`	`78`	`}`
`79`	`79`
	`80`	`+ /**`
	`81`	`+ * Saves multiple options at once, by supplying a record where the keys are the option names and the values represent the stringified value to set.`
	`82`	`+ * @param newValues the record of keys and values.`
	`83`	`+ */`
`80`	`84`	`async saveMany<T extends OptionNames>(newValues: Record<T, OptionValue>) {`
`81`	`85`	`await server.put<void>("options", newValues);`
`82`	`86`	`}`