@goast/kotlin 0.7.0-beta.2 → 0.7.1

package/dist/src/generators/models/args.d.ts

@@ -1,109 +1,342 @@
 import type { ApiSchema, ApiSchemaProperty } from '@goast/core';
+/**
+ * Arguments of `getFileContent`. The method takes no arguments beyond its context, so this type has no properties.
+ */
 export type GetFileContent = object;
+/**
+ * Arguments of `getSchemaDeclaration`, which writes the declaration of a schema into a model file.
+ */
 export type GetSchemaDeclaration = {
+    /**
+     * The normalized schema to declare as a class, interface or enum.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `getClass`, which declares an object schema without a discriminator as a Kotlin class.
+ */
 export type GetClass = {
+    /**
+     * The object schema to declare as a class. Its properties become the constructor parameters.
+     */
     schema: ApiSchema<'object'>;
 };
+/**
+ * Arguments of `getInterface`, which declares a discriminated object schema as a Kotlin interface.
+ */
 export type GetInterface = {
+    /**
+     * The discriminated object schema to declare as an interface. Its properties become interface members.
+     */
     schema: ApiSchema<'object'>;
 };
+/**
+ * Arguments of `getEnum`, which declares a string enum schema as a Kotlin enum class.
+ */
 export type GetEnum = {
+    /**
+     * The schema with a non-empty `enum` list to declare as an enum class.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `getSchemaDocDescription`, which builds the text of the doc comment of a schema or property.
+ */
 export type GetSchemaDocDescription = {
+    /**
+     * The schema whose description is used. Its source location is added when `includeSourceInDocs` is set.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `getType`, which maps a schema to the Kotlin type used to reference it.
+ */
 export type GetType = {
+    /**
+     * The schema to map to a Kotlin type.
+     */
     schema: ApiSchema;
+    /**
+     * Whether the type is nullable. When omitted, the schema's own `nullable` flag decides.
+     */
     nullable?: boolean;
 };
+/**
+ * Arguments of `getGeneratedType`, which looks up the type of a schema that has its own generated declaration.
+ */
 export type GetGeneratedType = {
+    /**
+     * The schema to look up. A reference to another schema is resolved to the schema it points to first.
+     */
     schema: ApiSchema;
+    /**
+     * Whether the reference is nullable. When omitted, the schema's own `nullable` flag decides.
+     */
     nullable?: boolean;
 };
+/**
+ * Arguments of `getAdditionalPropertiesType`, which resolves the value type of an object's `additionalProperties`.
+ */
 export type GetAdditionalPropertiesType = {
+    /**
+     * The object schema whose `additionalProperties` value type is resolved. A nullable `Any` is used when the
+     * value is not a schema.
+     */
     schema: ApiSchema<'object'>;
 };
+/**
+ * Arguments of `getDefaultValue`, which renders the `default` of a schema as a Kotlin expression.
+ */
 export type GetDefaultValue = {
+    /**
+     * The schema whose `default` value is rendered. A missing default is rendered as `null`.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `getClassParameter`, which declares one property as a constructor parameter of a class.
+ */
 export type GetClassParameter = {
+    /**
+     * The object schema that declares the class. Its `required` set decides whether the parameter is nullable.
+     */
     schema: ApiSchema<'object'>;
+    /**
+     * The schemas the class inherits from. A parameter that one of them also declares is marked as an override.
+     */
     inheritedSchemas: ApiSchema[];
+    /**
+     * All constructor parameters of the class, in the order they are written.
+     */
     parameters: ApiSchemaProperty[];
+    /**
+     * The property to declare as the constructor parameter.
+     */
     property: ApiSchemaProperty;
 };
+/**
+ * Arguments of `getInterfaceProperty`, which declares one property as a member of an interface.
+ */
 export type GetInterfaceProperty = {
+    /**
+     * The discriminated object schema that declares the interface. Its `required` set decides whether the property
+     * is nullable.
+     */
     schema: ApiSchema<'object'>;
+    /**
+     * The property to declare as an interface member.
+     */
     property: ApiSchemaProperty;
 };
+/**
+ * Arguments of `getAdditionalPropertiesProperty`, which declares the `additionalProperties` map of a class.
+ */
 export type GetAdditionalPropertiesProperty = {
+    /**
+     * The object schema whose `additionalProperties` are declared as a mutable map.
+     */
     schema: ApiSchema<'object'>;
 };
+/**
+ * Arguments of `getAdditionalPropertiesSetter`, which declares the `set` function that stores an additional property.
+ */
 export type GetAdditionalPropertiesSetter = {
+    /**
+     * The object schema whose `additionalProperties` the setter writes to.
+     */
     schema: ApiSchema<'object'>;
 };
+/**
+ * Arguments of `getAdditionalPropertiesGetter`, which declares the `getMap` function that returns the additional
+ * properties.
+ */
 export type GetAdditionalPropertiesGetter = {
+    /**
+     * The object schema whose `additionalProperties` the getter returns.
+     */
     schema: ApiSchema<'object'>;
 };
+/**
+ * Arguments of `getJacksonJsonTypeInfoAnnotation`, which builds the `@JsonTypeInfo` annotation of an interface.
+ */
 export type GetJacksonJsonTypeInfoAnnotation = {
+    /**
+     * The schema whose `discriminator` names the property that selects the subtype.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `getJacksonJsonSubTypesAnnotation`, which builds the `@JsonSubTypes` annotation of an interface.
+ */
 export type GetJacksonJsonSubTypesAnnotation = {
+    /**
+     * The discriminated schema whose `discriminator.mapping` entries are listed as subtypes.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `getJacksonJsonClassDescriptionAnnotation`, which builds the `@JsonClassDescription` annotation.
+ */
 export type GetJacksonJsonClassDescriptionAnnotation = {
+    /**
+     * The schema whose `description` is written into the annotation.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `getJacksonJsonPropertyAnnotation`, which builds the `@JsonProperty` annotation of a property.
+ */
 export type GetJacksonJsonPropertyAnnotation = {
+    /**
+     * The schema that declares the property. Its `required` set adds `required = true` to the annotation.
+     */
     schema: ApiSchema;
+    /**
+     * The property whose name is written into the annotation.
+     */
     property: ApiSchemaProperty;
 };
+/**
+ * Arguments of `getJacksonJsonPropertyDescriptionAnnotation`, which builds the `@JsonPropertyDescription` annotation.
+ */
 export type GetJacksonJsonPropertyDescriptionAnnotation = {
+    /**
+     * The schema that declares the property. The default implementation does not read it.
+     */
     schema: ApiSchema;
+    /**
+     * The property whose `description` is written into the annotation.
+     */
     property: ApiSchemaProperty;
 };
+/**
+ * Arguments of `getJacksonJsonIncludeAnnotation`, which builds the `@JsonInclude` annotation of a property.
+ */
 export type GetJacksonJsonIncludeAnnotation = {
+    /**
+     * The schema that declares the property. The default implementation does not read it.
+     */
     schema: ApiSchema;
+    /**
+     * The property whose `exclude-when-null` custom flag selects `@JsonInclude(NON_NULL)`.
+     */
     property: ApiSchemaProperty;
 };
+/**
+ * Arguments of `getJakartaValidationAnnotations`, which builds the Jakarta Validation annotations of a property.
+ */
 export type GetJakartaValidationAnnotations = {
+    /**
+     * The schema that declares the property. The default implementation does not read it.
+     */
     schema: ApiSchema;
+    /**
+     * The property whose constraints (pattern, length, size and range) and generated type determine the annotations.
+     */
     property: ApiSchemaProperty;
 };
+/**
+ * Arguments of `getSwaggerSchemaAnnotation`, which builds the Swagger `@Schema` annotation of a property.
+ */
 export type GetSwaggerSchemaAnnotation = {
+    /**
+     * The schema that declares the property. Its `required` set adds `required = true` to the annotation.
+     */
     schema: ApiSchema;
+    /**
+     * The property whose example, description and deprecation flag are written into the annotation.
+     */
     property: ApiSchemaProperty;
 };
+/**
+ * Arguments of `getPackageName`, which resolves the package the model of a schema is generated in.
+ */
 export type GetPackageName = {
+    /**
+     * The schema whose package is resolved. It is passed to `packageSuffix` when that option is a function.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `shouldGenerateTypeDeclaration`, which decides whether a schema gets its own declaration and file.
+ */
 export type ShouldGenerateTypeDeclaration = {
+    /**
+     * The schema to check. Enum schemas always get a declaration, and primitive schemas never do.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `getDeclarationTypeName`, which derives the Kotlin type name of a schema.
+ */
 export type GetDeclarationTypeName = {
+    /**
+     * The schema whose `name` is converted with the `typeNameCasing` option.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `getInheritedSchemas`, which collects the schemas a class inherits from.
+ */
 export type GetInheritedSchemas = {
+    /**
+     * The schema whose inherited schemas are collected. Only those that get their own named declaration are kept.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `getClassProperties`, which collects the constructor parameters of a class.
+ */
 export type GetClassProperties = {
+    /**
+     * The object schema whose properties are collected. A discriminator property that the mapping of an inherited
+     * schema fixes to this schema gets that value as its default and is moved to the end.
+     */
     schema: ApiSchema<'object'>;
 };
+/**
+ * Arguments of `sortProperties`, which orders the properties of a class or interface.
+ */
 export type SortProperties = {
+    /**
+     * The schema whose `required` set and defaults determine the order.
+     */
     schema: ApiSchema;
+    /**
+     * The properties to sort. The iterable is copied, so it is not modified.
+     */
     properties: Iterable<ApiSchemaProperty>;
 };
+/**
+ * Arguments of `normalizeSchema`, which turns a schema into the form that is declared.
+ */
 export type NormalizeSchema = {
+    /**
+     * The schema to normalize. A `oneOf` is turned into `anyOf` or `allOf` according to `oneOfBehavior`, and object
+     * compositions are merged into one object where possible.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `normalizeDiscriminatedBases`, which rewrites discriminated `oneOf` bases into objects.
+ */
 export type NormalizeDiscriminatedBases = {
+    /**
+     * The schema whose compositions are searched for discriminated `oneOf` bases to rewrite.
+     */
     schema: ApiSchema;
 };
+/**
+ * Arguments of `hasProperty`, which checks whether a schema declares a property, directly or through its compositions.
+ */
 export type HasProperty = {
+    /**
+     * The schema to search, including the schemas it composes with `allOf`, `anyOf` and undiscriminated `oneOf`.
+     */
     schema: ApiSchema;
+    /**
+     * The name of the property to look for.
+     */
     propertyName: string;
     /** The schemas already inspected, so a composition that cycles back on itself terminates. */
     visited?: Set<ApiSchema>;

package/dist/src/generators/models/model-generator.d.ts

@@ -7,10 +7,35 @@ import type { KotlinModelGeneratorContext, KotlinModelGeneratorOutput } from './
 type Context = KotlinModelGeneratorContext;
 type Output = KotlinModelGeneratorOutput;
 type Builder = KotlinFileBuilder;
+/**
+ * Generates the model for one schema. Implement this interface to replace the default model generation, or extend
+ * `DefaultKotlinModelGenerator` to change parts of it.
+ * @template TOutput The type of the result the generator returns. It extends `KotlinModelGeneratorOutput`.
+ * @see DefaultKotlinModelGenerator
+ */
 export interface KotlinModelGenerator<TOutput extends Output = Output> {
+    /**
+     * Generates the model for the schema in the context.
+     * @param ctx The context containing the schema to generate the model for.
+     * @returns The result for the schema, or a promise of it.
+     */
     generate(ctx: Context): MaybePromise<TOutput>;
 }
+/**
+ * The default model generator. A schema that gets its own declaration is written to
+ * `{outputDir}/{packagePath}/{TypeName}.kt` as a `data class`, a plain class, an interface for a discriminated base
+ * or an enum, depending on the schema.
+ * Any other schema is mapped to a built-in Kotlin type and no file is written. Schemas that exist only as `anyOf` or
+ * `allOf` members resolve to a nullable `Any`.
+ * @see KotlinModelGenerator
+ * @see KotlinModelsGenerator
+ */
 export declare class DefaultKotlinModelGenerator extends KotlinFileGenerator<Context, Output> implements KotlinModelGenerator {
+    /**
+     * Generates the model for the schema in the context. Writes the model file when the schema gets its own declaration.
+     * @param ctx The context containing the schema to generate the model for.
+     * @returns The Kotlin type the schema maps to, which is a reference to the generated declaration or a built-in type.
+     */
     generate(ctx: Context): MaybePromise<KotlinModelGeneratorOutput>;
     protected getFileContent(ctx: Context, _args: Args.GetFileContent): AppendValueGroup<Builder>;
     protected getSchemaDeclaration(ctx: Context, args: Args.GetSchemaDeclaration): AppendValue<Builder>;

package/dist/src/generators/models/model-generator.js

@@ -3,7 +3,21 @@ import { kt } from '../../ast/index.js';
 import { KotlinFileBuilder } from '../../file-builder.js';
 import { getSourceDocLine, getStringEnumSchema } from '../../utils.js';
 import { KotlinFileGenerator } from '../file-generator.js';
+/**
+ * The default model generator. A schema that gets its own declaration is written to
+ * `{outputDir}/{packagePath}/{TypeName}.kt` as a `data class`, a plain class, an interface for a discriminated base
+ * or an enum, depending on the schema.
+ * Any other schema is mapped to a built-in Kotlin type and no file is written. Schemas that exist only as `anyOf` or
+ * `allOf` members resolve to a nullable `Any`.
+ * @see KotlinModelGenerator
+ * @see KotlinModelsGenerator
+ */
 export class DefaultKotlinModelGenerator extends KotlinFileGenerator {
+    /**
+     * Generates the model for the schema in the context. Writes the model file when the schema gets its own declaration.
+     * @param ctx The context containing the schema to generate the model for.
+     * @returns The Kotlin type the schema maps to, which is a reference to the generated declaration or a built-in type.
+     */
     generate(ctx) {
         if (/\/(anyOf|allOf)(\/[0-9]+)?$/.test(ctx.schema.$src.path)) {
             // Do not generate types that are only used for anyOf and/or allOf

package/dist/src/generators/models/models-generator.d.ts

@@ -6,8 +6,23 @@ type Output = KotlinModelsGeneratorOutput;
 type Config = KotlinModelsGeneratorConfig;
 type SchemaOutput = KotlinModelGeneratorOutput;
 type Context = KotlinModelsGeneratorContext;
+/**
+ * Generates a Kotlin model for each schema of the document and publishes the results under `kotlin.models`.
+ *
+ * Each schema is passed to the `KotlinModelGenerator` created by the model generator factory. A schema that gets its
+ * own declaration is written to `{outputDir}/{packagePath}/{TypeName}.kt`, where `packagePath` is the model package
+ * (`packageName` followed by `packageSuffix`) with the dots replaced by slashes. Other schemas get no file.
+ * The result of every schema is stored under `kotlin.models`, keyed by the schema ID. No index file is generated.
+ * @see KotlinModelsGeneratorConfig
+ * @see DefaultKotlinModelGenerator
+ */
 export declare class KotlinModelsGenerator extends OpenApiSchemasGenerationProviderBase<Input, Output, Config, SchemaOutput, Context> {
     private readonly _modelGeneratorFactory;
+    /**
+     * Initializes a new instance of the KotlinModelsGenerator class.
+     * @param modelGeneratorFactory Creates the generator used for each schema. Defaults to a
+     * `DefaultKotlinModelGenerator`.
+     */
     constructor(modelGeneratorFactory?: Factory<KotlinModelGenerator, []>);
     protected initResult(): Output;
     protected buildContext(context: OpenApiGeneratorContext<KotlinModelsGeneratorInput>, config?: Partial<Config> | undefined): Context;

package/dist/src/generators/models/models-generator.js

@@ -1,8 +1,23 @@
 import { Factory, OpenApiSchemasGenerationProviderBase, } from '@goast/core';
 import { DefaultKotlinModelGenerator } from './model-generator.js';
 import { defaultKotlinModelsGeneratorConfig, } from './models.js';
+/**
+ * Generates a Kotlin model for each schema of the document and publishes the results under `kotlin.models`.
+ *
+ * Each schema is passed to the `KotlinModelGenerator` created by the model generator factory. A schema that gets its
+ * own declaration is written to `{outputDir}/{packagePath}/{TypeName}.kt`, where `packagePath` is the model package
+ * (`packageName` followed by `packageSuffix`) with the dots replaced by slashes. Other schemas get no file.
+ * The result of every schema is stored under `kotlin.models`, keyed by the schema ID. No index file is generated.
+ * @see KotlinModelsGeneratorConfig
+ * @see DefaultKotlinModelGenerator
+ */
 export class KotlinModelsGenerator extends OpenApiSchemasGenerationProviderBase {
     _modelGeneratorFactory;
+    /**
+     * Initializes a new instance of the KotlinModelsGenerator class.
+     * @param modelGeneratorFactory Creates the generator used for each schema. Defaults to a
+     * `DefaultKotlinModelGenerator`.
+     */
     constructor(modelGeneratorFactory) {
         super();
         this._modelGeneratorFactory = modelGeneratorFactory ?? Factory.fromValue(new DefaultKotlinModelGenerator());

package/dist/src/generators/models/models.d.ts

@@ -1,19 +1,56 @@
 import type { ApiSchema, DefaultGenerationProviderConfig, OpenApiSchemasGenerationProviderContext, SourceBuilder } from '@goast/core';
 import type { kt } from '../../ast/index.ts';
 import { type KotlinGeneratorConfig } from '../../config.ts';
+/**
+ * The configuration of the `KotlinModelsGenerator`. It extends the common Kotlin generator configuration with the
+ * model-specific options declared below.
+ *
+ * The common options are declared on `KotlinGeneratorConfig`. Their effect on the generated models is:
+ * - `outputDir`: The root directory of the model files, which are placed in a package-based subdirectory.
+ *   Default `'generated'`.
+ * - `clearOutputDir`: Empties `outputDir` once before any model is written, so it also removes files written by other
+ *   generators. Default `true`.
+ * - `existingFileBehavior`: What happens when a model file already exists at its path. Default `'error'`.
+ * - `indent`: The indentation of the generated Kotlin code. Default four spaces (`{ type: 'spaces', count: 4 }`).
+ * - `newLine`: The line separator of the generated files. Default `os.EOL`.
+ * - `typeNameCasing`: The casing of type names, which also determines the model file names. Default `'pascal'`.
+ * - `parameterNameCasing`: The casing of the parameters of the generated `set` function for `additionalProperties`.
+ *   Default `'camel'`.
+ * - `functionNameCasing`: The casing of the generated `set` and `getMap` functions for `additionalProperties`.
+ *   Default `'camel'`.
+ * - `propertyNameCasing`: The casing of property names, the `value` property of enums and `additionalProperties`.
+ *   Default `'camel'`.
+ * - `enumValueNameCasing`: The casing of enum constant names, so the value `available` becomes `AVAILABLE`.
+ *   Default `'snake'`.
+ * - `constantNameCasing`: No effect on this generator. Default `'snake'`.
+ * - `globalImports`: Imports that are not written to the generated files, such as the standard `kotlin.*`,
+ *   `java.lang.*` and `kotlin.jvm.*` packages. Default: `defaultKotlinGeneratorConfig.globalImports`.
+ * - `includeSourceInDocs`: Adds the source document path to the doc comments of generated classes, interfaces, enums
+ *   and interface properties. Default `false`.
+ * - `springBootVersion`: No effect on this generator, because the Jackson annotations it writes are the same for both
+ *   versions. Default `3`.
+ * @see defaultKotlinModelsGeneratorConfig
+ */
 export type KotlinModelsGeneratorConfig = KotlinGeneratorConfig & {
     /**
      * The package name for generated models.
+     * The model files are placed in `{outputDir}/{packagePath}`, where `packagePath` is `packageName` followed by
+     * `packageSuffix` with the dots replaced by slashes. The same package is written as the `package` declaration.
      * @default 'com.openapi.generated'
      */
     packageName: string;
     /**
      * The suffix to append to the package name for generated models.
+     * Include the leading `.`, because the suffix is appended as written. A function receives the schema of each model
+     * and returns the suffix for it, which allows models to be split across packages. The resulting package determines
+     * the model's file path and its `package` declaration.
      * @default '.model'
      */
     packageSuffix: string | ((schema: ApiSchema) => string);
     /**
      * Determines how `oneOf` schemas should be treated.
+     * This changes which properties the generated class or interface declares. Under `treat-as-any-of` the properties of
+     * the branches are merged as optional properties, and under `treat-as-all-of` they are merged as `allOf` members.
      * - `treat-as-any-of`: Treat `oneOf` schemas as `anyOf` schemas.
      * - `treat-as-all-of`: Treat `oneOf` schemas as `allOf` schemas.
      * @default 'treat-as-any-of'
@@ -21,40 +58,94 @@ export type KotlinModelsGeneratorConfig = KotlinGeneratorConfig & {
     oneOfBehavior: 'treat-as-any-of' | 'treat-as-all-of';
     /**
      * Determines how schemas of type `object` without properties should be treated.
-     * - `use-any`: Generate `Any` type for empty object schemas.
-     * - `generate-empty-class`: Generate an empty class for empty object schemas.
+     * Empty object schemas that allow additional properties always become `Map<String, ...>`, and discriminated base
+     * schemas always get their own file, regardless of this setting.
+     * - `use-any`: Generate `Any` type for empty object schemas. No file is generated for them.
+     * - `generate-empty-class`: Generate an empty class for empty object schemas. The class is not a `data class`.
      * @default 'generate-empty-class'
      */
     emptyObjectTypeBehavior: 'use-any' | 'generate-empty-class';
     /**
      * Whether to add Jackson annotations to generated models.
+     * When `true`, classes and interfaces get `@JsonClassDescription`, interfaces also get `@JsonTypeInfo` and
+     * `@JsonSubTypes`, and properties get `@JsonProperty`, `@JsonPropertyDescription` and `@JsonInclude` where
+     * applicable. When `false`, these are omitted. Enum constants keep their `@JsonProperty` annotation, and
+     * `additionalProperties` keep `@JsonIgnore`, `@JsonAnySetter` and `@JsonAnyGetter` either way.
      * @default true
      */
     addJacksonAnnotations: boolean;
     /**
      * Whether to add Jakarta Validation annotations to generated models.
+     * When `true`, constructor parameters of generated classes get `@Pattern`, `@NotEmpty`, `@Size`, `@Min` and `@Max`
+     * from the property's constraints, and `@Valid` when the property refers to a generated model. Interface properties
+     * do not receive them. When `false`, none of these are added.
      * @default true
      */
     addJakartaValidationAnnotations: boolean;
     /**
      * Whether to add Swagger annotations to generated models.
+     * When `true`, each constructor parameter of a generated class gets a `@Schema` annotation with its example,
+     * `required` flag, description and deprecation. Interface properties do not receive it. When `false`, none is added.
      * @default true
      */
     addSwaggerAnnotations: boolean;
 };
+/**
+ * The default configuration of the `KotlinModelsGenerator`. Options passed to the generator are merged on top of these.
+ * It includes the common Kotlin defaults from `defaultKotlinGeneratorConfig`.
+ * @see KotlinModelsGeneratorConfig
+ */
 export declare const defaultKotlinModelsGeneratorConfig: DefaultGenerationProviderConfig<KotlinModelsGeneratorConfig>;
+/**
+ * The input of the `KotlinModelsGenerator`. The generator does not use any input data, so this type has no properties.
+ */
 export type KotlinModelsGeneratorInput = {};
+/**
+ * The output of the `KotlinModelsGenerator`. It is merged into the generation result, where the models are published
+ * under the `kotlin.models` key.
+ * @see KotlinModelGeneratorOutput
+ */
 export type KotlinModelsGeneratorOutput = {
+    /**
+     * The Kotlin results of the generator, grouped under the `kotlin` key.
+     */
     kotlin: {
+        /**
+         * The generated models, keyed by the ID of their schema. Each entry describes the Kotlin type the schema maps to.
+         */
         models: {
+            /**
+             * The result for the schema with the given ID. Schemas that get no file are included as well.
+             */
             [schemaId: string]: KotlinModelGeneratorOutput;
         };
     };
 };
+/**
+ * The result of generating one schema. Its `type` property is the Kotlin type the schema maps to: for a model with
+ * its own file, a reference to the generated class, interface or enum in its package. For any other schema, the
+ * built-in type it was mapped to, such as `String`, `List<...>`, `Map<String, ...>` or `Any`. The file path is not
+ * part of the result.
+ * @see KotlinModelsGeneratorOutput
+ */
 export type KotlinModelGeneratorOutput = {
     type: kt.Reference<SourceBuilder>;
 };
+/**
+ * The context of the `KotlinModelsGenerator`. Besides the generator configuration (`config`) and the parsed document
+ * (`data`), it holds the `output` being built, which contains the `kotlin.models` entries, and the results already
+ * generated per schema (`existingSchemaResults`).
+ * @see KotlinModelGeneratorContext
+ */
 export type KotlinModelsGeneratorContext = OpenApiSchemasGenerationProviderContext<KotlinModelsGeneratorInput, KotlinModelsGeneratorOutput, KotlinModelsGeneratorConfig, KotlinModelGeneratorOutput>;
+/**
+ * The context passed to a `KotlinModelGenerator` for one schema. It extends the `KotlinModelsGeneratorContext` with
+ * the schema to generate.
+ * @see KotlinModelsGeneratorContext
+ */
 export type KotlinModelGeneratorContext = KotlinModelsGeneratorContext & {
+    /**
+     * The schema to generate the model for. Its `$src` path identifies where it appears in the document.
+     */
     schema: ApiSchema;
 };

package/dist/src/generators/models/models.js

@@ -1,4 +1,9 @@
 import { defaultKotlinGeneratorConfig } from '../../config.js';
+/**
+ * The default configuration of the `KotlinModelsGenerator`. Options passed to the generator are merged on top of these.
+ * It includes the common Kotlin defaults from `defaultKotlinGeneratorConfig`.
+ * @see KotlinModelsGeneratorConfig
+ */
 export const defaultKotlinModelsGeneratorConfig = {
     ...defaultKotlinGeneratorConfig,
     packageName: 'com.openapi.generated',