@goast/kotlin 0.7.0 → 0.7.1

package/dist/src/generators/services/okhttp3-clients/args.d.ts

@@ -1,86 +1,224 @@
 import type { ApiEndpoint, ApiParameter, ApiSchema, SourceBuilder } from '@goast/core';
 import type { kt } from '../../../ast/index.ts';
 import type { ApiParameterWithMultipartInfo } from '../../../types.ts';
+/**
+ * Arguments of `getClientFileContent`, which builds the content of a client file. It has no properties, because the
+ * generator context provides everything the method needs.
+ */
 export type GetClientFileContent = object;
+/**
+ * Arguments of `getClientClass`, which builds the client class with its primary constructor, companion object and
+ * members. It has no properties.
+ */
 export type GetClientClass = object;
+/**
+ * Arguments of `getClientCompanionObject`, which builds the companion object that holds `defaultBasePath`.
+ * It has no properties.
+ */
 export type GetClientCompanionObject = object;
+/**
+ * Arguments of `getEndpointClientMembers`, which returns the three members generated for one endpoint: the endpoint
+ * method, its `WithHttpInfo` method and its private `RequestConfig` method.
+ * @property endpoint The endpoint to generate the members for.
+ * @property parameters The method parameters of the endpoint, as returned by `getAllParameters`.
+ */
 export type GetEndpointClientMembers = {
     endpoint: ApiEndpoint;
     parameters: ApiParameter[];
 };
+/**
+ * Arguments of `getEndpointClientMethod`, which builds the endpoint method that returns the response data directly.
+ */
 export type GetEndpointClientMethod = {
+    /** The endpoint the method is generated for. */
     endpoint: ApiEndpoint;
+    /** The method parameters, with required parameters first, as returned by `getAllParameters`. */
     parameters: ApiParameter[];
+    /** The schema of the 2xx or default response, or `undefined` when that response has no schema. */
     responseSchema: ApiSchema | undefined;
 };
+/**
+ * Arguments of `getEndpointClientMethodBody`, which builds the body of the endpoint method. The body calls the
+ * `WithHttpInfo` method and returns its data, or throws for error responses.
+ */
 export type GetEndpointClientMethodBody = {
+    /** The endpoint whose method body is generated. */
     endpoint: ApiEndpoint;
+    /** The parameters to pass on to the `WithHttpInfo` method, in the same order. */
     parameters: ApiParameter[];
+    /** The schema that the successful response data is cast to. `undefined` makes the method return `Unit`. */
     responseSchema: ApiSchema | undefined;
 };
+/**
+ * Arguments of `getEndpointClientHttpInfoMethod`, which builds the `{name}WithHttpInfo` method. Unlike the endpoint
+ * method, it returns the whole `ApiResponse`, not only its data.
+ */
 export type GetEndpointClientHttpInfoMethod = {
+    /** The endpoint the method is generated for. */
     endpoint: ApiEndpoint;
+    /** The method parameters, which keep their names and types in the generated method. */
     parameters: ApiParameter[];
+    /**
+     * The schema of the response data. The data type of the generated return type is always nullable, and `undefined`
+     * falls back to `Unit?`.
+     */
     responseSchema: ApiSchema | undefined;
 };
+/**
+ * Arguments of `getEndpointClientHttpInfoMethodBody`, which builds the body of the `WithHttpInfo` method. The body
+ * creates the request config with the `RequestConfig` method and sends it with `request`.
+ */
 export type GetEndpointClientHttpInfoMethodBody = {
+    /** The endpoint whose request is sent. */
     endpoint: ApiEndpoint;
+    /** The parameters to forward to the private `RequestConfig` method. */
     parameters: ApiParameter[];
+    /** The schema used as the response type argument of `request`. `undefined` uses `Unit`. */
     responseSchema: ApiSchema | undefined;
 };
+/**
+ * Arguments of `getEndpointClientRequestConfigMethod`, which builds the private `{name}RequestConfig` method. That
+ * method returns the `RequestConfig` for one call of the endpoint.
+ */
 export type GetEndpointClientRequestConfigMethod = {
+    /** The endpoint the request config is built for. */
     endpoint: ApiEndpoint;
+    /** The method parameters, including the path parameters that the request path interpolates. */
     parameters: ApiParameter[];
 };
