@goast/kotlin 0.7.0-beta.2 → 0.7.1

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

@@ -3,18 +3,71 @@ import { KtNode } from '../node.js';
 import { writeKtNode } from '../utils/write-kt-node.js';
 import { writeKtParameters } from '../utils/write-kt-parameters.js';
 import { ktAnnotation } from './annotation.js';
+/**
+ * Represents a Kotlin parameter of a function or a class constructor. A class constructor parameter can also declare
+ * a property.
+ *
+ * Written in this order: the annotations, each on a line of its own, the modifiers, `val` or `var` for a property, the
+ * name, the type after a colon, then the default value after an equals sign.
+ *
+ * @template TBuilder The type of the source builder the parameter is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktParameter
+ */
 export class KtParameter extends KtNode {
+    /**
+     * The name of the parameter, written before the colon.
+     */
     name;
+    /**
+     * The type of the parameter, written after the colon, such as `Int` in `x: Int`.
+     */
     type;
+    /**
+     * The annotations written above the parameter, each on a line of its own. A parameter list with annotations is
+     * written with one parameter per line.
+     */
     annotations;
+    /**
+     * The default value written after ` = `, such as `42` in `x: Int = 42`. `null` writes no default value.
+     */
     default;
+    /**
+     * Whether the parameter is written with the `vararg` modifier, such as `vararg x: Int`. The modifier is written for a
+     * plain parameter as well as for a class property.
+     * @default false
+     */
     vararg;
+    /**
+     * The description of the parameter. It is not written inline. It becomes a `@param` tag in the KDoc comment of the
+     * function or class whose parameter list contains the parameter.
+     */
     description;
     // class parameter options
+    /**
+     * The visibility written before `val` or `var`, such as `private var x: Int`. Only written when `property` is set.
+     */
     accessModifier;
+    /**
+     * Whether the parameter declares a property: `readonly` writes `val` and `mutable` writes `var`. `null` writes a
+     * plain parameter without either keyword.
+     */
     property;
+    /**
+     * The description of the property. It is not written inline. It becomes a `@property` tag in the KDoc comment of the
+     * class that declares the parameter, when `property` is set.
+     */
     propertyDescription;
+    /**
+     * Whether the property is written with the `override` modifier, such as `override var x: Int`. Only written when
+     * `property` is set.
+     * @default false
+     */
     override;
+    /**
+     * Initializes a new instance of the KtParameter class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.name = options.name;
@@ -57,6 +110,21 @@ export class KtParameter extends KtNode {
 }
 const createParameter = (name, type, options) => new KtParameter({ ...options, name, type });
 const createClassParameter = (name, type, options) => new KtParameter({ ...options, name, type });
+/**
+ * Factory for creating parameter nodes. The `class` function creates a class constructor parameter, which can declare a
+ * property, and accepts the options for it. The `write` function writes a parenthesized parameter list.
+ *
+ * @param name The name of the parameter.
+ * @param type The type of the parameter.
+ * @param options The settings of the parameter. See `KtParameter` for the available properties.
+ * @example
+ * ```ts
+ * ktParameter('x', 'Int', { default: '42', annotations: [ktAnnotation('Inject')] });
+ * // Emits:
+ * // @Inject
+ * // x: Int = 42
+ * ```
+ */
 export const ktParameter = Object.assign(createParameter, {
     class: createClassParameter,
     write: writeKtParameters,

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

@@ -13,19 +13,75 @@ type AccessorOptions<TBuilder extends SourceBuilder, TInjects extends string = n
     body?: Nullable<AppendValue<TBuilder>>;
     singleExpression?: Nullable<boolean>;
 }>;
+/**
+ * Base class for the getter and setter of a Kotlin property, such as `get() = 42` or `private set`.
+ *
+ * Written in this order: the annotations, each on a line of its own, the access modifier, then the `get` or `set`
+ * keyword. A body follows the keyword: `()` for a getter or `(value)` for a setter, then either ` = ` and the
+ * expression, or a braced block on indented lines. Without a body, only the modifier and the keyword are written.
+ *
+ * @template TBuilder The type of the source builder the accessor is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktProperty.getter
+ * @see ktProperty.setter
+ */
 export declare abstract class KtPropertyAccessor<TBuilder extends SourceBuilder, TInjects extends string = never> extends KtNode<TBuilder, TInjects | AccessorInjects> {
+    /**
+     * The keyword written for the accessor, `get` or `set`. It also decides the parameter list of the body: `()` for a
+     * getter and `(value)` for a setter.
+     */
     abstract get kind(): 'get' | 'set';
+    /**
+     * The visibility written before the keyword, such as `private` in `private set`. `null` writes no visibility keyword,
+     * so the accessor has the visibility of the property.
+     */
     accessModifier: KtAccessModifier | null;
+    /**
+     * The annotations written above the accessor, each on a line of its own.
+     */
     annotations: KtAnnotation<TBuilder>[];
+    /**
+     * The code of the accessor, written after the parameter list. `null` writes no body. With `singleExpression` the code
+     * follows ` = `, otherwise it is written in braces on indented lines.
+     */
     body: AppendValue<TBuilder> | null;
+    /**
+     * Whether the body is a single expression written after ` = ` on the same line, such as `get() = 42`. Otherwise the
+     * body is written in braces. Has no effect without a body.
+     * @default false
+     */
     singleExpression: boolean;
+    /**
+     * Initializes a new instance of the KtPropertyAccessor class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: AccessorOptions<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
+/**
+ * Represents the getter of a Kotlin property, written with the `get` keyword. See `KtPropertyAccessor` for the order in
+ * which it is written.
+ *
+ * @template TBuilder The type of the source builder the getter is written to.
+ * @see ktProperty.getter
+ */
 export declare class KtPropertyGetter<TBuilder extends SourceBuilder> extends KtPropertyAccessor<TBuilder> {
+    /**
+     * The keyword of the accessor, always `get`. A body is written with an empty parameter list, such as `get() = 42`.
+     */
     readonly kind: 'get';
 }
+/**
+ * Represents the setter of a Kotlin property, written with the `set` keyword. See `KtPropertyAccessor` for the order in
+ * which it is written.
+ *
+ * @template TBuilder The type of the source builder the setter is written to.
+ * @see ktProperty.setter
+ */
 export declare class KtPropertySetter<TBuilder extends SourceBuilder> extends KtPropertyAccessor<TBuilder> {
+    /**
+     * The keyword of the accessor, always `set`. A body uses the parameter list `(value)`, as in `set(value) = 42`.
+     */
     readonly kind: 'set';
 }
 type Injects = 'doc' | 'annotations' | 'modifiers' | 'name' | 'type' | 'default' | 'delegate';
@@ -47,29 +103,125 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     override?: Nullable<boolean>;
     abstract?: Nullable<boolean>;
 }>;
+/**
+ * Represents a Kotlin property declaration, such as `val x: Int = 42` or `var x: Int` with a private setter.
+ *
+ * Written in this order: the KDoc comment, the annotations, the modifiers, `val` or `var`, the name, the type, the
+ * default value or the delegate, then the getter and the setter, indented on lines below. The modifiers are written in
+ * the order access modifier, `const`, `lateinit`, `abstract`, `override`, `open`. A property with a setter is always
+ * written with `var`. Without a type, `: Any?` is written unless a default value or a getter body is present, in which
+ * case no type is written.
+ *
+ * @template TBuilder The type of the source builder the property is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktProperty
+ */
 export declare class KtProperty<TBuilder extends SourceBuilder, TInjects extends string = never> extends KtNode<TBuilder, TInjects | Injects> {
+    /**
+     * The KDoc comment written above the property, or `null` to omit it. Nothing is written when the comment has neither
+     * a description nor tags.
+     */
     doc: KtDoc<TBuilder> | null;
+    /**
+     * The name of the property, written after `val` or `var`.
+     */
     name: string;
+    /**
+     * The type written after the colon, such as `Int` in `val x: Int`. When it is `null`, `: Any?` is written if there is
+     * neither a default value nor a getter body, and no type is written otherwise.
+     */
     type: KtType<TBuilder> | null;
+    /**
+     * The annotations written above the property, each on a line of its own. The target of an annotation is written as a
+     * use-site target, such as `@field:Json` or `@get:Inject`.
+     */
     annotations: KtAnnotation<TBuilder>[];
+    /**
+     * The visibility written before the other modifiers, such as `private` in `private val x`. `null` writes no
+     * visibility keyword.
+     */
     accessModifier: KtAccessModifier | null;
+    /**
+     * The getter written on an indented line below the property, such as `get() = 42`. `null` writes no getter.
+     */
     getter: KtPropertyGetter<TBuilder> | null;
+    /**
+     * The setter written on an indented line below the property, such as `private set`. Its presence makes the property
+     * `var`. `null` writes no setter.
+     */
     setter: KtPropertySetter<TBuilder> | null;
+    /**
+     * The initial value written after ` = `, such as `42` in `val x = 42`. `null` writes no initial value.
+     */
     default: KtValue<TBuilder> | null;
+    /**
+     * The delegate written after ` by `, such as `lazy` in `val x: Int by lazy`. `null` writes no delegation.
+     */
     delegate: KtType<TBuilder> | null;
+    /**
+     * The arguments written in parentheses after the delegate, such as `(42, true)` in `by lazy(42, true)`. Only written
+     * when `delegate` is set. An empty list writes `()`.
+     */
     delegateArguments: (KtArgument<TBuilder> | KtValue<TBuilder>)[] | null;
+    /**
+     * Whether the property is written with `var` instead of `val`. A property with a setter is always `var`.
+     * @default false
+     */
     mutable: boolean;
+    /**
+     * Whether the property is written with the `const` modifier, such as `const val x`.
+     * @default false
+     */
     const: boolean;
+    /**
+     * Whether the property is written with the `lateinit` modifier, such as `lateinit var x`.
+     * @default false
+     */
     lateinit: boolean;
+    /**
+     * Whether the property is written with the `open` modifier, such as `open val x`.
+     * @default false
+     */
     open: boolean;
+    /**
+     * Whether the property is written with the `override` modifier, such as `override val x`.
+     * @default false
+     */
     override: boolean;
+    /**
+     * Whether the property is written with the `abstract` modifier, such as `abstract val x: Int`.
+     * @default false
+     */
     abstract: boolean;
+    /**
+     * Initializes a new instance of the KtProperty class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
 declare const createPropertyGetter: <TBuilder extends SourceBuilder>(options?: AccessorOptions<TBuilder>) => KtPropertyGetter<TBuilder>;
 declare const createPropertySetter: <TBuilder extends SourceBuilder>(options?: AccessorOptions<TBuilder>) => KtPropertySetter<TBuilder>;
 declare const createProperty: <TBuilder extends SourceBuilder>(name: Options<TBuilder>['name'], options?: Prettify<Omit<Options<TBuilder>, 'name'>>) => KtProperty<TBuilder>;
+/**
+ * Factory for creating property nodes. The `getter` and `setter` functions create the accessors of a property and
+ * accept the options of `KtPropertyAccessor`. The `write` function writes one or more property nodes to a builder.
+ *
+ * @param name The name of the property.
+ * @param options The settings of the property. See `KtProperty` for the available properties.
+ * @example
+ * ```ts
+ * ktProperty('count', {
+ *   type: 'Int',
+ *   mutable: true,
+ *   default: '0',
+ *   setter: ktProperty.setter({ accessModifier: 'private' }),
+ * });
+ * // Emits:
+ * // var count: Int = 0
+ * //     private set
+ * ```
+ */
 export declare const ktProperty: typeof createProperty & {
     getter: typeof createPropertyGetter;
     setter: typeof createPropertySetter;

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

@@ -3,11 +3,43 @@ import { KtNode } from '../node.js';
 import { writeKtNode, writeKtNodes } from '../utils/write-kt-node.js';
 import { ktAnnotation } from './annotation.js';
 import { ktArgument } from './argument.js';
+/**
+ * Base class for the getter and setter of a Kotlin property, such as `get() = 42` or `private set`.
+ *
+ * Written in this order: the annotations, each on a line of its own, the access modifier, then the `get` or `set`
+ * keyword. A body follows the keyword: `()` for a getter or `(value)` for a setter, then either ` = ` and the
+ * expression, or a braced block on indented lines. Without a body, only the modifier and the keyword are written.
+ *
+ * @template TBuilder The type of the source builder the accessor is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktProperty.getter
+ * @see ktProperty.setter
+ */
 export class KtPropertyAccessor extends KtNode {
+    /**
+     * The visibility written before the keyword, such as `private` in `private set`. `null` writes no visibility keyword,
+     * so the accessor has the visibility of the property.
+     */
     accessModifier;
+    /**
+     * The annotations written above the accessor, each on a line of its own.
+     */
     annotations;
+    /**
+     * The code of the accessor, written after the parameter list. `null` writes no body. With `singleExpression` the code
+     * follows ` = `, otherwise it is written in braces on indented lines.
+     */
     body;
+    /**
+     * Whether the body is a single expression written after ` = ` on the same line, such as `get() = 42`. Otherwise the
+     * body is written in braces. Has no effect without a body.
+     * @default false
+     */
     singleExpression;
+    /**
+     * Initializes a new instance of the KtPropertyAccessor class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.accessModifier = options.accessModifier ?? null;
@@ -41,29 +73,126 @@ export class KtPropertyAccessor extends KtNode {
         builder.appendLine();
     }
 }
+/**
+ * Represents the getter of a Kotlin property, written with the `get` keyword. See `KtPropertyAccessor` for the order in
+ * which it is written.
+ *
+ * @template TBuilder The type of the source builder the getter is written to.
+ * @see ktProperty.getter
+ */
 export class KtPropertyGetter extends KtPropertyAccessor {
+    /**
+     * The keyword of the accessor, always `get`. A body is written with an empty parameter list, such as `get() = 42`.
+     */
     kind = 'get';
 }
+/**
+ * Represents the setter of a Kotlin property, written with the `set` keyword. See `KtPropertyAccessor` for the order in
+ * which it is written.
+ *
+ * @template TBuilder The type of the source builder the setter is written to.
+ * @see ktProperty.setter
+ */
 export class KtPropertySetter extends KtPropertyAccessor {
+    /**
+     * The keyword of the accessor, always `set`. A body uses the parameter list `(value)`, as in `set(value) = 42`.
+     */
     kind = 'set';
 }
+/**
+ * Represents a Kotlin property declaration, such as `val x: Int = 42` or `var x: Int` with a private setter.
+ *
+ * Written in this order: the KDoc comment, the annotations, the modifiers, `val` or `var`, the name, the type, the
+ * default value or the delegate, then the getter and the setter, indented on lines below. The modifiers are written in
+ * the order access modifier, `const`, `lateinit`, `abstract`, `override`, `open`. A property with a setter is always
+ * written with `var`. Without a type, `: Any?` is written unless a default value or a getter body is present, in which
+ * case no type is written.
+ *
+ * @template TBuilder The type of the source builder the property is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktProperty
+ */
 export class KtProperty extends KtNode {
+    /**
+     * The KDoc comment written above the property, or `null` to omit it. Nothing is written when the comment has neither
+     * a description nor tags.
+     */
     doc;
+    /**
+     * The name of the property, written after `val` or `var`.
+     */
     name;
+    /**
+     * The type written after the colon, such as `Int` in `val x: Int`. When it is `null`, `: Any?` is written if there is
+     * neither a default value nor a getter body, and no type is written otherwise.
+     */
     type;
+    /**
+     * The annotations written above the property, each on a line of its own. The target of an annotation is written as a
+     * use-site target, such as `@field:Json` or `@get:Inject`.
+     */
     annotations;
+    /**
+     * The visibility written before the other modifiers, such as `private` in `private val x`. `null` writes no
+     * visibility keyword.
+     */
     accessModifier;
+    /**
+     * The getter written on an indented line below the property, such as `get() = 42`. `null` writes no getter.
+     */
     getter;
+    /**
+     * The setter written on an indented line below the property, such as `private set`. Its presence makes the property
+     * `var`. `null` writes no setter.
+     */
     setter;
+    /**
+     * The initial value written after ` = `, such as `42` in `val x = 42`. `null` writes no initial value.
+     */
     default;
+    /**
+     * The delegate written after ` by `, such as `lazy` in `val x: Int by lazy`. `null` writes no delegation.
+     */
     delegate;
+    /**
+     * The arguments written in parentheses after the delegate, such as `(42, true)` in `by lazy(42, true)`. Only written
+     * when `delegate` is set. An empty list writes `()`.
+     */
     delegateArguments;
+    /**
+     * Whether the property is written with `var` instead of `val`. A property with a setter is always `var`.
+     * @default false
+     */
     mutable;
+    /**
+     * Whether the property is written with the `const` modifier, such as `const val x`.
+     * @default false
+     */
     const;
+    /**
+     * Whether the property is written with the `lateinit` modifier, such as `lateinit var x`.
+     * @default false
+     */
     lateinit;
+    /**
+     * Whether the property is written with the `open` modifier, such as `open val x`.
+     * @default false
+     */
     open;
+    /**
+     * Whether the property is written with the `override` modifier, such as `override val x`.
+     * @default false
+     */
     override;
+    /**
+     * Whether the property is written with the `abstract` modifier, such as `abstract val x: Int`.
+     * @default false
+     */
     abstract;
+    /**
+     * Initializes a new instance of the KtProperty class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.doc = options.doc ?? null;
@@ -137,6 +266,25 @@ export class KtProperty extends KtNode {
 const createPropertyGetter = (options) => new KtPropertyGetter(options ?? {});
 const createPropertySetter = (options) => new KtPropertySetter(options ?? {});
 const createProperty = (name, options) => new KtProperty({ ...options, name });
+/**
+ * Factory for creating property nodes. The `getter` and `setter` functions create the accessors of a property and
+ * accept the options of `KtPropertyAccessor`. The `write` function writes one or more property nodes to a builder.
+ *
+ * @param name The name of the property.
+ * @param options The settings of the property. See `KtProperty` for the available properties.
+ * @example
+ * ```ts
+ * ktProperty('count', {
+ *   type: 'Int',
+ *   mutable: true,
+ *   default: '0',
+ *   setter: ktProperty.setter({ accessModifier: 'private' }),
+ * });
+ * // Emits:
+ * // var count: Int = 0
+ * //     private set
+ * ```
+ */
 export const ktProperty = Object.assign(createProperty, {
     getter: createPropertyGetter,
     setter: createPropertySetter,

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

@@ -16,34 +16,141 @@ type _AddImportHandler<T> = {
     builderClass: abstract new (...args: any) => T;
     handler: (builder: T, reference: KtReference<any>) => void;
 };
+/**
+ * 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 declare class KtReference<TBuilder extends SourceBuilder, TInjects extends string = never> extends KtNode<TBuilder, TInjects | Injects> {
     private static readonly addImportHandlers;
+    /**
+     * The name written verbatim, such as `List`. When `packageName` is set, the same name is imported.
+     */
     name: string;
+    /**
+     * The package the name is imported from, such as `com.example.models`. `null` writes the name without an import.
+     */
     packageName: string | null;
+    /**
+     * The generic arguments written in angle brackets after the name, such as `<String>` in `List<String>`. An empty list
+     * writes nothing.
+     */
     generics: KtType<TBuilder>[];
+    /**
+     * Whether a `?` is written after the name, which makes the type nullable. Ignored when `classReference` or
+     * `subReference` is set.
+     * @default false
+     */
     nullable: boolean;
+    /**
+     * Whether the reference is written as a class literal, such as `Foo::class`. Takes precedence over `subReference` and
+     * `nullable`.
+     * @default false
+     */
     classReference: boolean;
+    /**
+     * 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: KtReference<TBuilder> | KtCall<TBuilder> | null;
+    /**
+     * Initializes a new instance of the KtReference class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
+    /**
+     * 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: TBuilder): void;
     protected onWrite(builder: TBuilder): void;
+    /**
+     * 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<TBuilder extends SourceBuilder>(builderClass: _AddImportHandler<TBuilder>['builderClass'], handler: _AddImportHandler<TBuilder>['handler']): void;
 }
 declare const createReference: <TBuilder extends SourceBuilder>(name: Options<TBuilder>['name'], packageName?: Options<TBuilder>['packageName'], options?: Prettify<Omit<Options<TBuilder>, 'name' | 'packageName'>>) => KtReference<TBuilder>;
+/**
+ * A function that creates references to one fixed name and package, as returned by `ktReference.factory`. Calling it
+ * creates the same reference as `ktReference` with that name and package, and takes the same options.
+ */
 export type KtReferenceFactory = (<TBuilder extends SourceBuilder>(options?: Prettify<Omit<Options<TBuilder>, 'name' | 'packageName'>>) => KtReference<TBuilder>) & {
+    /**
+     * The name that every reference created by this factory is written with.
+     */
     refName: string;
+    /**
+     * The package that every reference created by this factory is imported from, or `null` for none.
+     */
     packageName: Nullable<string>;
+    /**
+     * Whether the value is a reference with the name and package of this factory. Use it to check the type of a node.
+     */
     matches: (value: unknown) => value is KtReference<never>;
 };
+/**
+ * A function that creates references to one fixed name and package with generic arguments, as returned by
+ * `ktReference.genericFactory`. Its first argument is the tuple of generic arguments, which must match `TGenericCount`.
+ *
+ * @template TGenericCount The number of generic arguments, or a list of the allowed numbers.
+ */
 export type KtGenericReferenceFactory<TGenericCount extends number | number[]> = (<TBuilder extends SourceBuilder>(generics: TupleWithCount<KtType<TBuilder>, TGenericCount>, options?: Prettify<Omit<Options<TBuilder>, 'name' | 'packageName' | 'generics'>>) => KtReference<TBuilder>) & {
+    /**
+     * The name that every reference created by this factory is written with.
+     */
     refName: string;
+    /**
+     * The package that every reference created by this factory is imported from, or `null` for none.
+     */
     packageName: Nullable<string>;
+    /**
+     * Creates a reference with the name and package of this factory and without generic arguments, for when the arguments
+     * are not known or not needed.
+     */
     infer: <TBuilder extends SourceBuilder>(options?: Prettify<Omit<Options<TBuilder>, 'name' | 'packageName' | 'generics'>>) => KtReference<TBuilder>;
+    /**
+     * Whether the value is a reference with the name and package of this factory. Use it to check the type of a node.
+     */
     matches: (value: unknown) => value is KtReference<never>;
 };
 declare const createFactory: (name: string, packageName?: Nullable<string>) => KtReferenceFactory;
 declare const createGenericFactory: <TGenericCount extends number | number[]>(name: string, packageName?: Nullable<string>) => KtGenericReferenceFactory<TGenericCount>;
 declare const importRefs: <TBuilder extends SourceBuilder>(builder: TBuilder, references: KtReference<TBuilder>[]) => void;
+/**
+ * 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 declare const ktReference: typeof createReference & {
     factory: typeof createFactory;
     genericFactory: typeof createGenericFactory;