feat: jsdocCommentLineStrategy

issue: #135

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.
 

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<keyof JsdocOptions, SupportOption> = {
-  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<keyof JsdocOptions, SupportOption> = {
     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<keyof JsdocOptions, SupportOption> = {
     default: "greedy",
     description: `Strategy for wrapping lines for the given print width. More options may be added in the future.`,
   },
-};
+} satisfies Record<keyof JsdocOptions, SupportOption>;
 
 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";
+  }
+}

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,
           );

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;

src/utils.ts

@@ -127,12 +127,15 @@ async function formatType(type: string, options?: Options): Promise<string> {
 }
 
 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()} `;
   }

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) {}

tests/descriptions.test.ts

@@ -677,7 +677,7 @@ test("Long words", async () => {
  */
 `,
     {
-      jsdocSingleLineComment: false,
+      jsdocCommentLineStrategy: "multiline",
     },
   );
 

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: [],
     },
   );
 

tests/main.test.ts

@@ -104,15 +104,15 @@ 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(`/**
  * single line description
  * @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,

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();
+  });
+});

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,