Add clarifying comments

Author: youknowriad

packages/global-styles-engine/src/utils/common.ts

@@ -524,6 +524,20 @@ function getValueFromCustomVariable(
 	return getValueFromVariable( features, blockName, result as string );
 }
 
+/**
+ * Attempts to fetch the value of a theme.json CSS variable.
+ *
+ * This function resolves CSS variable references in two formats:
+ * - User format: `var:preset|color|red` or `var:custom|spacing|small`
+ * - Theme format: `var(--wp--preset--color--red)` or `var(--wp--custom--spacing--small)`
+ *
+ * It also handles ref-style variables in the format `{ ref: "path.to.value" }`.
+ *
+ * @param features  GlobalStylesContext config (user, base, or merged). Represents the theme.json tree.
+ * @param blockName The name of a block as represented in the styles property. E.g., 'root' for root-level, and 'core/block-name' for blocks.
+ * @param variable  An incoming style value. A CSS var value is expected, but it could be any value.
+ * @return The value of the CSS var, if found. If not found, returns the original variable argument.
+ */
 export function getValueFromVariable(
 	features: GlobalStylesConfig,
 	blockName?: string,

packages/global-styles-engine/src/utils/object.ts

@@ -35,6 +35,20 @@ export function setImmutably(
 	return object;
 }
 
+/**
+ * Helper util to return a value from a certain path of the object.
+ *
+ * Path is specified as either:
+ * - a string of properties, separated by dots, for example: "x.y".
+ * - an array of properties, for example `[ 'x', 'y' ]`.
+ *
+ * You can also specify a default value in case the result is nullish.
+ *
+ * @param object       Input object.
+ * @param path         Path to the object property.
+ * @param defaultValue Default value if the value at the specified path is nullish.
+ * @return Value of the object property at the specified path.
+ */
 export const getValueFromObjectPath = (
 	object: Object,
 	path: string | string[],

packages/global-styles-engine/src/utils/typography.ts

@@ -5,13 +5,31 @@ import type {
 	TypographyPreset,
 	GlobalStylesSettings,
 	FluidTypographySettings,
+	TypographySettings,
 } from '../types';
 import {
 	getTypographyValueAndUnit,
 	getComputedFluidTypographyValue,
 } from './fluid';
 
-function isFluidTypographyEnabled( typographySettings?: { fluid?: any } ) {
+/**
+ * Checks if fluid typography is enabled in the given typography settings.
+ *
+ * Fluid typography is considered enabled if the fluid setting is explicitly set to true,
+ * or if it's an object with properties (which would contain fluid typography configuration
+ * like minViewportWidth, maxViewportWidth, etc.).
+ *
+ * @param typographySettings       Typography settings object that may contain fluid typography configuration.
+ * @param typographySettings.fluid Fluid typography configuration. Can be:
+ *                                 - `true` to enable with default settings
+ *                                 - An object with fluid settings (minViewportWidth, maxViewportWidth, etc.)
+ *                                 - `false` or `undefined` to disable
+ *
+ * @return True if fluid typography is enabled, false otherwise.
+ */
+function isFluidTypographyEnabled(
+	typographySettings?: TypographySettings | TypographyPreset
+) {
 	const fluidSettings = typographySettings?.fluid;
 	return (
 		true === fluidSettings ||