chore: update module documentation (#3)

Author: Hebilicious

.changeset/tiny-hats-cough.md

@@ -0,0 +1,5 @@
+---
+"@hebilicious/cssforge": patch
+---
+
+chore: update module documentation

src/cli.ts

@@ -1,3 +1,10 @@
+/**
+ * This module provides the command-line interface (CLI) for CSSForge.
+ * It allows generating CSS variables from a configuration file, with options
+ * to watch for changes and specify output formats.
+ *
+ * @module
+ */
 import { defineCommand, runMain } from "citty";
 import chokidar from "chokidar";
 import fs from "node:fs/promises";
@@ -12,14 +19,27 @@ const writeFileRecursive = (path: string, data: string) =>
     fs.writeFile(path, data)
   );
 
+/**
+ * Defines the options for the build command.
+ */
 export interface BuildOptions {
+  /** Path to the configuration file. */
   config: string;
+  /** The output mode. */
   mode: "css" | "json" | "ts" | "all";
+  /** Path for the CSS output file. */
   cssOutput: string;
+  /** Path for the JSON output file. */
   jsonOutput: string;
+  /** Path for the TypeScript output file. */
   tsOutput: string;
 }
 
+/**
+ * Builds the CSS, JSON, and/or TypeScript files based on the configuration.
+ * @param options The build options.
+ * @returns A promise that resolves to an object indicating success or failure.
+ */
 export async function build(
   { config, tsOutput, cssOutput, jsonOutput, mode }: BuildOptions,
 ): Promise<{ success: boolean; error?: unknown }> {
@@ -64,10 +84,19 @@ export async function build(
   }
 }
 
+/**
+ * Defines the options for the watch command.
+ */
 export interface WatchOptions extends BuildOptions {
+  /** A callback function to execute on rebuild. */
   onRebuild?: () => void;
 }
 
+/**
+ * Watches the configuration file for changes and rebuilds on modification.
+ * @param options The watch options.
+ * @returns A promise that resolves to a function to stop watching.
+ */
 export async function watch(
   { onRebuild, ...buildOptions }: WatchOptions,
 ): Promise<() => void> {
@@ -167,5 +196,7 @@ if (import.meta.main) {
   runMain(mainCommand);
 }
 
-// Export for programmatic usage
+/**
+ * The main command definition for the CSSForge CLI.
+ */
 export default mainCommand as CommandDef;

src/generator.ts

@@ -19,6 +19,11 @@ type ForgeValue = {
   [key: string]: ForgeValue | CssValue;
 };
 
+/**
+ * Creates a nested object structure of design tokens from a configuration.
+ * @param config The CSSForge configuration.
+ * @returns A nested object representing the design tokens.
+ */
 export function createForgeValues(config: Partial<CSSForgeConfig>) {
   type Input = readonly [string, CssValue];
 

src/lib.ts

@@ -1,10 +1,20 @@
+/**
+ * A map where keys are dot-separated paths and values are objects
+ * containing the CSS variable key, its value, and the full variable declaration.
+ */
 export type ResolveMap = Map<
   string,
   { key: string; value: string; variable: string }
 >;
 
+/**
+ * Represents the output of a processing function, containing the generated
+ * CSS and a resolve map.
+ */
 export interface Output {
+  /** The generated CSS string. */
   css: string;
+  /** A map for resolving variable paths. */
   resolveMap: ResolveMap;
 }
 

src/mod.ts

@@ -1,3 +1,11 @@
+/**
+ * This module provides the core functionalities of CSSForge, a tool for generating
+ * CSS variables from a configuration file. It exports functions for processing
+ * different aspects of a design system, such as colors, typography, and spacing,
+ * as well as the main function to generate the final CSS.
+ *
+ * @module
+ */
 import { generateCSS } from "./generator.ts";
 import { defineConfig } from "./config.ts";
 import { processColors } from "./modules/colors.ts";
@@ -6,13 +14,46 @@ import { processPrimitives } from "./modules/primitive.ts";
 import { processSpacing } from "./modules/spacing.ts";
 
 import type { CSSForgeConfig } from "./config.ts";
+/**
+ * The main configuration object for CSSForge.
+ */
 export type { CSSForgeConfig };
 
 export {
+  /**
+   * A helper function to define the CSSForge configuration with type inference.
+   * @param config The CSSForge configuration.
+   * @returns The configuration object.
+   */
   defineConfig,
+  /**
+   * Generates the CSS string from a CSSForge configuration.
+   * @param config The CSSForge configuration.
+   * @returns The generated CSS string.
+   */
   generateCSS,
+  /**
+   * Processes the colors section of the configuration.
+   * @param colors The colors configuration.
+   * @returns A map of CSS variables for colors.
+   */
   processColors,
+  /**
+   * Processes the primitives section of the configuration.
+   * @param primitives The primitives configuration.
+   * @returns A map of CSS variables for primitives.
+   */
   processPrimitives,
+  /**
+   * Processes the spacing section of the configuration.
+   * @param spacing The spacing configuration.
+   * @returns A map of CSS variables for spacing.
+   */
   processSpacing,
+  /**
+   * Processes the typography section of the configuration.
+   * @param typography The typography configuration.
+   * @returns A map of CSS variables for typography.
+   */
   processTypography,
 };