docs: added jsdocs to exported functions

src/css.ts

@@ -64,15 +64,36 @@ export function* parseFontFace(
   yield { family: '', source: '' }
 }
 
+/**
+ * Generates a fallback name based on the first font family specified in the input string.
+ * @param {string} name - The full font family string.
+ * @returns {string} - The fallback font name.
+ */
 export function generateFallbackName(name: string) {
   const firstFamily = withoutQuotes(name.split(',').shift()!)
   return `${firstFamily} fallback`
 }
 
 interface FallbackOptions {
+  /**
+   * The name of the fallback font.
+   */
   name: string
+
+  /**
+   * The fallback font family name.
+   */
   font: string
+
+  /**
+   * Metrics for fallback face calculations.
+   * @optional
+   */
   metrics?: FontFaceMetrics
+
+  /**
+   * Additional properties that may be included dynamically
+   */
   [key: string]: any
 }
 
@@ -81,6 +102,12 @@ export type FontFaceMetrics = Pick<
   'ascent' | 'descent' | 'lineGap' | 'unitsPerEm' | 'xWidthAvg'
 >
 
+/**
+ * Generates a CSS `@font-face' declaration for a font, taking fallback and resizing into account.
+ * @param {FontFaceMetrics} metrics - The metrics of the preferred font. See {@link FontFaceMetrics}.
+ * @param {FallbackOptions} fallback - The fallback options, including name, font and optional metrics. See {@link FallbackOptions}.
+ * @returns {string} - The full `@font-face` CSS declaration.
+ */
 export function generateFontFace(metrics: FontFaceMetrics, fallback: FallbackOptions) {
   const {
     name: fallbackName,

src/metrics.ts

@@ -27,6 +27,12 @@ function filterRequiredMetrics({
   }
 }
 
+/**
+ * Retrieves the font metrics for a given font family from the metrics collection. Uses caching to avoid redundant calculations.
+ * @param {string} family - The name of the font family for which metrics are requested.
+ * @returns {Promise<FontFaceMetrics | null>} - A promise that resolves with the filtered font metrics or null if not found. See {@link FontFaceMetrics}.
+ * @async
+ */
 export async function getMetricsForFamily(family: string) {
   family = withoutQuotes(family)
 
@@ -51,6 +57,13 @@ export async function getMetricsForFamily(family: string) {
   }
 }
 
+/**
+ * Reads font metrics from a specified source URL or file path. This function supports both local files and remote URLs.
+ * It caches the results to optimise subsequent requests for the same source.
+ * @param {URL | string} _source - The source URL or local file path from which to read the font metrics.
+ * @returns {Promise<FontFaceMetrics | null>} - A promise that resolves to the filtered font metrics or null if the source cannot be processed.
+ * @async
+ */
 export async function readMetrics(_source: URL | string) {
   const source
     = typeof _source !== 'string' && 'href' in _source ? _source.href : _source

src/transform.ts

@@ -14,14 +14,49 @@ import { generateFallbackName, generateFontFace, parseFontFace } from './css'
 import { getMetricsForFamily, readMetrics } from './metrics'
 
 export interface FontaineTransformOptions {
-  css?: { value?: string }
+  /**
+   * Configuration options for the CSS transformation.
+   * @optional
+   */
+  css?: {
+    /**
+     * Holds the current value of the CSS being transformed.
+     * @optional
+     */
+    value?: string
+  }
+
+  /**
+   * An array of fallback font family names to use.
+   */
   fallbacks: string[]
+
+  /**
+   * Function to resolve a given path to a valid URL or local path.
+   * This is typically used to resolve font file paths.
+   * @optional
+   */
   resolvePath?: (path: string) => string | URL
+
+  /**
+   * A function to determine whether to skip font face generation for a given fallback name.
+   * @optional
+   */
   skipFontFaceGeneration?: (fallbackName: string) => boolean
-  /** this should produce an unquoted font family name */
+
+  /**
+   * Function to generate an unquoted font family name to use as a fallback.
+   * This should return a valid CSS font family name and should not include quotes.
+   * @optional
+   */
   fallbackName?: (name: string) => string
   /** @deprecated use fallbackName */
   overrideName?: (name: string) => string
+
+  /**
+   * Specifies whether to create a source map for the transformation.
+   * @optional
+   */
   sourcemap?: boolean
 }
 
@@ -51,6 +86,12 @@ const CSS_RE = createRegExp(
     .at.lineEnd(),
 )
 
+/**
+ * Transforms CSS files to include font fallbacks.
+ * 
+ * @param options - The transformation options. See {@link FontaineTransformOptions}.
+ * @returns The unplugin instance.
+ */
 export const FontaineTransform = createUnplugin(
   (options: FontaineTransformOptions) => {
     const cssContext = (options.css = options.css || {})