+/**
+ * Arguments of `getEndpointClientRequestConfigMethodBody`, which builds the body of the `RequestConfig` method. It
+ * collects the query, header and body values, and sets the HTTP method and the interpolated path.
+ */
 export type GetEndpointClientRequestConfigMethodBody = {
+    /** The endpoint whose HTTP method and path the request config uses. */
     endpoint: ApiEndpoint;
+    /** The parameters whose values are written to the query, header or body. Multipart fields carry `multipart` info. */
     parameters: ApiParameterWithMultipartInfo[];
 };
+/**
+ * Arguments of `getParameterToString`, which returns the expression that converts a parameter value into a string.
+ */
 export type GetParameterToString = {
+    /** The endpoint that declares the parameter. */
     endpoint: ApiEndpoint;
+    /**
+     * The parameter whose value is converted. String enums use `.value`, arrays are joined with `,`, and other values
+     * use `.toString()`.
+     */
     parameter: ApiParameter;
 };
+/**
+ * Arguments of `getAdditionalClientMembers`, which returns extra members added to every client class, such as the
+ * private `encodeURIComponent` helper. It has no properties.
+ */
 export type GetAdditionalClientMembers = object;
+/**
+ * Arguments of `getParameterType`, which returns the Kotlin type of a method parameter.
+ * @property endpoint The endpoint that declares the parameter.
+ * @property parameter The parameter to type. A file part of a multipart request becomes `java.io.File`.
+ */
 export type GetParameterType = {
     endpoint: ApiEndpoint;
     parameter: ApiParameterWithMultipartInfo;
 };
+/**
+ * Arguments of `getRequestBodyType`, which returns the Kotlin type of the request body. A `multipart/form-data` body
+ * becomes a map of part configs.
+ * @property endpoint The endpoint whose request body type is returned.
+ */
 export type GetRequestBodyType = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments of `getParameterDefaultValue`, which returns the default value expression of a parameter.
+ */
 export type GetParameterDefaultValue = {
+    /** The endpoint that declares the parameter. */
     endpoint: ApiEndpoint;
+    /** The parameter whose default value is returned. Required parameters have no default value. */
     parameter: ApiParameter;
 };
+/**
+ * Arguments of `getTypeUsage`, which returns the Kotlin type used for a schema.
+ * @template TBuilder The type of the source builder the type is written to.
+ */
 export type GetTypeUsage<TBuilder extends SourceBuilder> = {
+    /** The schema to map to a Kotlin type. `undefined` uses `fallback`. */
     schema: ApiSchema | undefined;
+    /** Whether the type is nullable. When omitted, the nullability of the mapped type is kept. */
     nullable?: boolean;
+    /** The type to use when no type is mapped. Defaults to `Any`, nullable when `nullable` is set. */
     fallback?: kt.Type<TBuilder>;
 };
+/**
+ * Arguments of `getPackageName`, which returns the package of the client class. It has no properties.
+ */
 export type GetPackageName = object;
+/**
+ * Arguments of `getPathWithInterpolation`, which returns the endpoint path with each path parameter replaced by an
+ * `encodeURIComponent` template expression.
+ * @property endpoint The endpoint whose path is interpolated.
+ */
 export type GetPathWithInterpolation = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments of `getResponseSchema`, which returns the schema of the successful response.
+ * @property endpoint The endpoint whose response schema is looked up. The first 2xx or default response is used.
+ */
 export type GetResponseSchema = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments of `getSchemaType`, which returns the Kotlin type reference of a schema.
+ * @property schema The schema to look up in the models output. `undefined` yields `undefined`.
+ */
 export type GetSchemaType = {
     schema: ApiSchema | undefined;
 };
+/**
+ * Arguments of `getAllParameters`, which returns the method parameters of an endpoint.
+ * @property endpoint The endpoint whose query, path and header parameters and request body are returned.
+ */
 export type GetAllParameters = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments of `getRequestBodyParamName`, which returns the name of the request body parameter.
+ * @property endpoint The endpoint whose request body parameter is named.
+ */
 export type GetRequestBodyParamName = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments of `getEndpointDocDescription`, which returns the doc text of an endpoint method.
+ * @property endpoint The endpoint whose description is used. The source path is appended when `includeSourceInDocs`
+ * is set.
+ */
 export type GetEndpointDocDescription = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments of `getBasePath`, which returns the base path of a client. It has no properties, because the service is
