@goast/kotlin 0.7.0 → 0.7.1

package/dist/src/ast/nodes/reference.js

@@ -3,6 +3,24 @@ import { KotlinFileBuilder } from '../../file-builder.js';
 import { KtNode } from '../node.js';
 import { writeKtNode, writeKtNodes } from '../utils/write-kt-node.js';
 import { ktGenericParameter } from './generic-parameter.js';
+/**
+ * Represents a reference to a named Kotlin type or declaration, such as `List<String>?` or `Foo::class`.
+ *
+ * Written in this order: the name, the generic arguments in angle brackets, then one suffix. The suffix is `::class`
+ * when `classReference` is set, `::` followed by `subReference` when that is set, or `?` when `nullable` is set. The
+ * suffixes exclude each other, so `nullable` has no effect when `classReference` or `subReference` is set.
+ *
+ * Writing a reference also imports it. When `packageName` is set and the builder is a `KotlinFileBuilder`, the file
+ * gets an import for `<packageName>.<name>`, unless the package is the package of the file itself. Imports that match
+ * the `globalImports` option of the generator configuration are left out when the import block is written. Builders
+ * with no registered handler, such as a plain string builder, only receive the name. The import is added when the
+ * reference is written, so use `addImport` or `ktReference.import` to add an import without writing the reference.
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktReference
+ * @see KtReference.registerAddImportHandler
+ */
 export class KtReference extends KtNode {
     static addImportHandlers = [
         {
@@ -10,12 +28,40 @@ export class KtReference extends KtNode {
             handler: (builder, reference) => builder.addImport(reference.name, reference.packageName),
         },
     ];
+    /**
+     * The name written verbatim, such as `List`. When `packageName` is set, the same name is imported.
+     */
     name;
+    /**
+     * The package the name is imported from, such as `com.example.models`. `null` writes the name without an import.
+     */
     packageName;
+    /**
+     * The generic arguments written in angle brackets after the name, such as `<String>` in `List<String>`. An empty list
+     * writes nothing.
+     */
     generics;
+    /**
+     * Whether a `?` is written after the name, which makes the type nullable. Ignored when `classReference` or
+     * `subReference` is set.
+     * @default false
+     */
     nullable;
+    /**
+     * Whether the reference is written as a class literal, such as `Foo::class`. Takes precedence over `subReference` and
+     * `nullable`.
+     * @default false
+     */
     classReference;
+    /**
+     * A reference or call written after `::`, such as `Bar` in `Foo::Bar`, or `null` for none. Takes precedence over
+     * `nullable`, and `classReference` takes precedence over it.
+     */
     subReference;
+    /**
+     * Initializes a new instance of the KtReference class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.name = options.name;
@@ -25,6 +71,11 @@ export class KtReference extends KtNode {
         this.classReference = options.classReference ?? false;
         this.subReference = options.subReference ?? null;
     }
+    /**
+     * Adds the import for this reference to the builder without writing the reference. Nothing is added when
+     * `packageName` is not set, or when no handler is registered for the class of the builder.
+     * @param builder The builder to add the import to.
+     */
     addImport(builder) {
         if (this.packageName) {
             const handler = KtReference.addImportHandlers.find((h) => builder instanceof h.builderClass);
@@ -48,6 +99,14 @@ export class KtReference extends KtNode {
         }
         this.addImport(builder);
     }
+    /**
+     * Registers a handler that adds imports for references written to builders of the given class. The handlers are tried
+     * in the order they were registered, and the first one whose class matches the builder is used. The handler for
+     * `KotlinFileBuilder` is registered first, so it also matches subclasses of that class.
+     * @template TBuilder The type of the builder that the handler supports.
+     * @param builderClass The class of the builders that the handler applies to.
+     * @param handler Adds the import for the reference to the builder.
+     */
     static registerAddImportHandler(builderClass, handler) {
         KtReference.addImportHandlers.push({ builderClass, handler });
     }
@@ -71,6 +130,22 @@ const createGenericFactory = (name, packageName) => {
 const importRefs = (builder, references) => {
     references.forEach((ref) => ref.addImport(builder));
 };
+/**
+ * Factory for creating reference nodes. The `factory` and `genericFactory` functions create factories for one fixed
+ * name and package, `import` adds the imports of references without writing them, and `write` writes one or more
+ * reference nodes to a builder.
+ *
+ * @param name The name of the referenced type, such as `List`.
+ * @param packageName The package the name is imported from, or `null` to write the name without an import.
+ * @param options The settings of the reference. See `KtReference` for the available properties.
+ * @example
+ * ```ts
+ * ktReference('User', 'com.example.models', { generics: ['String'], nullable: true });
+ * // Emits:
+ * // User<String>?
+ * // and adds the import `com.example.models.User` to the file.
+ * ```
+ */
 export const ktReference = Object.assign(createReference, {
     factory: createFactory,
     genericFactory: createGenericFactory,

package/dist/src/ast/nodes/string.d.ts

@@ -10,13 +10,55 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     marginPrefix?: Nullable<string>;
     autoAddMarginPrefix?: Nullable<boolean>;
 }>;
+/**
+ * Represents a Kotlin string literal, such as `"Hello"`, or the `null` literal when the value is `null`.
+ *
+ * The value is escaped like a JSON string, and `$` is escaped so that it stays literal, unless `template` is set. A
+ * multiline string is written as a raw string in triple quotes. Its line breaks are kept, and with `trimMargin` each
+ * line is prefixed with `marginPrefix` and the string is followed by `.trimMargin()`.
+ *
+ * @template TBuilder The type of the source builder the string is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktString
+ */
 export declare class KtString<TBuilder extends SourceBuilder, TInjects extends string = never> extends KtNode<TBuilder, TInjects | Injects> {
+    /**
+     * The text of the string, escaped as described above. `null` writes the Kotlin `null` literal instead of a string.
+     */
     value: string | null;
+    /**
+     * Whether `${...}` placeholders in the value are kept as Kotlin string templates. Otherwise `$` is escaped as
+     * `\$`, so the placeholder text is written literally.
+     * @default false
+     */
     template: boolean;
+    /**
+     * Whether the string is written as a raw string in triple quotes. Line breaks in the value become line breaks in the
+     * output, and without `trimMargin` the text is written in one piece.
+     * @default false
+     */
     multiline: boolean;
+    /**
+     * Whether a multiline string starts on a new line and is followed by `.trimMargin()`, the Kotlin call that removes
+     * the margin prefix at runtime. Has no effect on single-line strings.
+     * @default true
+     */
     trimMargin: boolean;
+    /**
+     * The prefix written at the start of each line of a multiline string, and passed to `trimMargin` as its argument,
+     * such as `.trimMargin("!")`. `null` uses `|` as the prefix and writes `.trimMargin()` without an argument.
+     */
     marginPrefix: string | null;
+    /**
+     * Whether the margin prefix is written at the start of each line of a multiline string. When `false`, the lines are
+     * written as they are, and `.trimMargin()` is still appended.
+     * @default true
+     */
     autoAddMarginPrefix: boolean;
+    /**
+     * Initializes a new instance of the KtString class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
     protected findTemplateParts(value: string): {
@@ -25,6 +67,21 @@ export declare class KtString<TBuilder extends SourceBuilder, TInjects extends s
     }[];
 }
 declare const createString: <TBuilder extends SourceBuilder>(value: Options<TBuilder>['value'], options?: Prettify<Omit<Options<TBuilder>, 'value'>>) => KtString<TBuilder>;
+/**
+ * Factory for creating string nodes. The `write` function writes one or more string nodes to a builder.
+ *
+ * @param value The text of the string, or `null` for the Kotlin `null` literal.
+ * @param options The settings of the string. See `KtString` for the available properties.
+ * @example
+ * ```ts
+ * ktString('first line\nsecond line', { multiline: true });
+ * // Emits:
+ * // """
+ * //     |first line
+ * //     |second line
+ * //     """.trimMargin()
+ * ```
+ */
 export declare const ktString: typeof createString & {
     write: typeof writeKtNodes;
 };

package/dist/src/ast/nodes/string.js

@@ -2,13 +2,55 @@ import { spliceString } from '@goast/core';
 import { KtNode } from '../node.js';
 import { writeKtNodes } from '../utils/write-kt-node.js';
 import { ktArgument } from './argument.js';
+/**
+ * Represents a Kotlin string literal, such as `"Hello"`, or the `null` literal when the value is `null`.
+ *
+ * The value is escaped like a JSON string, and `$` is escaped so that it stays literal, unless `template` is set. A
+ * multiline string is written as a raw string in triple quotes. Its line breaks are kept, and with `trimMargin` each
+ * line is prefixed with `marginPrefix` and the string is followed by `.trimMargin()`.
+ *
+ * @template TBuilder The type of the source builder the string is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktString
+ */
 export class KtString extends KtNode {
+    /**
+     * The text of the string, escaped as described above. `null` writes the Kotlin `null` literal instead of a string.
+     */
     value;
+    /**
+     * Whether `${...}` placeholders in the value are kept as Kotlin string templates. Otherwise `$` is escaped as
+     * `\$`, so the placeholder text is written literally.
+     * @default false
+     */
     template;
+    /**
+     * Whether the string is written as a raw string in triple quotes. Line breaks in the value become line breaks in the
+     * output, and without `trimMargin` the text is written in one piece.
+     * @default false
+     */
     multiline;
+    /**
+     * Whether a multiline string starts on a new line and is followed by `.trimMargin()`, the Kotlin call that removes
+     * the margin prefix at runtime. Has no effect on single-line strings.
+     * @default true
+     */
     trimMargin;
+    /**
+     * The prefix written at the start of each line of a multiline string, and passed to `trimMargin` as its argument,
+     * such as `.trimMargin("!")`. `null` uses `|` as the prefix and writes `.trimMargin()` without an argument.
+     */
     marginPrefix;
+    /**
+     * Whether the margin prefix is written at the start of each line of a multiline string. When `false`, the lines are
+     * written as they are, and `.trimMargin()` is still appended.
+     * @default true
+     */
     autoAddMarginPrefix;
+    /**
+     * Initializes a new instance of the KtString class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.value = options?.value ?? null;
@@ -82,6 +124,21 @@ export class KtString extends KtNode {
     }
 }
 const createString = (value, options) => new KtString({ ...options, value });
+/**
+ * Factory for creating string nodes. The `write` function writes one or more string nodes to a builder.
+ *
+ * @param value The text of the string, or `null` for the Kotlin `null` literal.
+ * @param options The settings of the string. See `KtString` for the available properties.
+ * @example
+ * ```ts
+ * ktString('first line\nsecond line', { multiline: true });
+ * // Emits:
+ * // """
+ * //     |first line
+ * //     |second line
+ * //     """.trimMargin()
+ * ```
+ */
 export const ktString = Object.assign(createString, {
     write: writeKtNodes,
 });

package/dist/src/ast/nodes/types.d.ts

@@ -6,5 +6,14 @@ import type { KtLambda } from './lambda.ts';
 import type { KtObject } from './object.ts';
 import type { KtReference } from './reference.ts';
 import type { KtString } from './string.ts';
+/**
+ * A value that can be written where a Kotlin type is expected: a reference, a lambda type, or any appended value.
+ * @template TBuilder The type of the builder that the type is written to.
+ */
 export type KtType<TBuilder extends SourceBuilder> = KtReference<TBuilder> | KtLambdaType<TBuilder> | BasicAppendValue<TBuilder>;
+/**
+ * A value that can be written where a Kotlin expression is expected, such as a default value or an argument: a
+ * reference, a string, a call, an object, a lambda, a collection literal, or any appended value.
+ * @template TBuilder The type of the builder that the value is written to.
+ */
 export type KtValue<TBuilder extends SourceBuilder> = KtReference<TBuilder> | KtString<TBuilder> | KtCall<TBuilder> | KtObject<TBuilder> | KtLambda<TBuilder> | KtCollectionLiteral<TBuilder> | BasicAppendValue<TBuilder>;

package/dist/src/ast/references/jackson.d.ts

@@ -1,17 +1,64 @@
+/**
+ * Pre-built references to Jackson types.
+ *
+ * Annotation references are fixed to `com.fasterxml.jackson.annotation` on Spring Boot 3 and 4. The databind and
+ * Kotlin module factories take a `springBootVersion` and select `com.fasterxml.jackson.*` (Spring Boot 3, Jackson 2)
+ * or `tools.jackson.*` (Spring Boot 4, Jackson 3). `dateTimeFeature` is Jackson 3 only and is always
+ * `tools.jackson.databind.cfg`.
+ */
 import type { SourceBuilder } from '@goast/core';
 import type { SpringBootVersion } from '../../config.ts';
 import { type KtReference, type KtReferenceFactory } from '../nodes/reference.ts';
+/** Reference to the `JsonTypeInfo` annotation from the `com.fasterxml.jackson.annotation` package. */
 export declare const jsonTypeInfo: KtReferenceFactory;
+/** Reference to the `JsonSubTypes` annotation from the `com.fasterxml.jackson.annotation` package. */
 export declare const jsonSubTypes: KtReferenceFactory;
+/** Reference to the `JsonClassDescription` annotation from the `com.fasterxml.jackson.annotation` package. */
 export declare const jsonClassDescription: KtReferenceFactory;
+/** Reference to the `JsonProperty` annotation from the `com.fasterxml.jackson.annotation` package. */
 export declare const jsonProperty: KtReferenceFactory;
+/** Reference to the `JsonPropertyDescription` annotation from the `com.fasterxml.jackson.annotation` package. */
 export declare const jsonPropertyDescription: KtReferenceFactory;
+/** Reference to the `JsonInclude` annotation from the `com.fasterxml.jackson.annotation` package. */
 export declare const jsonInclude: KtReferenceFactory;
+/** Reference to the `JsonIgnore` annotation from the `com.fasterxml.jackson.annotation` package. */
 export declare const jsonIgnore: KtReferenceFactory;
+/** Reference to the `JsonAnySetter` annotation from the `com.fasterxml.jackson.annotation` package. */
 export declare const jsonAnySetter: KtReferenceFactory;
+/** Reference to the `JsonAnyGetter` annotation from the `com.fasterxml.jackson.annotation` package. */
 export declare const jsonAnyGetter: KtReferenceFactory;
+/**
+ * Factory for a reference to the `ObjectMapper` class from the `com.fasterxml.jackson.databind` package
+ * (Spring Boot 3) or the `tools.jackson.databind` package (Spring Boot 4).
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @param springBootVersion The targeted Spring Boot major version. Selects the Jackson package.
+ * @default 3
+ * @returns A reference to `ObjectMapper`.
+ * @see SpringBootVersion
+ */
 export declare const objectMapper: <TBuilder extends SourceBuilder>(springBootVersion?: SpringBootVersion) => KtReference<TBuilder>;
+/**
+ * Factory for a reference to the `SerializationFeature` type from the `com.fasterxml.jackson.databind` package
+ * (Spring Boot 3) or the `tools.jackson.databind` package (Spring Boot 4).
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @param springBootVersion The targeted Spring Boot major version. Selects the Jackson package.
+ * @default 3
+ * @returns A reference to `SerializationFeature`.
+ * @see SpringBootVersion
+ */
 export declare const serializationFeature: <TBuilder extends SourceBuilder>(springBootVersion?: SpringBootVersion) => KtReference<TBuilder>;
+/**
+ * Factory for a reference to the `DeserializationFeature` type from the `com.fasterxml.jackson.databind` package
+ * (Spring Boot 3) or the `tools.jackson.databind` package (Spring Boot 4).
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @param springBootVersion The targeted Spring Boot major version. Selects the Jackson package.
+ * @default 3
+ * @returns A reference to `DeserializationFeature`.
+ * @see SpringBootVersion
+ */
 export declare const deserializationFeature: <TBuilder extends SourceBuilder>(springBootVersion?: SpringBootVersion) => KtReference<TBuilder>;
 /**
  * `tools.jackson.databind.cfg.DateTimeFeature` — Jackson 3 only.
@@ -21,5 +68,25 @@ export declare const deserializationFeature: <TBuilder extends SourceBuilder>(sp
  * line the constant still lives on `SerializationFeature`.
  */
 export declare const dateTimeFeature: KtReferenceFactory;
+/**
+ * Factory for a reference to the `jacksonObjectMapper` function from the Jackson Kotlin module package,
+ * `com.fasterxml.jackson.module.kotlin` (Spring Boot 3) or `tools.jackson.module.kotlin` (Spring Boot 4).
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @param springBootVersion The targeted Spring Boot major version. Selects the Jackson package.
+ * @default 3
+ * @returns A reference to `jacksonObjectMapper`.
+ * @see SpringBootVersion
+ */
 export declare const jacksonObjectMapper: <TBuilder extends SourceBuilder>(springBootVersion?: SpringBootVersion) => KtReference<TBuilder>;
+/**
+ * Factory for a reference to the `jacksonMapperBuilder` function from the Jackson Kotlin module package,
+ * `com.fasterxml.jackson.module.kotlin` (Spring Boot 3) or `tools.jackson.module.kotlin` (Spring Boot 4).
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @param springBootVersion The targeted Spring Boot major version. Selects the Jackson package.
+ * @default 3
+ * @returns A reference to `jacksonMapperBuilder`.
+ * @see SpringBootVersion
+ */
 export declare const jacksonMapperBuilder: <TBuilder extends SourceBuilder>(springBootVersion?: SpringBootVersion) => KtReference<TBuilder>;

package/dist/src/ast/references/jackson.js

@@ -7,18 +7,57 @@ import { ktReference } from '../nodes/reference.js';
  */
 const jacksonPackage = (subPackage, springBootVersion) => `${springBootVersion === 4 ? 'tools.jackson' : 'com.fasterxml.jackson'}.${subPackage}`;
 // com.fasterxml.jackson.annotation
+/** Reference to the `JsonTypeInfo` annotation from the `com.fasterxml.jackson.annotation` package. */
 export const jsonTypeInfo = ktReference.factory('JsonTypeInfo', 'com.fasterxml.jackson.annotation');
+/** Reference to the `JsonSubTypes` annotation from the `com.fasterxml.jackson.annotation` package. */
 export const jsonSubTypes = ktReference.factory('JsonSubTypes', 'com.fasterxml.jackson.annotation');
+/** Reference to the `JsonClassDescription` annotation from the `com.fasterxml.jackson.annotation` package. */
 export const jsonClassDescription = ktReference.factory('JsonClassDescription', 'com.fasterxml.jackson.annotation');
+/** Reference to the `JsonProperty` annotation from the `com.fasterxml.jackson.annotation` package. */
 export const jsonProperty = ktReference.factory('JsonProperty', 'com.fasterxml.jackson.annotation');
+/** Reference to the `JsonPropertyDescription` annotation from the `com.fasterxml.jackson.annotation` package. */
 export const jsonPropertyDescription = ktReference.factory('JsonPropertyDescription', 'com.fasterxml.jackson.annotation');
+/** Reference to the `JsonInclude` annotation from the `com.fasterxml.jackson.annotation` package. */
 export const jsonInclude = ktReference.factory('JsonInclude', 'com.fasterxml.jackson.annotation');
+/** Reference to the `JsonIgnore` annotation from the `com.fasterxml.jackson.annotation` package. */
 export const jsonIgnore = ktReference.factory('JsonIgnore', 'com.fasterxml.jackson.annotation');
+/** Reference to the `JsonAnySetter` annotation from the `com.fasterxml.jackson.annotation` package. */
 export const jsonAnySetter = ktReference.factory('JsonAnySetter', 'com.fasterxml.jackson.annotation');
+/** Reference to the `JsonAnyGetter` annotation from the `com.fasterxml.jackson.annotation` package. */
 export const jsonAnyGetter = ktReference.factory('JsonAnyGetter', 'com.fasterxml.jackson.annotation');
 // com.fasterxml.jackson.databind (Jackson 2) / tools.jackson.databind (Jackson 3, Spring Boot 4)
+/**
+ * Factory for a reference to the `ObjectMapper` class from the `com.fasterxml.jackson.databind` package
+ * (Spring Boot 3) or the `tools.jackson.databind` package (Spring Boot 4).
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @param springBootVersion The targeted Spring Boot major version. Selects the Jackson package.
+ * @default 3
+ * @returns A reference to `ObjectMapper`.
+ * @see SpringBootVersion
+ */
 export const objectMapper = (springBootVersion = 3) => ktReference('ObjectMapper', jacksonPackage('databind', springBootVersion));
+/**
+ * Factory for a reference to the `SerializationFeature` type from the `com.fasterxml.jackson.databind` package
+ * (Spring Boot 3) or the `tools.jackson.databind` package (Spring Boot 4).
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @param springBootVersion The targeted Spring Boot major version. Selects the Jackson package.
+ * @default 3
+ * @returns A reference to `SerializationFeature`.
+ * @see SpringBootVersion
+ */
 export const serializationFeature = (springBootVersion = 3) => ktReference('SerializationFeature', jacksonPackage('databind', springBootVersion));
+/**
+ * Factory for a reference to the `DeserializationFeature` type from the `com.fasterxml.jackson.databind` package
+ * (Spring Boot 3) or the `tools.jackson.databind` package (Spring Boot 4).
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @param springBootVersion The targeted Spring Boot major version. Selects the Jackson package.
+ * @default 3
+ * @returns A reference to `DeserializationFeature`.
+ * @see SpringBootVersion
+ */
 export const deserializationFeature = (springBootVersion = 3) => ktReference('DeserializationFeature', jacksonPackage('databind', springBootVersion));
 /**
  * `tools.jackson.databind.cfg.DateTimeFeature` — Jackson 3 only.
@@ -29,5 +68,25 @@ export const deserializationFeature = (springBootVersion = 3) => ktReference('De
  */
 export const dateTimeFeature = ktReference.factory('DateTimeFeature', 'tools.jackson.databind.cfg');
 // com.fasterxml.jackson.module.kotlin (Jackson 2) / tools.jackson.module.kotlin (Jackson 3, Spring Boot 4)
+/**
+ * Factory for a reference to the `jacksonObjectMapper` function from the Jackson Kotlin module package,
+ * `com.fasterxml.jackson.module.kotlin` (Spring Boot 3) or `tools.jackson.module.kotlin` (Spring Boot 4).
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @param springBootVersion The targeted Spring Boot major version. Selects the Jackson package.
+ * @default 3
+ * @returns A reference to `jacksonObjectMapper`.
+ * @see SpringBootVersion
+ */
 export const jacksonObjectMapper = (springBootVersion = 3) => ktReference('jacksonObjectMapper', jacksonPackage('module.kotlin', springBootVersion));
+/**
+ * Factory for a reference to the `jacksonMapperBuilder` function from the Jackson Kotlin module package,
+ * `com.fasterxml.jackson.module.kotlin` (Spring Boot 3) or `tools.jackson.module.kotlin` (Spring Boot 4).
+ *
+ * @template TBuilder The type of the source builder the reference is written to.
+ * @param springBootVersion The targeted Spring Boot major version. Selects the Jackson package.
+ * @default 3
+ * @returns A reference to `jacksonMapperBuilder`.
+ * @see SpringBootVersion
+ */
 export const jacksonMapperBuilder = (springBootVersion = 3) => ktReference('jacksonMapperBuilder', jacksonPackage('module.kotlin', springBootVersion));

package/dist/src/ast/references/jakarta.d.ts

@@ -1,8 +1,21 @@
+/**
+ * Pre-built references to Jakarta annotation and Bean Validation (`jakarta.validation`) types.
+ *
+ * Each `export const` is a factory that creates a `KtReference` with the given name and package, so the
+ * generated code imports the type automatically. See `KtReferenceFactory` for the optional `options`.
+ */
 import { type KtReferenceFactory } from '../nodes/reference.ts';
+/** Reference to `Generated` from the `jakarta.annotation` package. */
 export declare const generated: KtReferenceFactory;
+/** Reference to `Valid` from the `jakarta.validation` package. */
 export declare const valid: KtReferenceFactory;
+/** Reference to `Pattern` from the `jakarta.validation.constraints` package. */
 export declare const pattern: KtReferenceFactory;
+/** Reference to `Min` from the `jakarta.validation.constraints` package. */
 export declare const min: KtReferenceFactory;
+/** Reference to `Max` from the `jakarta.validation.constraints` package. */
 export declare const max: KtReferenceFactory;
+/** Reference to `NotEmpty` from the `jakarta.validation.constraints` package. */
 export declare const notEmpty: KtReferenceFactory;
+/** Reference to `Size` from the `jakarta.validation.constraints` package. */
 export declare const size: KtReferenceFactory;

package/dist/src/ast/references/jakarta.js

@@ -1,11 +1,24 @@
+/**
+ * Pre-built references to Jakarta annotation and Bean Validation (`jakarta.validation`) types.
+ *
+ * Each `export const` is a factory that creates a `KtReference` with the given name and package, so the
+ * generated code imports the type automatically. See `KtReferenceFactory` for the optional `options`.
+ */
 import { ktReference } from '../nodes/reference.js';
 // jakarta.annotation
+/** Reference to `Generated` from the `jakarta.annotation` package. */
 export const generated = ktReference.factory('Generated', 'jakarta.annotation');
 // jakarta.validation
+/** Reference to `Valid` from the `jakarta.validation` package. */
 export const valid = ktReference.factory('Valid', 'jakarta.validation');
 // jakarta.validation.constraints
+/** Reference to `Pattern` from the `jakarta.validation.constraints` package. */
 export const pattern = ktReference.factory('Pattern', 'jakarta.validation.constraints');
+/** Reference to `Min` from the `jakarta.validation.constraints` package. */
 export const min = ktReference.factory('Min', 'jakarta.validation.constraints');
+/** Reference to `Max` from the `jakarta.validation.constraints` package. */
 export const max = ktReference.factory('Max', 'jakarta.validation.constraints');
+/** Reference to `NotEmpty` from the `jakarta.validation.constraints` package. */
 export const notEmpty = ktReference.factory('NotEmpty', 'jakarta.validation.constraints');
+/** Reference to `Size` from the `jakarta.validation.constraints` package. */
 export const size = ktReference.factory('Size', 'jakarta.validation.constraints');

package/dist/src/ast/references/java.d.ts

@@ -1,14 +1,33 @@
+/**
+ * Pre-built references to Java standard library types.
+ *
+ * The `java.lang` package is in the default `globalImports`, so no `import` is emitted for its references unless
+ * `globalImports` is changed. References from the other packages in this file always emit an `import`.
+ */
 import { type KtGenericReferenceFactory, type KtReferenceFactory } from '../nodes/reference.ts';
+/** Reference to `File` from the `java.io` package. */
 export declare const file: KtReferenceFactory;
+/** Reference to `IOException` from the `java.io` package. */
 export declare const ioException: KtReferenceFactory;
+/** Reference to `IllegalStateException` from the `java.lang` package. */
 export declare const illegalStateException: KtReferenceFactory;
+/** Reference to `System` from the `java.lang` package. */
 export declare const system: KtReferenceFactory;
+/** Reference to `UnsupportedOperationException` from the `java.lang` package. */
 export declare const unsupportedOperationException: KtReferenceFactory;
+/** Reference to `Void` from the `java.lang` package. Named `void_` because `void` is reserved in TypeScript. */
 export declare const void_: KtReferenceFactory;
+/** Reference to `URI` from the `java.net` package. */
 export declare const uri: KtReferenceFactory;
+/** Reference to `OffsetDateTime` from the `java.time` package. */
 export declare const offsetDateTime: KtReferenceFactory;
+/** Reference to `OffsetTime` from the `java.time` package. */
 export declare const offsetTime: KtReferenceFactory;
+/** Reference to `LocalDateTime` from the `java.time` package. */
 export declare const localDateTime: KtReferenceFactory;
+/** Reference to `LocalDate` from the `java.time` package. */
 export declare const localDate: KtReferenceFactory;
+/** Reference to `LocalTime` from the `java.time` package. */
 export declare const localTime: KtReferenceFactory;
+/** Reference to `Optional` from the `java.util` package. Takes one type argument. */
 export declare const optional: KtGenericReferenceFactory<1>;

package/dist/src/ast/references/java.js

@@ -1,19 +1,38 @@
+/**
+ * Pre-built references to Java standard library types.
+ *
+ * The `java.lang` package is in the default `globalImports`, so no `import` is emitted for its references unless
+ * `globalImports` is changed. References from the other packages in this file always emit an `import`.
+ */
 import { ktReference } from '../nodes/reference.js';
 // java.io
+/** Reference to `File` from the `java.io` package. */
 export const file = ktReference.factory('File', 'java.io');
+/** Reference to `IOException` from the `java.io` package. */
 export const ioException = ktReference.factory('IOException', 'java.io');
 // java.lang
+/** Reference to `IllegalStateException` from the `java.lang` package. */
 export const illegalStateException = ktReference.factory('IllegalStateException', 'java.lang');
+/** Reference to `System` from the `java.lang` package. */
 export const system = ktReference.factory('System', 'java.lang');
+/** Reference to `UnsupportedOperationException` from the `java.lang` package. */
 export const unsupportedOperationException = ktReference.factory('UnsupportedOperationException', 'java.lang');
+/** Reference to `Void` from the `java.lang` package. Named `void_` because `void` is reserved in TypeScript. */
 export const void_ = ktReference.factory('Void', 'java.lang');
 // java.net
+/** Reference to `URI` from the `java.net` package. */
 export const uri = ktReference.factory('URI', 'java.net');
 // java.time
+/** Reference to `OffsetDateTime` from the `java.time` package. */
 export const offsetDateTime = ktReference.factory('OffsetDateTime', 'java.time');
+/** Reference to `OffsetTime` from the `java.time` package. */
 export const offsetTime = ktReference.factory('OffsetTime', 'java.time');
+/** Reference to `LocalDateTime` from the `java.time` package. */
 export const localDateTime = ktReference.factory('LocalDateTime', 'java.time');
+/** Reference to `LocalDate` from the `java.time` package. */
 export const localDate = ktReference.factory('LocalDate', 'java.time');
+/** Reference to `LocalTime` from the `java.time` package. */
 export const localTime = ktReference.factory('LocalTime', 'java.time');
 // java.util
+/** Reference to `Optional` from the `java.util` package. Takes one type argument. */
 export const optional = ktReference.genericFactory('Optional', 'java.util');

package/dist/src/ast/references/kotlin.d.ts

@@ -1,23 +1,51 @@
+/**
+ * Pre-built references to Kotlin standard library types, functions and annotations.
+ *
+ * The `kotlin`, `kotlin.collections` and `kotlin.jvm` packages are in the default `globalImports`, so no `import`
+ * is emitted for these references unless `globalImports` is changed.
+ */
 import { type KtGenericReferenceFactory, type KtReferenceFactory } from '../nodes/reference.ts';
+/** Reference to `Any` from the `kotlin` package. */
 export declare const any: KtReferenceFactory;
+/** Reference to `Nothing` from the `kotlin` package. */
 export declare const nothing: KtReferenceFactory;
+/** Reference to `Unit` from the `kotlin` package. */
 export declare const unit: KtReferenceFactory;
+/** Reference to `String` from the `kotlin` package. */
 export declare const string: KtReferenceFactory;
+/** Reference to `Int` from the `kotlin` package. */
 export declare const int: KtReferenceFactory;
+/** Reference to `Long` from the `kotlin` package. */
 export declare const long: KtReferenceFactory;
+/** Reference to `Float` from the `kotlin` package. */
 export declare const float: KtReferenceFactory;
+/** Reference to `Double` from the `kotlin` package. */
 export declare const double: KtReferenceFactory;
+/** Reference to `Boolean` from the `kotlin` package. */
 export declare const boolean: KtReferenceFactory;
+/** Reference to the `lazy` function from the `kotlin` package. Takes one type argument. */
 export declare const lazyFun: KtGenericReferenceFactory<1>;
+/** Reference to the `Throws` annotation from the `kotlin` package. */
 export declare const throws: KtReferenceFactory;
+/** Reference to the `Deprecated` annotation from the `kotlin` package. */
 export declare const deprecated: KtReferenceFactory;
+/** Reference to `Throwable` from the `kotlin` package. */
 export declare const throwable: KtReferenceFactory;
+/** Reference to the `List` type from the `kotlin.collections` package. Takes one type argument. */
 export declare const list: KtGenericReferenceFactory<1>;
+/** Reference to the `MutableList` type from the `kotlin.collections` package. Takes one type argument. */
 export declare const mutableList: KtGenericReferenceFactory<1>;
+/** Reference to the `Map` type from the `kotlin.collections` package. Takes two type arguments. */
 export declare const map: KtGenericReferenceFactory<2>;
+/** Reference to the `MutableMap` type from the `kotlin.collections` package. Takes two type arguments. */
 export declare const mutableMap: KtGenericReferenceFactory<2>;
+/** Reference to the `listOf` function from the `kotlin.collections` package. Takes one type argument. */
 export declare const listOf: KtGenericReferenceFactory<1>;
+/** Reference to the `mutableListOf` function from the `kotlin.collections` package. Takes one type argument. */
 export declare const mutableListOf: KtGenericReferenceFactory<1>;
+/** Reference to the `mapOf` function from the `kotlin.collections` package. Takes two type arguments. */
 export declare const mapOf: KtGenericReferenceFactory<2>;
+/** Reference to the `mutableMapOf` function from the `kotlin.collections` package. Takes two type arguments. */
 export declare const mutableMapOf: KtGenericReferenceFactory<2>;
+/** Reference to the `JvmStatic` annotation from the `kotlin.jvm` package. */
 export declare const jvmStatic: KtReferenceFactory;