diff --git a/README.md b/README.md index 1cd33d0..ab55c9f 100755 --- a/README.md +++ b/README.md @@ -182,21 +182,21 @@ Description is formatting as Markdown, so you could use any features of Markdown ## Options -| Key | type | Default | description | -| :-------------------------------- | :------ | :-------- | ----------------------------------------------------------------------------------------- | -| jsdocSpaces | Number | 1 | -| jsdocDescriptionWithDot | Boolean | false | -| jsdocDescriptionTag | Boolean | false | -| jsdocVerticalAlignment | Boolean | false | -| jsdocKeepUnParseAbleExampleIndent | Boolean | false | -| jsdocSingleLineComment | Boolean | true | -| jsdocCapitalizeDescription | Boolean | true | -| jsdocSeparateReturnsFromParam | Boolean | false | Add an space between last @param and @returns | -| jsdocSeparateTagGroups | Boolean | false | Add an space between tag groups | -| jsdocPreferCodeFences | Boolean | false | Always fence code blocks (surround them by triple backticks) | -| tsdoc | Boolean | false | -| jsdocPrintWidth | Number | undefined | If You don't set value to jsdocPrintWidth, the printWidth will be use as jsdocPrintWidth. | -| jsdocLineWrappingStyle | String | "greedy" | "greedy": Lines wrap as soon as they reach the print width | +| Key | type | Default | description | +| :-------------------------------- | :-------------------------------- | :-------- | ----------------------------------------------------------------------------------------- | +| jsdocSpaces | Number | 1 | +| jsdocDescriptionWithDot | Boolean | false | +| jsdocDescriptionTag | Boolean | false | +| jsdocVerticalAlignment | Boolean | false | +| jsdocKeepUnParseAbleExampleIndent | Boolean | false | +| jsdocCommentLineStrategy | ("singleLine","multiline","keep") | true | +| jsdocCapitalizeDescription | Boolean | true | +| jsdocSeparateReturnsFromParam | Boolean | false | Add an space between last @param and @returns | +| jsdocSeparateTagGroups | Boolean | false | Add an space between tag groups | +| jsdocPreferCodeFences | Boolean | false | Always fence code blocks (surround them by triple backticks) | +| tsdoc | Boolean | false | +| jsdocPrintWidth | Number | undefined | If You don't set value to jsdocPrintWidth, the printWidth will be use as jsdocPrintWidth. | +| jsdocLineWrappingStyle | String | "greedy" | "greedy": Lines wrap as soon as they reach the print width | Full up to date list and description of options can be found in Prettier help. First install plugin then run Prettier with "--help" option. diff --git a/src/index.ts b/src/index.ts index c66c601..08973fd 100755 --- a/src/index.ts +++ b/src/index.ts @@ -6,14 +6,7 @@ import prettier, { SupportOption } from "prettier"; import { JsdocOptions } from "./types.js"; import { findPluginByParser } from "./utils.js"; -const options: Record = { - jsdocParser: { - name: "jsdocParser", - type: "boolean", - category: "jsdoc", - default: true, - description: "Enable/Disable jsdoc parser", - }, +const options = { jsdocSpaces: { name: "jsdocSpaces", type: "int", @@ -54,9 +47,34 @@ const options: Record = { name: "jsdocSingleLineComment", type: "boolean", category: "jsdoc", + deprecated: "use jsdocCommentLineStrategy instead will be remove on v2", default: true, description: "Should compact single line comment", }, + jsdocCommentLineStrategy: { + name: "jsdocCommentLineStrategy", + type: "choice", + choices: [ + { + since: "1.1.0", + value: "singleLine", + description: `Should compact single line comment, if possible`, + }, + { + since: "1.1.0", + value: "multiline", + description: `Should compact multi line comment`, + }, + { + since: "1.1.0", + value: "keep", + description: `Should keep original line comment`, + }, + ], + category: "jsdoc", + default: "singleLine", + description: "How comments line should be", + }, jsdocSeparateReturnsFromParam: { name: "jsdocSeparateReturnsFromParam", type: "boolean", @@ -121,10 +139,9 @@ const options: Record = { default: "greedy", description: `Strategy for wrapping lines for the given print width. More options may be added in the future.`, }, -}; +} satisfies Record; const defaultOptions: JsdocOptions = { - jsdocParser: options.jsdocParser.default as boolean, jsdocSpaces: options.jsdocSpaces.default as number, jsdocPrintWidth: options.jsdocPrintWidth.default as unknown as undefined, jsdocDescriptionWithDot: options.jsdocDescriptionWithDot.default as boolean, @@ -133,6 +150,8 @@ const defaultOptions: JsdocOptions = { jsdocKeepUnParseAbleExampleIndent: options.jsdocKeepUnParseAbleExampleIndent .default as boolean, jsdocSingleLineComment: options.jsdocSingleLineComment.default as boolean, + jsdocCommentLineStrategy: options.jsdocCommentLineStrategy + .default as "singleLine", jsdocSeparateReturnsFromParam: options.jsdocSeparateReturnsFromParam .default as boolean, jsdocSeparateTagGroups: options.jsdocSeparateTagGroups.default as boolean, @@ -183,6 +202,7 @@ function mergeParsers(originalParser: prettier.Parser, parserName: string) { const jsDocParse = getParser(originalParser.parse, parserName) as any; const jsDocPreprocess = (text: string, options: prettier.ParserOptions) => { + normalizeOptions(options as any); const tsPluginParser = findPluginByParser(parserName, options); if (!tsPluginParser) { @@ -213,3 +233,14 @@ function mergeParsers(originalParser: prettier.Parser, parserName: string) { } export { options, parsers, defaultOptions }; + +function normalizeOptions(options: prettier.ParserOptions & JsdocOptions) { + if (options.jsdocCommentLineStrategy) { + return; + } + if (options.jsdocSingleLineComment) { + options.jsdocCommentLineStrategy = "singleLine"; + } else { + options.jsdocCommentLineStrategy = "multiline"; + } +} diff --git a/src/parser.ts b/src/parser.ts index 58917b3..06df736 100755 --- a/src/parser.ts +++ b/src/parser.ts @@ -44,10 +44,6 @@ export const getParser = (originalParse: Parser["parse"], parserName: string) => const ast = prettierParse(text, options) as AST; - // jsdocParser is deprecated,this is backward compatible will be remove - if ((options as any).jsdocParser === false) { - return ast; - } options = { ...options, printWidth: options.jsdocPrintWidth ?? options.printWidth, @@ -62,10 +58,10 @@ export const getParser = (originalParse: Parser["parse"], parserName: string) => if (!isBlockComment(comment)) return; const tokenIndex = findTokenIndex(ast.tokens, comment); const paramsOrder = getParamsOrders(ast, tokenIndex); + const originalValue = comment.value; /** Issue: https://github.com/hosseinmd/prettier-plugin-jsdoc/issues/18 */ comment.value = comment.value.replace(/^([*]+)/g, "*"); - // Create the full comment string with line ends normalized to \n // This means that all following code can assume \n and should only use // \n. @@ -232,6 +228,7 @@ export const getParser = (originalParse: Parser["parse"], parserName: string) => if (comment.value) { comment.value = addStarsToTheBeginningOfTheLines( + originalValue, comment.value, options, ); diff --git a/src/types.ts b/src/types.ts index ad65338..c371465 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,15 +1,19 @@ import { ParserOptions } from "prettier"; export interface JsdocOptions { - jsdocParser: boolean; jsdocSpaces: number; jsdocPrintWidth?: number; jsdocDescriptionWithDot: boolean; jsdocDescriptionTag: boolean; jsdocVerticalAlignment: boolean; jsdocKeepUnParseAbleExampleIndent: boolean; - /** default is true */ + /** + * @deprecated use jsdocCommentLineStrategy instead + * @default true + */ jsdocSingleLineComment: boolean; + /** @default "singleLine" */ + jsdocCommentLineStrategy: "singleLine" | "multiline" | "keep"; jsdocSeparateReturnsFromParam: boolean; jsdocSeparateTagGroups: boolean; jsdocAddDefaultToDescription: boolean; diff --git a/src/utils.ts b/src/utils.ts index 6666bf1..413f22c 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -127,12 +127,15 @@ async function formatType(type: string, options?: Options): Promise { } function addStarsToTheBeginningOfTheLines( + originalComment: string, comment: string, options: AllOptions, ): string { if ( - options.jsdocSingleLineComment && - numberOfAStringInString(comment.trim(), "\n") === 0 + (options.jsdocCommentLineStrategy === "singleLine" && + numberOfAStringInString(comment.trim(), "\n") === 0) || + (options.jsdocCommentLineStrategy === "keep" && + numberOfAStringInString(originalComment, "\n") === 0) ) { return `* ${comment.trim()} `; } diff --git a/tests/__snapshots__/singleTag.test.ts.snap b/tests/__snapshots__/singleTag.test.ts.snap index be40ad4..893b781 100644 --- a/tests/__snapshots__/singleTag.test.ts.snap +++ b/tests/__snapshots__/singleTag.test.ts.snap @@ -1,5 +1,41 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP +exports[`Comment Line Strategy keep multi 1`] = ` +"/** + * @type {import("eslint").Linter.Config} should Be multiline + */ +const config = { + // ... +}; +" +`; + +exports[`Comment Line Strategy keep single 1`] = ` +"/** @type {import("eslint").Linter.Config} should Be single line */ +const config = { + // ... +}; +" +`; + +exports[`Comment Line Strategy multiline 1`] = ` +"/** + * @type {import("eslint").Linter.Config} should Be multiline + */ +const config = { + // ... +}; +" +`; + +exports[`Comment Line Strategy singleLine 1`] = ` +"/** @type {import("eslint").Linter.Config} should Be single */ +const config = { + // ... +}; +" +`; + exports[`single tag 1`] = ` "/** @param {string} param0 Description */ function fun(param0) {} diff --git a/tests/descriptions.test.ts b/tests/descriptions.test.ts index 69a8b6e..197cdb3 100644 --- a/tests/descriptions.test.ts +++ b/tests/descriptions.test.ts @@ -677,7 +677,7 @@ test("Long words", async () => { */ `, { - jsdocSingleLineComment: false, + jsdocCommentLineStrategy: "multiline", }, ); diff --git a/tests/jsdocParserDisable.test.ts b/tests/jsdocParserDisable.test.ts index 8c04633..1b4da18 100644 --- a/tests/jsdocParserDisable.test.ts +++ b/tests/jsdocParserDisable.test.ts @@ -49,8 +49,7 @@ test("disabled complex object typedef ", async () => { export class BreadCrumbs extends PureComponent {} `, { - plugins: ["prettier-plugin-jsdoc"], - jsdocParser: false, + plugins: [], }, ); diff --git a/tests/main.test.ts b/tests/main.test.ts index def03d4..94e045c 100755 --- a/tests/main.test.ts +++ b/tests/main.test.ts @@ -104,7 +104,7 @@ test("Should convert to single line if necessary", async () => { test("Should convert to single multiLine", async () => { const Result1 = await subject(`/** single line description*/`, { - jsdocSingleLineComment: false, + jsdocCommentLineStrategy: "multiline", }); const Result2 = await subject( await subject(`/** @@ -112,7 +112,7 @@ test("Should convert to single multiLine", async () => { * @example */`), { - jsdocSingleLineComment: false, + jsdocCommentLineStrategy: "multiline", }, ); @@ -769,7 +769,7 @@ import { something } from './index'; `, { jsdocDescriptionWithDot: true, - jsdocSingleLineComment: false, + jsdocCommentLineStrategy: "multiline", jsdocSeparateTagGroups: true, jsdocPreferCodeFences: true, tsdoc: true, diff --git a/tests/singleTag.test.ts b/tests/singleTag.test.ts index 3620121..b068e27 100644 --- a/tests/singleTag.test.ts +++ b/tests/singleTag.test.ts @@ -29,3 +29,68 @@ function fun(param0){} expect(result).toMatchSnapshot(); }); + +describe("Comment Line Strategy", () => { + test("keep single", async () => { + const result = await subject( + ` + /** @type {import('eslint').Linter.Config} should be single line */ + const config = { + // ... + }; +`, + { + jsdocCommentLineStrategy: "keep", + }, + ); + expect(result).toMatchSnapshot(); + }); + + test("keep multi", async () => { + const result1 = await subject( + ` + /** + * @type {import('eslint').Linter.Config} should be multiline + */ + const config = { + // ... + }; +`, + { + jsdocCommentLineStrategy: "keep", + }, + ); + + expect(result1).toMatchSnapshot(); + }); + test("singleLine ", async () => { + const result2 = await subject( + ` + /** + * @type {import('eslint').Linter.Config} should be single + */ + const config = { + // ... + }; +`, + { + jsdocCommentLineStrategy: "singleLine", + }, + ); + expect(result2).toMatchSnapshot(); + }); + test("multiline ", async () => { + const result3 = await subject( + ` + /** @type {import('eslint').Linter.Config} should be multiline */ + const config = { + // ... + }; +`, + { + jsdocCommentLineStrategy: "multiline", + }, + ); + expect(result3).toMatchSnapshot(); + }); +}); diff --git a/tests/tagGroup.test.ts b/tests/tagGroup.test.ts index 2630887..565d63c 100644 --- a/tests/tagGroup.test.ts +++ b/tests/tagGroup.test.ts @@ -71,7 +71,7 @@ test("space after unknownTag", async () => { jsdocPrintWidth: 120, jsdocSeparateReturnsFromParam: false, jsdocSeparateTagGroups: true, - jsdocSingleLineComment: false, + jsdocCommentLineStrategy: "multiline", jsdocSpaces: 1, jsdocVerticalAlignment: true, tsdoc: false,