+ * read from the generator context.
+ */
 export type GetBasePath = object;
+/**
+ * Arguments of `getEndpointPath`, which returns an endpoint path after `pathModifier` is applied.
+ * @property endpoint The endpoint whose path is modified.
+ */
 export type GetEndpointPath = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments of `getFilePath`, which returns the output file path of a client class.
+ * @property packageName The package of the client class, which becomes the directory below `outputDir`.
+ */
 export type GetFilePath = {
     packageName: string;
 };
+/**
+ * Arguments of `getApiClientName`, which returns the class name of a client. It has no properties.
+ */
 export type GetApiClientName = object;

package/dist/src/generators/services/okhttp3-clients/models.d.ts

@@ -4,15 +4,70 @@ import { type KotlinGeneratorConfig } from '../../../config.ts';
 import type { KotlinFileBuilder } from '../../../file-builder.ts';
 import type { KotlinModelsGeneratorOutput } from '../../models/index.ts';
 import type { getReferenceFactories } from './refs.ts';
+/**
+ * The configuration of the `KotlinOkHttp3ClientsGenerator`. It extends the common Kotlin generator configuration with
+ * the client-specific options declared below.
+ *
+ * Of the common options, `typeNameCasing` names the client classes, `functionNameCasing` names the endpoint methods,
+ * `parameterNameCasing` names their parameters, `includeSourceInDocs` adds the source path to the endpoint docs, and
+ * `springBootVersion` selects the Jackson packages in the infrastructure files.
+ * @see defaultKotlinOkHttp3ClientsGeneratorConfig
+ */
 export type KotlinOkHttp3ClientsGeneratorConfig = KotlinGeneratorConfig & {
+    /**
+     * The base package name for the generated client classes.
+     * Each client file is 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 appended to `packageName` for the generated client classes. Include the leading `.`, because the suffix
+     * is appended as written. A function receives the service and returns the suffix for it, so each service can be
+     * placed in its own package. The infrastructure package also uses the suffix when `infrastructurePackageName` is in
+     * `append-full-package-name` mode, and then the function is called without a service.
+     * @default '.api.client'
+     */
     packageSuffix: string | ((service?: ApiService) => string);
+    /**
+     * The package of the shared infrastructure files, such as `ApiClient`, `ApiResponse` and `Serializer`. The files are
+     * written to `{outputDir}/{infrastructurePackagePath}`, and the client classes refer to their types by this package.
+     * - A string is used as the package name as written.
+     * - `{ mode: 'append-package-name', value }` appends `value` to `packageName`.
+     * - `{ mode: 'append-full-package-name', value }` appends `value` to `packageName` followed by `packageSuffix`.
+     * - `{ mode: 'replace', value }` uses `value` as written.
+     * @default { mode: 'append-full-package-name', value: '.infrastructure' }
+     */
     infrastructurePackageName: string | {
         mode: 'append-package-name' | 'append-full-package-name' | 'replace';
         value: string;
     };
+    /**
+     * The base path that the generated clients use as the prefix of every request URL. It is the fallback of the
+     * `defaultBasePath` property in each client's companion object, which the system property named by
+     * `ApiClient.baseUrlKey` overrides at runtime.
+     * - A string replaces the base path as written.
+     * - A RegExp replaces the base path with the text it matches, and keeps the base path when nothing matches.
+     * - A function receives the base path and the service, and returns the new base path.
+     * @default The URL of the first server in the source OpenAPI document, or `'/'` when it defines none.
+     */
     basePath?: string | RegExp | ((basePath: string, service: ApiService) => string);
+    /**
+     * Changes the path of each endpoint before its request URL is built. The `{name}` placeholders of path parameters
+     * must remain in the modified path, because the path parameters are substituted into them afterwards.
+     * - A string replaces the path as written.
+     * - A RegExp replaces the path with the text it matches, and keeps the path when nothing matches.
+     * - A function receives the path and the endpoint, and returns the new path.
+     * @default undefined, so the endpoint path is used as written.
+     */
     pathModifier?: RegExp | ((path: string, endpoint: ApiEndpoint) => string);
+    /**
+     * The Jackson inclusion rule of the default `Serializer` object, which decides which null or empty values are left
+     * out of the serialized JSON. The value becomes a `JsonInclude.Include` constant in upper snake case, so
+     * `non-absent` becomes `NON_ABSENT`. It only applies to the default factory of a `'static'` serializer. It has no
+     * effect when `serializer` is `'parameter'`, or when it provides its own factory.
+     * @default 'non-absent'
+     */
     serializerJsonInclude: 'always' | 'non-null' | 'non-absent' | 'non-default' | 'non-empty' | 'use-defaults';
     /**
      * Determines how the serializer is provided to the client.
@@ -26,20 +81,48 @@ export type KotlinOkHttp3ClientsGeneratorConfig = KotlinGeneratorConfig & {
         factory: AppendValue<KotlinFileBuilder>;
     };
 };
+/**
+ * The default configuration of the `KotlinOkHttp3ClientsGenerator`. It is merged with the common Kotlin defaults from
+ * `defaultKotlinGeneratorConfig`, and the options passed to the generator are merged on top of these.
+ * @see KotlinOkHttp3ClientsGeneratorConfig
+ */
 export declare const defaultKotlinOkHttp3ClientsGeneratorConfig: DefaultGenerationProviderConfig<KotlinOkHttp3ClientsGeneratorConfig>;
+/**
+ * The input of the `KotlinOkHttp3ClientsGenerator`, which is the output of the `KotlinModelsGenerator`. The client
+ * methods use the model types it publishes under `kotlin.models` for their parameter and response types.
+ */
 export type KotlinOkHttp3ClientsGeneratorInput = KotlinModelsGeneratorOutput;
+/**
+ * The output of the `KotlinOkHttp3ClientsGenerator`. Later generators read the generated clients from `kotlin.clients`.
+ */
 export type KotlinOkHttp3ClientsGeneratorOutput = {
+    /** The Kotlin results of the generator. */
     kotlin: {
+        /** The generated client classes, keyed by service id. Each entry holds the type name and package of its client. */
         clients: {
             [serviceId: string]: KotlinOkHttp3ClientGeneratorOutput;
         };
     };
 };
+/**
+ * The result of generating the client for one service: the name and package of the generated client class. It is the
+ * entry stored under `kotlin.clients[serviceId]`.
+ */
 export type KotlinOkHttp3ClientGeneratorOutput = KotlinImport;
+/**
+ * The context of the `KotlinOkHttp3ClientsGenerator`. It extends the services generation context with the resolved
+ * infrastructure package name and the reference factories for the infrastructure types.
+ */
 export type KotlinOkHttp3ClientsGeneratorContext = OpenApiServicesGenerationProviderContext<KotlinOkHttp3ClientsGeneratorInput, KotlinOkHttp3ClientsGeneratorOutput, KotlinOkHttp3ClientsGeneratorConfig, KotlinOkHttp3ClientGeneratorOutput> & {
+    /** The package of the shared infrastructure files, resolved from `infrastructurePackageName`. */
     infrastructurePackageName: string;
+    /** The reference factories for the types in the infrastructure package, from `getReferenceFactories`. */
     refs: ReturnType<typeof getReferenceFactories>;
 };
+/**
+ * The context of the `DefaultKotlinOkHttp3Generator` for one service. It extends the clients context with the service.
+ */
 export type KotlinOkHttp3ClientGeneratorContext = KotlinOkHttp3ClientsGeneratorContext & {
+    /** The service to generate the client class for, with its endpoints. */
     service: ApiService;
 };

package/dist/src/generators/services/okhttp3-clients/models.js

@@ -1,4 +1,9 @@
 import { defaultKotlinGeneratorConfig } from '../../../config.js';
+/**
+ * The default configuration of the `KotlinOkHttp3ClientsGenerator`. It is merged with the common Kotlin defaults from
+ * `defaultKotlinGeneratorConfig`, and the options passed to the generator are merged on top of these.
+ * @see KotlinOkHttp3ClientsGeneratorConfig
+ */
 export const defaultKotlinOkHttp3ClientsGeneratorConfig = {
     ...defaultKotlinGeneratorConfig,
     packageName: 'com.openapi.generated',

package/dist/src/generators/services/okhttp3-clients/okhttp3-client-generator.d.ts

@@ -8,10 +8,43 @@ import type { KotlinOkHttp3ClientGeneratorContext, KotlinOkHttp3ClientGeneratorO
 type Context = KotlinOkHttp3ClientGeneratorContext;
 type Output = KotlinOkHttp3ClientGeneratorOutput;
 type Builder = KotlinFileBuilder;
+/**
+ * Generates the API client class of one service. Implement this interface to replace the default client generation,
+ * and pass the implementation to the `KotlinOkHttp3ClientsGenerator` constructor.
+ *
+ * @template TOutput The type of the result that the generation returns.
+ * @see DefaultKotlinOkHttp3Generator
+ */
 export interface KotlinOkHttp3Generator<TOutput extends Output = Output> {
+    /**
+     * Generates the client class for the service in `ctx.service`.
+     *
+     * @param ctx The context of the service, with its endpoints, the generator configuration and the reference factories.
+     * @returns The name and package of the generated client class.
+     */
     generate(ctx: Context): MaybePromise<TOutput>;
 }
+/**
+ * The default generator of a service's API client. It writes one Kotlin class to
+ * `{outputDir}/{packagePath}/{ClientName}.kt`, where `packagePath` is `packageName` followed by `packageSuffix`,
+ * with the dots replaced by slashes, and `ClientName` is the service name in `typeNameCasing` followed by `ApiClient`.
+ * With the default configuration, the service `pet` is written to
+ * `{outputDir}/com/openapi/generated/api/client/PetApiClient.kt`.
+ *
+ * The generated class extends `ApiClient`. For each endpoint it has the endpoint method, a `{name}WithHttpInfo`
+ * method that returns the whole `ApiResponse`, and a private `{name}RequestConfig` method that builds the request.
+ * It returns
+ * `{ typeName, packageName }`, which `KotlinOkHttp3ClientsGenerator` publishes under `kotlin.clients[serviceId]`.
+ *
+ * @see KotlinOkHttp3ClientsGenerator
+ */
 export declare class DefaultKotlinOkHttp3Generator extends KotlinFileGenerator<Context, Output> implements KotlinOkHttp3Generator {
+    /**
+     * Generates the client class file for the service in `ctx.service` and writes it to disk.
+     *
+     * @param ctx The context of the service to generate the client for.
+     * @returns The `typeName` and `packageName` of the generated client class.
+     */
     generate(ctx: KotlinOkHttp3ClientGeneratorContext): MaybePromise<Output>;
     protected getClientFileContent(ctx: Context, _args: Args.GetClientFileContent): AppendValueGroup<Builder>;
     /**

package/dist/src/generators/services/okhttp3-clients/okhttp3-client-generator.js

@@ -3,7 +3,27 @@ import { kt } from '../../../ast/index.js';
 import { KotlinFileBuilder } from '../../../file-builder.js';
 import { getArrayItemStringEnumSchema, getSourceDocLine, getStringEnumSchema, modifyString } from '../../../utils.js';
 import { KotlinFileGenerator } from '../../file-generator.js';
+/**
+ * The default generator of a service's API client. It writes one Kotlin class to
+ * `{outputDir}/{packagePath}/{ClientName}.kt`, where `packagePath` is `packageName` followed by `packageSuffix`,
+ * with the dots replaced by slashes, and `ClientName` is the service name in `typeNameCasing` followed by `ApiClient`.
+ * With the default configuration, the service `pet` is written to
+ * `{outputDir}/com/openapi/generated/api/client/PetApiClient.kt`.
+ *
+ * The generated class extends `ApiClient`. For each endpoint it has the endpoint method, a `{name}WithHttpInfo`
+ * method that returns the whole `ApiResponse`, and a private `{name}RequestConfig` method that builds the request.
+ * It returns
+ * `{ typeName, packageName }`, which `KotlinOkHttp3ClientsGenerator` publishes under `kotlin.clients[serviceId]`.
+ *
+ * @see KotlinOkHttp3ClientsGenerator
+ */
 export class DefaultKotlinOkHttp3Generator extends KotlinFileGenerator {
+    /**
+     * Generates the client class file for the service in `ctx.service` and writes it to disk.
+     *
+     * @param ctx The context of the service to generate the client for.
+     * @returns The `typeName` and `packageName` of the generated client class.
+     */
     generate(ctx) {
         const typeName = this.getApiClientName(ctx, {});
         const packageName = this.getPackageName(ctx, {});

package/dist/src/generators/services/okhttp3-clients/okhttp3-clients-generator.d.ts

@@ -7,8 +7,29 @@ type Output = KotlinOkHttp3ClientsGeneratorOutput;
 type Config = KotlinOkHttp3ClientsGeneratorConfig;
 type ServiceOutput = KotlinOkHttp3ClientGeneratorOutput;
 type Context = KotlinOkHttp3ClientsGeneratorContext;
+/**
+ * Generates the OkHttp3 client infrastructure and one API client class per service.
+ *
+ * These files are written to `{outputDir}/{infrastructurePackagePath}/`, where `infrastructurePackagePath` is
+ * `infrastructurePackageName` with the dots replaced by slashes:
+ * - `ApiAbstractions.kt`, `ApiClient.kt`, `ApiResponse.kt`, `Errors.kt`, `PartConfig.kt`, `RequestConfig.kt`,
+ *   `RequestMethod.kt` and `ResponseExtensions.kt`, copied from the bundled `client/okhttp3` assets with the package
+ *   name filled in. With `springBootVersion: 4`, their Jackson imports are rewritten to `tools.jackson`.
+ * - `Serializer.kt`, only when `serializer` is `'static'` or an object with `mode: 'static'`.
+ *
+ * Each service is generated by a `KotlinOkHttp3Generator`, which writes its client class to
+ * `{outputDir}/{packagePath}/{ClientName}.kt`. Services named `exclude-from-generation` are skipped. The result of each
+ * service is published under `kotlin.clients[serviceId]` as `{ typeName, packageName }`.
+ *
+ * @see DefaultKotlinOkHttp3Generator
+ */
 export declare class KotlinOkHttp3ClientsGenerator extends OpenApiServicesGenerationProviderBase<Input, Output, Config, ServiceOutput, Context> {
     private readonly _serviceGeneratorFactory;
+    /**
+     * Creates the generator.
+     *
+     * @param serviceGeneratorFactory Creates the generator for each service. Defaults to the default generator.
+     */
     constructor(serviceGeneratorFactory?: Factory<KotlinOkHttp3Generator, []>);
     protected generateAdditionalFiles(ctx: KotlinOkHttp3ClientsGeneratorContext): Promise<void>;
     protected initResult(): Output;

package/dist/src/generators/services/okhttp3-clients/okhttp3-clients-generator.js

@@ -6,8 +6,29 @@ import { KotlinFileBuilder } from '../../../file-builder.js';
 import { defaultKotlinOkHttp3ClientsGeneratorConfig, } from './models.js';
 import { DefaultKotlinOkHttp3Generator } from './okhttp3-client-generator.js';
 import { getReferenceFactories } from './refs.js';
+/**
+ * Generates the OkHttp3 client infrastructure and one API client class per service.
+ *
+ * These files are written to `{outputDir}/{infrastructurePackagePath}/`, where `infrastructurePackagePath` is
+ * `infrastructurePackageName` with the dots replaced by slashes:
+ * - `ApiAbstractions.kt`, `ApiClient.kt`, `ApiResponse.kt`, `Errors.kt`, `PartConfig.kt`, `RequestConfig.kt`,
+ *   `RequestMethod.kt` and `ResponseExtensions.kt`, copied from the bundled `client/okhttp3` assets with the package
+ *   name filled in. With `springBootVersion: 4`, their Jackson imports are rewritten to `tools.jackson`.
+ * - `Serializer.kt`, only when `serializer` is `'static'` or an object with `mode: 'static'`.
+ *
+ * Each service is generated by a `KotlinOkHttp3Generator`, which writes its client class to
+ * `{outputDir}/{packagePath}/{ClientName}.kt`. Services named `exclude-from-generation` are skipped. The result of each
+ * service is published under `kotlin.clients[serviceId]` as `{ typeName, packageName }`.
+ *
+ * @see DefaultKotlinOkHttp3Generator
+ */
 export class KotlinOkHttp3ClientsGenerator extends OpenApiServicesGenerationProviderBase {
     _serviceGeneratorFactory;
+    /**
+     * Creates the generator.
+     *
+     * @param serviceGeneratorFactory Creates the generator for each service. Defaults to the default generator.
+     */
     constructor(serviceGeneratorFactory) {
         super();
         this._serviceGeneratorFactory = serviceGeneratorFactory ?? Factory.fromValue(new DefaultKotlinOkHttp3Generator());

package/dist/src/generators/services/okhttp3-clients/refs.d.ts

@@ -1,21 +1,46 @@
 import { kt } from '../../../ast/index.ts';
+/**
+ * Creates the reference factories for the types of the OkHttp3 client infrastructure. Each factory writes a reference
+ * to a type in the infrastructure package, so the generated clients import the types from there.
+ *
+ * @param infrastructurePackageName The package that the infrastructure files are written to.
+ * @returns The reference factories, keyed by the name of the type they refer to.
+ */
 export declare function getReferenceFactories(infrastructurePackageName: string): {
+    /** The `MultiValueMap` type alias for query and header values. Declared in `ApiAbstractions.kt`. */
     multiValueMap: kt.ReferenceFactory;
+    /** The `collectionDelimiter` function, which returns the separator of a collection format. `ApiAbstractions.kt`. */
     collectionDelimiter: kt.ReferenceFactory;
+    /** The `defaultMultiValueConverter` value, which converts an item to a string. Declared in `ApiAbstractions.kt`. */
     defaultMultiValueConverter: kt.ReferenceFactory;
+    /** The `toMultiValueMap` function. The generator does not use it, and no bundled asset declares it. */
     toMultiValueMap: kt.GenericReferenceFactory<1>;
+    /** The `ApiClient` base class that every generated client extends. Declared in `ApiClient.kt`. */
     apiClient: kt.ReferenceFactory;
+    /** The `ResponseType` enum that tells the response kinds apart. Declared in `ApiResponse.kt`. */
     responseType: kt.ReferenceFactory;
+    /** The generic `ApiResponse<T>` base class of every response. Declared in `ApiResponse.kt`. */
     apiResponse: kt.GenericReferenceFactory<1>;
+    /** The generic `Success<T>` response, which holds the response data. Declared in `ApiResponse.kt`. */
     success: kt.GenericReferenceFactory<1>;
+    /** The generic `Informational<T>` response. Declared in `ApiResponse.kt`. */
     informational: kt.GenericReferenceFactory<1>;
+    /** The generic `Redirection<T>` response. Declared in `ApiResponse.kt`. */
     redirection: kt.GenericReferenceFactory<1>;
+    /** The generic `ClientError<T>` response for 4xx status codes. Declared in `ApiResponse.kt`. */
     clientError: kt.GenericReferenceFactory<1>;
+    /** The generic `ServerError<T>` response for 5xx status codes. Declared in `ApiResponse.kt`. */
     serverError: kt.GenericReferenceFactory<1>;
+    /** The `ClientException` thrown for client error responses. Declared in `Errors.kt`. */
     clientException: kt.ReferenceFactory;
+    /** The `ServerException` thrown for server error responses. Declared in `Errors.kt`. */
     serverException: kt.ReferenceFactory;
+    /** The generic `PartConfig<T>` of one part of a multipart request. Declared in `PartConfig.kt`. */
     partConfig: kt.GenericReferenceFactory<1>;
+    /** The generic `RequestConfig<T>` that describes one request. Declared in `RequestConfig.kt`. */
     requestConfig: kt.GenericReferenceFactory<1>;
+    /** The `RequestMethod` enum of HTTP methods. Declared in `RequestMethod.kt`. */
     requestMethod: kt.ReferenceFactory;
+    /** The `Serializer` object with the default object mapper. It is generated only for a `'static'` serializer. */
     serializer: kt.ReferenceFactory;
 };

package/dist/src/generators/services/okhttp3-clients/refs.js

@@ -1,5 +1,12 @@
 import { kt } from '../../../ast/index.js';
 // See packages/kotlin/assets/client/okhttp3 for reference
+/**
+ * Creates the reference factories for the types of the OkHttp3 client infrastructure. Each factory writes a reference
+ * to a type in the infrastructure package, so the generated clients import the types from there.
+ *
+ * @param infrastructurePackageName The package that the infrastructure files are written to.
+ * @returns The reference factories, keyed by the name of the type they refer to.
+ */
 export function getReferenceFactories(infrastructurePackageName) {
     return {
         // ApiAbstractions.kt