From ba2cb3269045454c2766dec6d3160bdbcc272949 Mon Sep 17 00:00:00 2001 From: Dereck Tu Date: Fri, 16 Jan 2026 13:22:37 -0500 Subject: [PATCH] feat: remove @preserveLineBreaks tag Ticket: DX-2755 This commit removes the support for the @preserveLineBreaks tag. We will no longer support this tag as line breaks are now preserved by default BREAKING CHANGE: `@preserveLineBreaks` is no longer a supported tag. Formatting preservation is now the default behavior, rendering the `@preserveLineBreaks` tag obsolete. Please remove usages of `@preserveLineBreaks` in your JSDoc comments --- packages/openapi-generator/README.md | 13 -- packages/openapi-generator/src/comments.ts | 7 - .../test/openapi/comments.test.ts | 156 ------------------ 3 files changed, 176 deletions(-) diff --git a/packages/openapi-generator/README.md b/packages/openapi-generator/README.md index 711df2bc..2038b449 100644 --- a/packages/openapi-generator/README.md +++ b/packages/openapi-generator/README.md @@ -472,9 +472,6 @@ These are some tags that you can use in your schema JSDocs are custom to this ge will have `x-internal: true` for schemas with the `@private` tag. - `@deprecated` allows to mark any field in any schema as deprecated. The final spec will include `deprecated: true` in the final specificaiton. -- `@preserveLineBreaks` preserves line breaks in descriptions. By default, multiline - descriptions are collapsed into a single line. Use this tag when you need to preserve - formatting, such as for markdown lists or structured text. ```typescript import * as t from 'io-ts'; @@ -485,16 +482,6 @@ const Schema = t.type({ /** @deprecated */ deprecatedField: t.string, publicNonDeprecatedField: t.string, - /** - * @preserveLineBreaks - * This description spans multiple lines - * and will preserve its line breaks. - * - * Available options: - * - `option1` - First option - * - `option2` - Second option - */ - fieldWithFormattedDescription: t.string, }); ``` diff --git a/packages/openapi-generator/src/comments.ts b/packages/openapi-generator/src/comments.ts index 36879f2d..7c684720 100644 --- a/packages/openapi-generator/src/comments.ts +++ b/packages/openapi-generator/src/comments.ts @@ -70,13 +70,6 @@ export function leadingComment( } } - const shouldPreserveLineBreaks = commentString.includes('@preserveLineBreaks'); - if (shouldPreserveLineBreaks) { - // This handles both inline and separate line cases - commentString = commentString.replace(/^\s*\*\s*@preserveLineBreaks\s*$/gm, ''); - commentString = commentString.replace(/@preserveLineBreaks\s*/g, ''); - } - const parsedComment = parseComment(commentString, { spacing: 'preserve' }); for (const block of parsedComment) { diff --git a/packages/openapi-generator/test/openapi/comments.test.ts b/packages/openapi-generator/test/openapi/comments.test.ts index 4b461a5f..710cd316 100644 --- a/packages/openapi-generator/test/openapi/comments.test.ts +++ b/packages/openapi-generator/test/openapi/comments.test.ts @@ -1658,162 +1658,6 @@ testCase( }, ); -const ROUTE_WITH_MARKDOWN_LIST_AND_PRESERVE_LINE_BREAKS = ` -import * as t from 'io-ts'; -import * as h from '@api-ts/io-ts-http'; - -/** - * A route with a list in the comment - * - * @operationId api.v1.list - * @tag Test Routes - */ -export const route = h.httpRoute({ - path: '/list', - method: 'GET', - request: h.httpRequest({ - query: { - /** - * @preserveLineBreaks - * The permissions granted by this access token. - * - * - \`all\` - Access all actions in the test environment. - * - \`crypto_compare\` - Call CryptoCompare API. - */ - permissions: t.string, - }, - }), - response: { - 200: t.string - }, -}); -`; - -testCase( - 'route with markdown list in comment and @preserveLineBreaks tag', - ROUTE_WITH_MARKDOWN_LIST_AND_PRESERVE_LINE_BREAKS, - { - openapi: '3.0.3', - info: { - title: 'Test', - version: '1.0.0', - }, - paths: { - '/list': { - get: { - summary: 'A route with a list in the comment', - operationId: 'api.v1.list', - tags: ['Test Routes'], - parameters: [ - { - name: 'permissions', - in: 'query', - required: true, - schema: { - type: 'string', - }, - description: - 'The permissions granted by this access token.\n\n- `all` - Access all actions in the test environment.\n- `crypto_compare` - Call CryptoCompare API.', - }, - ], - responses: { - 200: { - description: 'OK', - content: { - 'application/json': { - schema: { - type: 'string', - }, - }, - }, - }, - }, - }, - }, - }, - components: { - schemas: {}, - }, - }, -); - -const ROUTE_WITH_INLINE_PRESERVE_LINE_BREAKS = ` -import * as t from 'io-ts'; -import * as h from '@api-ts/io-ts-http'; - -/** - * A route with inline preserveLineBreaks tag - * - * @operationId api.v1.inline - * @tag Test Routes - */ -export const route = h.httpRoute({ - path: '/inline', - method: 'GET', - request: h.httpRequest({ - query: { - /** - * @preserveLineBreaks This tag is inline with other text - * This is a long description that - * spans multiple lines in the source. - */ - field1: t.string, - }, - }), - response: { - 200: t.string - }, -}); -`; - -testCase( - 'route with inline @preserveLineBreaks tag', - ROUTE_WITH_INLINE_PRESERVE_LINE_BREAKS, - { - openapi: '3.0.3', - info: { - title: 'Test', - version: '1.0.0', - }, - paths: { - '/inline': { - get: { - summary: 'A route with inline preserveLineBreaks tag', - operationId: 'api.v1.inline', - tags: ['Test Routes'], - parameters: [ - { - name: 'field1', - in: 'query', - required: true, - schema: { - type: 'string', - }, - description: - 'This tag is inline with other text\nThis is a long description that\nspans multiple lines in the source.', - }, - ], - responses: { - 200: { - description: 'OK', - content: { - 'application/json': { - schema: { - type: 'string', - }, - }, - }, - }, - }, - }, - }, - }, - components: { - schemas: {}, - }, - }, -); - const ROUTE_WITH_ENUM_DEPRECATED = ` import * as t from 'io-ts'; import * as h from '@api-ts/io-ts-http';