📝 Add docstrings to ve-compat-entry

Docstrings generation was requested by @black7375.

* #219 (comment)

The following files were modified:

* `packages/babel/src/styled.ts`
* `packages/css/src/css/index.ts`
* `packages/css/src/rules/index.ts`

Author: coderabbitai[bot]

packages/babel/src/styled.ts

@@ -3,12 +3,11 @@ import type { PluginState, ProgramScope } from "@/types.js";
 import { registerImportMethod } from "@/utils.js";
 
 /**
- * The plugin for transforming styled components
+ * Babel plugin that transforms `styled` calls from "@mincho-js/react" into runtime calls with tree-shaking annotations.
  *
- * This plugin transforms calls to `styled` from "@mincho-js/react" into runtime
- * calls with proper tree-shaking annotations.
+ * Replaces calls to `styled` with calls to runtime-imported `$$styled` and `rules`, preserving comments and source locations for accurate source maps. Ensures transformed calls are annotated for tree-shaking and updates scope references after transformation.
  *
- * @returns The plugin object
+ * @returns A Babel plugin object for transforming styled component calls.
  */
 export function styledComponentPlugin(): PluginObj<PluginState> {
   return {

packages/css/src/css/index.ts

@@ -14,7 +14,14 @@ import { style as vStyle, globalStyle as gStyle } from "@vanilla-extract/css";
 import type { GlobalStyleRule } from "@vanilla-extract/css";
 import { className, getDebugName } from "../utils.js";
 
-// == Global CSS ===============================================================
+/**
+ * Applies a global CSS rule to the specified selector, supporting nested at-rules.
+ *
+ * Transforms the provided rule and applies it globally, including any nested at-rules such as `@media` or `@supports`.
+ *
+ * @param selector - The CSS selector to which the global rule will be applied
+ * @param rule - The global CSS rule object to apply
+ */
 export function globalCss(selector: string, rule: GlobalCSSRule) {
   const transformedStyle = transform({
     selectors: {
@@ -100,7 +107,15 @@ function hoistSelectors(input: CSSRule): HoistResult {
   return result;
 }
 
-// == CSS ======================================================================
+/**
+ * Creates a CSS class from a complex style rule.
+ *
+ * Transforms the provided style rule and generates a class name using vanilla-extract.
+ *
+ * @param style - The complex CSS rule to transform and apply
+ * @param debugId - Optional identifier for debugging or naming the class
+ * @returns The generated CSS class name
+ */
 export function css(style: ComplexCSSRule, debugId?: string) {
   return vStyle(transform(style), debugId);
 }
@@ -117,6 +132,16 @@ export function cssVariants<
   Key extends keyof Data,
   MapData extends (value: Data[Key], key: Key) => ComplexCSSRule
 >(data: Data, mapData: MapData, debugId?: string): Record<keyof Data, string>;
+/**
+ * Generates a map of class names for style variants, supporting both direct style maps and data-to-style mapping functions.
+ *
+ * Accepts either a map of style objects keyed by variant names, or a data object with a mapping function that produces style rules for each key.
+ *
+ * @param styleMapOrData - Either a style map or a data object to generate variants from
+ * @param mapDataOrDebugId - A mapping function to convert data items to style rules, or a debug identifier if using a style map
+ * @param debugId - Optional debug identifier for naming the generated classes
+ * @returns A map of variant keys to generated class names
+ */
 export function cssVariants<
   StyleMap extends Record<string | number, ComplexCSSRule>,
   Data extends Record<string | number, unknown>,
@@ -137,6 +162,11 @@ export function cssVariants<
   }
 }
 
+/**
+ * Type guard that determines if the provided argument is a mapping function for variant data.
+ *
+ * @returns `true` if the argument is a function; otherwise, `false`
+ */
 function isMapDataFunction<
   Data extends Record<string | number, unknown>,
   Key extends keyof Data,

packages/css/src/rules/index.ts

@@ -47,6 +47,13 @@ function setCSSProperty(
   styles[property] = value;
 }
 
+/**
+ * Creates a runtime CSS style function supporting variants, toggle variants, compound variants, and CSS property variables.
+ *
+ * @param options - Pattern options defining base styles, variants, toggles, compound variants, default variants, and props
+ * @param debugId - Optional identifier used for debugging and naming generated classes and variables
+ * @returns A runtime function that generates class names and CSS variable mappings based on selected variants and props
+ */
 export function rules<
   Variants extends VariantGroups | undefined = undefined,
   ToggleVariants extends VariantDefinitions | undefined = undefined,
@@ -185,6 +192,16 @@ export function rules<
   );
 }
 
+/**
+ * Processes a prop definition object to generate CSS variables and assign them to specified CSS properties.
+ *
+ * For each prop, creates a CSS variable (optionally with a debug name), stores its key in `propVars`, and sets the variable as the value for each target CSS property in `propStyles`. If a base value is provided, uses it as a fallback.
+ *
+ * @param props - The prop definitions mapping prop names to their configuration
+ * @param propVars - Object to store generated CSS variable keys for each prop
+ * @param propStyles - CSS rule object to which the variables are assigned as property values
+ * @param debugId - Optional identifier used for debugging and variable naming
+ */
 function processPropObject<Target extends PropTarget>(
   props: PropDefinition<Target>,
   propVars: Record<string, PureCSSVarKey>,