@goast/kotlin 0.7.0-beta.2 → 0.7.1

package/dist/src/assets.d.ts

@@ -1,2 +1,19 @@
+/**
+ * Gets the text content of a file from the `assets` directory that ships with this package. The directory is resolved
+ * relative to this module. Rejects if the file cannot be read.
+ * @param relativePath The path of the asset file, relative to the assets directory.
+ * @returns A promise that resolves with the text content of the asset file.
+ * @see AssetManager.getAssetFileContent
+ */
 export declare const getAssetFileContent: (relativePath: string) => Promise<string>;
+/**
+ * Copies a file from the `assets` directory that ships with this package into a directory, keeping its base name. An
+ * existing file at the target path is overwritten.
+ * @param relativePath The path of the asset file, relative to the assets directory.
+ * @param destDir The directory to copy the file into.
+ * @param logName The name to show in the log message. Nothing is logged if omitted, and the relative path is logged if
+ * empty.
+ * @returns A promise that resolves when the file has been copied.
+ * @see AssetManager.copyAssetFile
+ */
 export declare const copyAssetFile: (relativePath: string, destDir: string, logName?: string) => Promise<void>;

package/dist/src/assets.js

@@ -1,5 +1,22 @@
 import { AssetManager } from '@goast/core';
 import { URL } from 'node:url';
 const manager = new AssetManager(new URL('../assets/', import.meta.url));
+/**
+ * Gets the text content of a file from the `assets` directory that ships with this package. The directory is resolved
+ * relative to this module. Rejects if the file cannot be read.
+ * @param relativePath The path of the asset file, relative to the assets directory.
+ * @returns A promise that resolves with the text content of the asset file.
+ * @see AssetManager.getAssetFileContent
+ */
 export const getAssetFileContent = manager.getAssetFileContent.bind(manager);
+/**
+ * Copies a file from the `assets` directory that ships with this package into a directory, keeping its base name. An
+ * existing file at the target path is overwritten.
+ * @param relativePath The path of the asset file, relative to the assets directory.
+ * @param destDir The directory to copy the file into.
+ * @param logName The name to show in the log message. Nothing is logged if omitted, and the relative path is logged if
+ * empty.
+ * @returns A promise that resolves when the file has been copied.
+ * @see AssetManager.copyAssetFile
+ */
 export const copyAssetFile = manager.copyAssetFile.bind(manager);

package/dist/src/ast/common.d.ts

@@ -1 +1,5 @@
+/**
+ * The visibility modifier written before a declaration, such as `private` in `private interface Foo`.
+ * A declaration with no visibility modifier is written without a keyword, so Kotlin's default of `public` applies.
+ */
 export type KtAccessModifier = 'public' | 'protected' | 'internal' | 'private';

package/dist/src/ast/node.d.ts

@@ -1,4 +1,15 @@
 import { AstNode, type AstNodeOptions, type SourceBuilder } from '@goast/core';
+/**
+ * Base class for all Kotlin AST nodes. It adds no behavior of its own. Nodes are written with `write`, and their
+ * injection points, such as `before` and `beforeName`, come from `AstNode` in `@goast/core`.
+ *
+ * @template TBuilder The type of the builder that the node is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ */
 export declare abstract class KtNode<TBuilder extends SourceBuilder, TInjects extends string = never> extends AstNode<TBuilder, TInjects> {
+    /**
+     * Initializes a new instance of the KtNode class.
+     * @param options The options of the node. They are passed on to the constructor of `AstNode`.
+     */
     constructor(options: AstNodeOptions<typeof AstNode<TBuilder, TInjects>>);
 }

package/dist/src/ast/node.js

@@ -1,5 +1,16 @@
 import { AstNode } from '@goast/core';
