@goast/kotlin 0.5.5 → 0.5.7

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

@@ -3,10 +3,12 @@ import {
   type ApiSchema,
   type AppendValueGroup,
   appendValueGroup,
+  type BasicAppendValue,
   builderTemplate as s,
   createOverwriteProxy,
   getSourceDisplayName,
   type MaybePromise,
+  notNullish,
   resolveAnyOfAndAllOf,
   SourceBuilder,
   toCasing,
@@ -16,7 +18,7 @@ import { kt } from '../../../ast/index.js';
 import type { KtValue } from '../../../ast/nodes/types.js';
 import { KotlinFileBuilder } from '../../../file-builder.js';
 import type { ApiParameterWithMultipartInfo } from '../../../types.js';
-import { modifyString } from '../../../utils.js';
+import { getSourceDocLine, modifyString } from '../../../utils.js';
 import { KotlinFileGenerator } from '../../file-generator.js';
 import type { DefaultKotlinOkHttp3GeneratorArgs as Args } from './index.js';
 import type { KotlinOkHttp3ClientGeneratorContext, KotlinOkHttp3ClientGeneratorOutput } from './models.js';
@@ -126,7 +128,7 @@ export class DefaultKotlinOkHttp3Generator extends KotlinFileGenerator<Context,
     const { endpoint, parameters, responseSchema } = args;
 
     return kt.function(toCasing(endpoint.name, ctx.config.functionNameCasing), {
-      doc: kt.doc(endpoint.summary, [
+      doc: kt.doc(this.getEndpointDocDescription(ctx, { endpoint }), [
         kt.docTag('throws', 'IllegalStateException', 'If the request is not correctly configured'),
         kt.docTag('throws', 'IOException', 'Rethrows the OkHttp execute method exception'),
         kt.docTag(
@@ -219,7 +221,7 @@ export class DefaultKotlinOkHttp3Generator extends KotlinFileGenerator<Context,
     const { endpoint, parameters, responseSchema } = args;
 
     return kt.function(toCasing(args.endpoint.name, ctx.config.functionNameCasing) + 'WithHttpInfo', {
-      doc: kt.doc(endpoint.summary, [
+      doc: kt.doc(this.getEndpointDocDescription(ctx, { endpoint }), [
         kt.docTag('throws', 'IllegalStateException', 'If the request is not correctly configured'),
         kt.docTag('throws', 'IOException', 'Rethrows the OkHttp execute method exception'),
       ]),
@@ -556,6 +558,16 @@ export class DefaultKotlinOkHttp3Generator extends KotlinFileGenerator<Context,
     );
   }
 
+  protected getEndpointDocDescription(ctx: Context, args: Args.GetEndpointDocDescription): BasicAppendValue<Builder> {
+    const docSegments = [args.endpoint.description?.trim()];
+
+    if (ctx.config.includeSourceInDocs) {
+      docSegments.push(getSourceDocLine(args.endpoint));
+    }
+
+    return docSegments.filter(notNullish).join('\n\n');
+  }
+
   protected getBasePath(ctx: Context, _args: Args.GetBasePath): string {
     return modifyString(
       (ctx.service.$src ?? ctx.service.endpoints[0]?.$src)?.document.servers?.[0]?.url ?? '/',

package/src/src/generators/services/spring-controllers/args.ts

@@ -68,6 +68,8 @@ export type GetTypeUsage<TBuilder extends SourceBuilder> = {
   type?: kt.Reference<TBuilder>;
 };
 
+export type GetEndpointDocDescription = { endpoint: ApiEndpoint };
+
 export type GetSchemaType = { schema: ApiSchema | undefined };
 
 export type GetControllerRequestMapping = { prefix?: string };

package/src/src/generators/services/spring-controllers/spring-controller-generator.ts

@@ -3,6 +3,7 @@ import {
   type ApiParameter,
   type AppendValueGroup,
   appendValueGroup,
+  type BasicAppendValue,
   builderTemplate as s,
   createOverwriteProxy,
   getSourceDisplayName,
@@ -18,7 +19,7 @@ import { kt } from '../../../ast/index.js';
 import type { KotlinImport } from '../../../common-results.js';
 import { KotlinFileBuilder } from '../../../file-builder.js';
 import type { ApiParameterWithMultipartInfo } from '../../../types.js';
-import { modifyString } from '../../../utils.js';
+import { getSourceDocLine, modifyString } from '../../../utils.js';
 import { KotlinFileGenerator } from '../../file-generator.js';
 import type { DefaultKotlinSpringControllerGeneratorArgs as Args } from './index.js';
 import type { KotlinServiceGeneratorContext, KotlinServiceGeneratorOutput } from './models.js';
@@ -163,6 +164,7 @@ export class DefaultKotlinSpringControllerGenerator extends KotlinFileGenerator<
     const parameters = this.getAllParameters(ctx, { endpoint });
 
     return kt.function(toCasing(endpoint.name, ctx.config.functionNameCasing), {
+      doc: kt.doc(this.getEndpointDocDescription(ctx, { endpoint })),
       suspend: ctx.config.suspendingFunctions,
       annotations: this.getApiInterfaceEndpointMethodAnnnotations(
         ctx,
@@ -789,6 +791,7 @@ export class DefaultKotlinSpringControllerGenerator extends KotlinFileGenerator<
     const fn = kt.function<Builder>(
       toCasing(endpoint.name, ctx.config.functionNameCasing),
       {
+        doc: kt.doc(this.getEndpointDocDescription(ctx, { endpoint })),
         suspend: ctx.config.suspendingFunctions,
         parameters: parameters.map((parameter) => {
           return kt.parameter(
@@ -906,6 +909,16 @@ export class DefaultKotlinSpringControllerGenerator extends KotlinFileGenerator<
     return schema && ctx.input.kotlin.models[schema.id].type;
   }
 
+  protected getEndpointDocDescription(ctx: Context, args: Args.GetEndpointDocDescription): BasicAppendValue<Builder> {
+    const docSegments = [args.endpoint.description?.trim()];
+
+    if (ctx.config.includeSourceInDocs) {
+      docSegments.push(getSourceDocLine(args.endpoint));
+    }
+
+    return docSegments.filter(notNullish).join('\n\n');
+  }
+
   protected getControllerRequestMapping(
     ctx: Context,
     args: Args.GetControllerRequestMapping,

package/src/src/generators/services/spring-reactive-web-clients/args.ts

@@ -92,6 +92,8 @@ export type GetAllParameters = { endpoint: ApiEndpoint };
 
 export type GetRequestBodyParamName = { endpoint: ApiEndpoint };
 
+export type GetEndpointDocDescription = { endpoint: ApiEndpoint };
+
 export type GetBasePath = object;
 
 export type GetEndpointPath = { endpoint: ApiEndpoint };

package/src/src/generators/services/spring-reactive-web-clients/spring-reactive-web-client-generator.ts

@@ -3,10 +3,12 @@ import {
   type ApiSchema,
   type AppendValueGroup,
   appendValueGroup,
+  type BasicAppendValue,
   builderTemplate as s,
   createOverwriteProxy,
   getSourceDisplayName,
   type MaybePromise,
+  notNullish,
   resolveAnyOfAndAllOf,
   SourceBuilder,
   toCasing,
@@ -16,7 +18,7 @@ import { kt } from '../../../ast/index.js';
 import type { KtValue } from '../../../ast/nodes/types.js';
 import { KotlinFileBuilder } from '../../../file-builder.js';
 import type { ApiParameterWithMultipartInfo } from '../../../types.js';
-import { modifyString } from '../../../utils.js';
+import { getSourceDocLine, modifyString } from '../../../utils.js';
 import { KotlinFileGenerator } from '../../file-generator.js';
 import type { DefaultKotlinSpringReactiveWebClientGeneratorArgs as Args } from './index.js';
 import type {
@@ -90,7 +92,7 @@ export class DefaultKotlinSpringReactiveWebClientGenerator extends KotlinFileGen
     const functionName = this.getEndpointFunctionName(ctx, { endpoint });
 
     return kt.function(functionName, {
-      doc: kt.doc(endpoint.description),
+      doc: kt.doc(this.getEndpointDocDescription(ctx, { endpoint })),
       suspend: true,
       receiverType: kt.refs.springReactive.webClient(),
       parameters: parameters.map((parameter) =>
@@ -142,7 +144,7 @@ export class DefaultKotlinSpringReactiveWebClientGenerator extends KotlinFileGen
     const functionName = this.getEndpointFunctionName(ctx, { endpoint });
 
     return kt.function(functionName, {
-      doc: kt.doc(endpoint.description),
+      doc: kt.doc(this.getEndpointDocDescription(ctx, { endpoint })),
       suspend: true,
       generics: [kt.genericParameter('T')],
       receiverType: kt.refs.springReactive.webClient(),
@@ -201,7 +203,7 @@ export class DefaultKotlinSpringReactiveWebClientGenerator extends KotlinFileGen
     const functionName = this.getEndpointRequestFunctionName(ctx, { endpoint });
 
     return kt.function(functionName, {
-      doc: kt.doc(endpoint.description),
+      doc: kt.doc(this.getEndpointDocDescription(ctx, { endpoint })),
       receiverType: kt.refs.springReactive.webClient(),
       parameters: parameters.map((parameter) =>
         kt.parameter(
@@ -529,6 +531,16 @@ export class DefaultKotlinSpringReactiveWebClientGenerator extends KotlinFileGen
     );
   }
 
+  protected getEndpointDocDescription(ctx: Context, args: Args.GetEndpointDocDescription): BasicAppendValue<Builder> {
+    const docSegments = [args.endpoint.description?.trim()];
+
+    if (ctx.config.includeSourceInDocs) {
+      docSegments.push(getSourceDocLine(args.endpoint));
+    }
+
+    return docSegments.filter(notNullish).join('\n\n');
+  }
+
   protected getBasePath(ctx: Context, _args: Args.GetBasePath): string {
     return modifyString(
       (ctx.service.$src ?? ctx.service.endpoints[0]?.$src)?.document.servers?.[0]?.url ?? '/',

package/src/src/utils.ts

@@ -1,4 +1,6 @@
-import type { Nullable } from '@goast/core';
+import type { ApiComponent, Nullable } from '@goast/core';
+import path from 'node:path';
+import process from 'node:process';
 
 export function toKotlinStringLiteral(value: Nullable<string>): string {
   if (!value) {
@@ -37,3 +39,9 @@ export function modifyString<TArgs extends unknown[]>(
   }
   return value;
 }
+
+export function getSourceDocLine<T>(component: ApiComponent<T>): string {
+  const file = path.relative(process.cwd(), component.$src.file).replace(/\\/g, '/');
+  const { line, col } = component.$src.pos;
+  return `Source: ${file}:${line}:${col} (${component.$src.path})`;
+}