+/**
+ * Base class for all Kotlin AST nodes. It adds no behavior of its own. Nodes are written with `write`, and their
+ * injection points, such as `before` and `beforeName`, come from `AstNode` in `@goast/core`.
+ *
+ * @template TBuilder The type of the builder that the node is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ */
 export class KtNode extends AstNode {
+    /**
+     * Initializes a new instance of the KtNode class.
+     * @param options The options of the node. They are passed on to the constructor of `AstNode`.
+     */
     constructor(options) {
         super(options);
     }

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

@@ -9,15 +9,59 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     arguments?: Nullable<Nullable<KtArgument<TBuilder> | KtValue<TBuilder>>[]>;
     target?: Nullable<KtAnnotationTarget>;
 }>;
+/**
+ * The use-site target of an annotation, written as a prefix before the colon, such as `field` for `@field:Inject`.
+ * Without a target, the annotation applies to the element that it is written on.
+ */
 export type KtAnnotationTarget = 'file' | 'property' | 'field' | 'get' | 'set' | 'receiver' | 'param' | 'setparam' | 'delegate';
+/**
+ * Represents a Kotlin annotation, such as `@Inject` or `@field:JsonProperty("user_id")`.
+ *
+ * Written in this order: the `@` sign, the use-site target followed by a colon, the annotation class, then the
+ * arguments in parentheses.
+ *
+ * @template TBuilder The type of the source builder the annotation is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktAnnotation
+ */
 export declare class KtAnnotation<TBuilder extends SourceBuilder, TInjects extends string = never> extends KtNode<TBuilder, TInjects | Injects> {
+    /**
+     * The annotation class, written right after the `@` sign and the optional target, such as `Inject` or
+     * `kotlin.Deprecated`.
+     */
     class: KtType<TBuilder>;
+    /**
+     * The arguments written in parentheses after the annotation class, such as `("user_id")`. Nothing is written when the
+     * list is empty, so the annotation stays a marker annotation without parentheses.
+     */
     arguments: (KtArgument<TBuilder> | KtValue<TBuilder>)[];
+    /**
+     * The use-site target written between the `@` sign and the annotation class, followed by a colon, such as `field` for
+     * `@field:Inject`. `null` omits the target.
+     */
     target: KtAnnotationTarget | null;
+    /**
+     * Initializes a new instance of the KtAnnotation class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
 declare const createAnnotation: <TBuilder extends SourceBuilder>($class: Options<TBuilder>['class'], $arguments?: Options<TBuilder>['arguments'], options?: Prettify<Omit<Options<TBuilder>, 'class' | 'arguments'>>) => KtAnnotation<TBuilder>;
+/**
+ * Factory for creating annotation nodes. The `write` function writes one or more annotations to a builder,
+ * each followed by a line break when `multiline` is set and by a space otherwise.
+ *
+ * @param $class The annotation class. See `KtAnnotation.class`.
+ * @param $arguments The arguments of the annotation. See `KtAnnotation.arguments`.
+ * @param options The settings of the annotation. See `KtAnnotation` for the available properties.
+ * @example
+ * ```ts
+ * ktAnnotation('JsonProperty', ['"user_id"'], { target: 'field' });
+ * // Emits:
+ * // @field:JsonProperty("user_id")
+ * ```
+ */
 export declare const ktAnnotation: typeof createAnnotation & {
     write: typeof writeKtAnnotations;
 };

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

@@ -3,10 +3,36 @@ import { KtNode } from '../node.js';
 import { writeKtAnnotations } from '../utils/write-kt-annotations.js';
 import { writeKtNode } from '../utils/write-kt-node.js';
 import { ktArgument } from './argument.js';
+/**
+ * Represents a Kotlin annotation, such as `@Inject` or `@field:JsonProperty("user_id")`.
+ *
+ * Written in this order: the `@` sign, the use-site target followed by a colon, the annotation class, then the
+ * arguments in parentheses.
+ *
+ * @template TBuilder The type of the source builder the annotation is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktAnnotation
+ */
 export class KtAnnotation extends KtNode {
+    /**
+     * The annotation class, written right after the `@` sign and the optional target, such as `Inject` or
+     * `kotlin.Deprecated`.
+     */
     class;
+    /**
+     * The arguments written in parentheses after the annotation class, such as `("user_id")`. Nothing is written when the
+     * list is empty, so the annotation stays a marker annotation without parentheses.
+     */
     arguments;
+    /**
+     * The use-site target written between the `@` sign and the annotation class, followed by a colon, such as `field` for
+     * `@field:Inject`. `null` omits the target.
+     */
     target;
+    /**
+     * Initializes a new instance of the KtAnnotation class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.class = options.class;
@@ -32,6 +58,20 @@ export class KtAnnotation extends KtNode {
     }
 }
 const createAnnotation = ($class, $arguments, options) => new KtAnnotation({ ...options, class: $class, arguments: $arguments });
+/**
+ * Factory for creating annotation nodes. The `write` function writes one or more annotations to a builder,
+ * each followed by a line break when `multiline` is set and by a space otherwise.
+ *
+ * @param $class The annotation class. See `KtAnnotation.class`.
+ * @param $arguments The arguments of the annotation. See `KtAnnotation.arguments`.
+ * @param options The settings of the annotation. See `KtAnnotation` for the available properties.
+ * @example
+ * ```ts
+ * ktAnnotation('JsonProperty', ['"user_id"'], { target: 'field' });
+ * // Emits:
+ * // @field:JsonProperty("user_id")
+ * ```
+ */
 export const ktAnnotation = Object.assign(createAnnotation, {
     write: writeKtAnnotations,
 });

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

@@ -7,14 +7,47 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     name?: Nullable<string>;
     value: KtValue<TBuilder>;
 }>;
+/**
+ * Represents an argument that is passed to a call or an annotation, such as `42` or `timeout = 30`.
+ *
+ * Written in this order: the name followed by ` = ` when a name is set, then the value.
+ *
+ * @template TBuilder The type of the source builder the argument is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktArgument
+ */
 export declare class KtArgument<TBuilder extends SourceBuilder, TInjects extends string = never> extends KtNode<TBuilder, TInjects | Injects> {
+    /**
+     * The name of the parameter that the value is passed to, written before ` = ` to pass the value by name. `null` or an
+     * empty name passes the value by position instead.
+     */
     name: string | null;
+    /**
+     * The value of the argument. A string is written verbatim, while other nodes write their own Kotlin code.
+     */
     value: KtValue<TBuilder>;
+    /**
+     * Initializes a new instance of the KtArgument class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
 declare const createArgument: <TBuilder extends SourceBuilder>(value: Options<TBuilder>['value'], options?: Prettify<Omit<Options<TBuilder>, 'value'>>) => KtArgument<TBuilder>;
 declare const createNamedArgument: <TBuilder extends SourceBuilder>(name: Options<TBuilder>['name'], value: Options<TBuilder>['value'], options?: Prettify<Omit<Options<TBuilder>, 'value' | 'name'>>) => KtArgument<TBuilder>;
+/**
+ * Factory for creating argument nodes. The `named` function creates an argument with a name, and the `write` function
+ * writes a list of arguments in parentheses, or `()` when the list is empty.
+ *
+ * @param value The value of the argument. A string is written verbatim.
+ * @param options The settings of the argument. See `KtArgument` for the available properties.
+ * @example
+ * ```ts
+ * ktArgument('30', { name: 'timeout' });
+ * // Emits:
+ * // timeout = 30
+ * ```
+ */
 export declare const ktArgument: typeof createArgument & {
     named: typeof createNamedArgument;
     write: typeof writeKtArguments;

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

@@ -1,9 +1,29 @@
 import { KtNode } from '../node.js';
 import { writeKtArguments } from '../utils/write-kt-arguments.js';
 import { writeKtNode } from '../utils/write-kt-node.js';
+/**
+ * Represents an argument that is passed to a call or an annotation, such as `42` or `timeout = 30`.
+ *
+ * Written in this order: the name followed by ` = ` when a name is set, then the value.
+ *
+ * @template TBuilder The type of the source builder the argument is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktArgument
+ */
 export class KtArgument extends KtNode {
+    /**
+     * The name of the parameter that the value is passed to, written before ` = ` to pass the value by name. `null` or an
+     * empty name passes the value by position instead.
+     */
     name;
+    /**
+     * The value of the argument. A string is written verbatim, while other nodes write their own Kotlin code.
+     */
     value;
+    /**
+     * Initializes a new instance of the KtArgument class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.name = options?.name ?? null;
@@ -23,6 +43,19 @@ export class KtArgument extends KtNode {
 }
 const createArgument = (value, options) => new KtArgument({ ...options, value });
 const createNamedArgument = (name, value, options) => new KtArgument({ ...options, value, name });
+/**
+ * Factory for creating argument nodes. The `named` function creates an argument with a name, and the `write` function
+ * writes a list of arguments in parentheses, or `()` when the list is empty.
+ *
+ * @param value The value of the argument. A string is written verbatim.
+ * @param options The settings of the argument. See `KtArgument` for the available properties.
+ * @example
+ * ```ts
+ * ktArgument('30', { name: 'timeout' });
+ * // Emits:
+ * // timeout = 30
+ * ```
+ */
 export const ktArgument = Object.assign(createArgument, {
     named: createNamedArgument,
     write: writeKtArguments,

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

@@ -9,14 +9,56 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     arguments?: Nullable<Nullable<KtArgument<TBuilder> | KtValue<TBuilder>>[]>;
     infix?: boolean;
 }>;
+/**
+ * Represents a call of a function, such as `listOf(1, 2)` or `client.get("/pets")`.
+ *
+ * Written in this order: the path with its segments joined by dots, then the arguments in parentheses. With `infix` set
+ * and a single argument, the call is written in infix form without parentheses instead.
+ *
+ * @template TBuilder The type of the source builder the call is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktCall
+ */
 export declare class KtCall<TBuilder extends SourceBuilder, TInjects extends string = never> extends KtNode<TBuilder, TInjects | Injects> {
+    /**
+     * The segments of the callee, joined with dots, such as `client` and `get` for `client.get`. With more than two
+     * segments, the first segment is written on its own line and each following segment is indented on a new line,
+     * starting with a dot.
+     */
     path: (KtType<TBuilder> | KtValue<TBuilder>)[];
+    /**
+     * The arguments written in parentheses after the path, such as `(1, 2)`. An empty list writes `()`, while `null`
+     * omits the parentheses entirely, which turns the call into a plain property access.
+     */
     arguments: (KtArgument<TBuilder> | KtValue<TBuilder>)[] | null;
+    /**
+     * Whether the call is written in infix form, such as `a plus b`. Infix form requires exactly one argument and a path
+     * with more than one segment, and only the first and the last path segment are written in that form. Otherwise the
+     * normal call form is used.
+     * @default false
+     */
     infix: boolean;
+    /**
+     * Initializes a new instance of the KtCall class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
 declare const createCall: <TBuilder extends SourceBuilder>(path: Options<TBuilder>['path'] | ArrayItem<Options<TBuilder>['path']>, args?: Options<TBuilder>['arguments'], options?: Prettify<Omit<Options<TBuilder>, 'path' | 'arguments'>>) => KtCall<TBuilder>;
+/**
+ * Factory for creating call nodes. The `write` function writes one or more call nodes to a builder.
+ *
+ * @param path The segments of the callee. A single segment can be passed without an array.
+ * @param args The arguments of the call. `null` or `undefined` writes the call without parentheses.
+ * @param options The settings of the call. See `KtCall` for the available properties.
+ * @example
+ * ```ts
+ * ktCall(['client', 'get'], ['"/pets"']);
+ * // Emits:
+ * // client.get("/pets")
+ * ```
+ */
 export declare const ktCall: typeof createCall & {
     write: typeof writeKtNodes;
 };

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

@@ -2,10 +2,39 @@ import { notNullish, } from '@goast/core';
 import { KtNode } from '../node.js';
 import { writeKtNode, writeKtNodes } from '../utils/write-kt-node.js';
 import { ktArgument } from './argument.js';
+/**
+ * Represents a call of a function, such as `listOf(1, 2)` or `client.get("/pets")`.
+ *
+ * Written in this order: the path with its segments joined by dots, then the arguments in parentheses. With `infix` set
+ * and a single argument, the call is written in infix form without parentheses instead.
+ *
+ * @template TBuilder The type of the source builder the call is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktCall
+ */
 export class KtCall extends KtNode {
+    /**
+     * The segments of the callee, joined with dots, such as `client` and `get` for `client.get`. With more than two
+     * segments, the first segment is written on its own line and each following segment is indented on a new line,
+     * starting with a dot.
+     */
     path;
+    /**
+     * The arguments written in parentheses after the path, such as `(1, 2)`. An empty list writes `()`, while `null`
+     * omits the parentheses entirely, which turns the call into a plain property access.
+     */
     arguments;
+    /**
+     * Whether the call is written in infix form, such as `a plus b`. Infix form requires exactly one argument and a path
+     * with more than one segment, and only the first and the last path segment are written in that form. Otherwise the
+     * normal call form is used.
+     * @default false
+     */
     infix;
+    /**
+     * Initializes a new instance of the KtCall class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.path = options.path.filter(notNullish);
@@ -39,6 +68,19 @@ export class KtCall extends KtNode {
     }
 }
 const createCall = (path, args, options) => new KtCall({ ...options, path: Array.isArray(path) ? path : [path], arguments: args });
+/**
+ * Factory for creating call nodes. The `write` function writes one or more call nodes to a builder.
+ *
+ * @param path The segments of the callee. A single segment can be passed without an array.
+ * @param args The arguments of the call. `null` or `undefined` writes the call without parentheses.
+ * @param options The settings of the call. See `KtCall` for the available properties.
+ * @example
+ * ```ts
+ * ktCall(['client', 'get'], ['"/pets"']);
+ * // Emits:
+ * // client.get("/pets")
+ * ```
+ */
 export const ktCall = Object.assign(createCall, {
     write: writeKtNodes,
 });

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

@@ -29,26 +29,122 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     companionObject?: Nullable<KtObject<TBuilder>>;
     members?: Nullable<Nullable<KtClassMember<TBuilder>>[]>;
 }>;
+/**
+ * The kinds of class that are written as a keyword before `class`, such as `data` for `data class`.
+ */
 export type KtClassKind = 'data' | 'value' | 'annotation' | 'sealed';
+/**
+ * The nodes that can be written as members of a class body. Other append values are written as-is.
+ */
 export type KtClassMember<TBuilder extends SourceBuilder> = KtConstructor<TBuilder> | KtEnum<TBuilder> | KtInitBlock<TBuilder> | KtInterface<TBuilder> | KtProperty<TBuilder> | KtFunction<TBuilder> | KtClass<TBuilder> | AppendValue<TBuilder>;
+/**
+ * Represents a Kotlin class declaration, such as `data class PetDto(val id: Long)`.
+ *
+ * Written in this order: the doc comment, annotations, modifiers, the `class` keyword and name, generics, the primary
+ * constructor, the inheritance list, then the body. The modifiers are written in the order access modifier, `open`,
+ * `abstract`, class kind. The body is written in braces only when it has members, a companion object or a primary
+ * constructor body.
+ *
+ * @template TBuilder The type of the source builder the class is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktClass
+ */
 export declare class KtClass<TBuilder extends SourceBuilder, TInjects extends string = never> extends KtNode<TBuilder, TInjects | Injects> {
+    /**
+     * The KDoc comment written above the class, or `null` to omit it. Descriptions of generic parameters and primary
+     * constructor parameters are merged into it as `@param` tags, and property descriptions of primary constructor
+     * parameters are merged into it as `@property` tags.
+     */
     doc: KtDoc<TBuilder> | null;
+    /**
+     * The annotations written above the class, each on its own line.
+     */
     annotations: KtAnnotation<TBuilder>[];
+    /**
+     * The visibility modifier written before the `class` keyword, or `null` to omit it. Kotlin classes are public by
+     * default, so `null` writes a public class.
+     */
     accessModifier: KtAccessModifier | null;
+    /**
+     * Whether the class is written with the `open` modifier, which allows other classes to extend it.
+     * @default false
+     */
     open: boolean;
+    /**
+     * Whether the class is written with the `abstract` modifier, placed after `open` when both are set.
+     * @default false
+     */
     abstract: boolean;
+    /**
+     * The kind of the class, written as a keyword before `class`, such as `data` for `data class`. `null` writes a
+     * regular class.
+     */
     classKind: KtClassKind | null;
+    /**
+     * The class name, written verbatim after the `class` keyword.
+     */
     name: string;
+    /**
+     * The type parameters written in angle brackets after the name, such as `<T, U>`. Plain strings are written as-is,
+     * while described parameters also add a `@param` tag to the doc comment.
+     */
     generics: (KtGenericParameter<TBuilder> | BasicAppendValue<TBuilder>)[];
+    /**
+     * The primary constructor written in parentheses after the name, or `null` to omit it. Only its annotations, access
+     * modifier and parameters are written in the header, while its body is written as an `init` block in the class body.
+     */
     primaryConstructor: KtConstructor<TBuilder> | null;
+    /**
+     * The base class written after `:` in the inheritance list, or `null` to omit it. When the primary constructor
+     * delegates to `super`, its arguments are written after the base class, such as `Bar(x)`.
+     */
     extends: KtType<TBuilder> | null;
+    /**
+     * The further supertypes written in the inheritance list after `:`, separated by commas. When a base class is also
+     * set, they follow it after a comma.
+     */
     implements: KtType<TBuilder>[];
+    /**
+     * The members written in the class body, in the given order. Properties without a doc comment or annotations are
+     * written without blank lines between them, while other members are set off by blank lines.
+     */
     members: KtClassMember<TBuilder>[];
+    /**
+     * The companion object written first in the class body, or `null` to omit it. It is written before the `init` block
+     * of the primary constructor and before the members.
+     */
     companionObject: Nullable<KtObject<TBuilder>>;
+    /**
+     * Initializes a new instance of the KtClass class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
 declare const createClass: <TBuilder extends SourceBuilder>(name: Options<TBuilder>['name'], options?: Prettify<Omit<Options<TBuilder>, 'name'>>) => KtClass<TBuilder>;
+/**
+ * Factory for creating class nodes. The `write` function writes one or more class nodes to a builder.
+ *
+ * @param name The name of the class.
+ * @param options The settings of the class. See `KtClass` for the available properties.
+ * @example
+ * ```ts
+ * ktClass('PetDto', {
+ *   annotations: [ktAnnotation('Serializable')],
+ *   classKind: 'data',
+ *   primaryConstructor: ktConstructor([
+ *     ktParameter.class('id', 'Long', { property: 'readonly' }),
+ *     ktParameter.class('name', 'String', { property: 'readonly' }),
+ *   ]),
+ *   members: [ktProperty('tag', { type: 'String?' })],
+ * });
+ * // Emits:
+ * // @Serializable
+ * // data class PetDto(val id: Long, val name: String) {
+ * //     val tag: String?
+ * // }
+ * ```
+ */
 export declare const ktClass: typeof createClass & {
     write: typeof writeKtNodes;
 };

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

@@ -7,20 +7,87 @@ import { ktArgument } from './argument.js';
 import { ktDoc } from './doc.js';
 import { ktGenericParameter } from './generic-parameter.js';
 import { ktInitBlock } from './init-block.js';
+/**
+ * Represents a Kotlin class declaration, such as `data class PetDto(val id: Long)`.
+ *
+ * Written in this order: the doc comment, annotations, modifiers, the `class` keyword and name, generics, the primary
+ * constructor, the inheritance list, then the body. The modifiers are written in the order access modifier, `open`,
+ * `abstract`, class kind. The body is written in braces only when it has members, a companion object or a primary
+ * constructor body.
+ *
+ * @template TBuilder The type of the source builder the class is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see ktClass
+ */
 export class KtClass extends KtNode {
+    /**
+     * The KDoc comment written above the class, or `null` to omit it. Descriptions of generic parameters and primary
+     * constructor parameters are merged into it as `@param` tags, and property descriptions of primary constructor
+     * parameters are merged into it as `@property` tags.
+     */
     doc;
+    /**
+     * The annotations written above the class, each on its own line.
+     */
     annotations;
+    /**
+     * The visibility modifier written before the `class` keyword, or `null` to omit it. Kotlin classes are public by
+     * default, so `null` writes a public class.
+     */
     accessModifier;
+    /**
+     * Whether the class is written with the `open` modifier, which allows other classes to extend it.
+     * @default false
+     */
     open;
+    /**
+     * Whether the class is written with the `abstract` modifier, placed after `open` when both are set.
+     * @default false
+     */
     abstract;
+    /**
+     * The kind of the class, written as a keyword before `class`, such as `data` for `data class`. `null` writes a
+     * regular class.
+     */
     classKind;
+    /**
+     * The class name, written verbatim after the `class` keyword.
+     */
     name;
+    /**
+     * The type parameters written in angle brackets after the name, such as `<T, U>`. Plain strings are written as-is,
+     * while described parameters also add a `@param` tag to the doc comment.
+     */
     generics;
+    /**
+     * The primary constructor written in parentheses after the name, or `null` to omit it. Only its annotations, access
+     * modifier and parameters are written in the header, while its body is written as an `init` block in the class body.
+     */
     primaryConstructor;
+    /**
+     * The base class written after `:` in the inheritance list, or `null` to omit it. When the primary constructor
+     * delegates to `super`, its arguments are written after the base class, such as `Bar(x)`.
+     */
     extends;
+    /**
+     * The further supertypes written in the inheritance list after `:`, separated by commas. When a base class is also
+     * set, they follow it after a comma.
+     */
     implements;
+    /**
+     * The members written in the class body, in the given order. Properties without a doc comment or annotations are
+     * written without blank lines between them, while other members are set off by blank lines.
+     */
     members;
+    /**
+     * The companion object written first in the class body, or `null` to omit it. It is written before the `init` block
+     * of the primary constructor and before the members.
+     */
     companionObject;
+    /**
+     * Initializes a new instance of the KtClass class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.doc = options.doc ?? null;
@@ -95,6 +162,29 @@ export class KtClass extends KtNode {
     }
 }
 const createClass = (name, options) => new KtClass({ ...options, name });
+/**
+ * Factory for creating class nodes. The `write` function writes one or more class nodes to a builder.
+ *
+ * @param name The name of the class.
+ * @param options The settings of the class. See `KtClass` for the available properties.
+ * @example
+ * ```ts
+ * ktClass('PetDto', {
+ *   annotations: [ktAnnotation('Serializable')],
+ *   classKind: 'data',
+ *   primaryConstructor: ktConstructor([
+ *     ktParameter.class('id', 'Long', { property: 'readonly' }),
+ *     ktParameter.class('name', 'String', { property: 'readonly' }),
+ *   ]),
+ *   members: [ktProperty('tag', { type: 'String?' })],
+ * });
+ * // Emits:
+ * // @Serializable
+ * // data class PetDto(val id: Long, val name: String) {
+ * //     val tag: String?
+ * // }
+ * ```
+ */
 export const ktClass = Object.assign(createClass, {
     write: writeKtNodes,
 });