feat: add jsdocEmptyCommentStrategy option to handle empty JSDoc comments ("keep"| "remove") "remove" is default

#243

Author: fardad-dev

README.md

@@ -196,6 +196,7 @@ Like code tags (` ```js `), header tags like `# Header`, or other Markdown featu
 | `jsdocSeparateReturnsFromParam`     | Boolean                           | false        | Adds a space between last `@param` and `@returns`                                                                                                                       |
 | `jsdocSeparateTagGroups`            | Boolean                           | false        | Adds a space between tag groups                                                                                                                                         |
 | `jsdocPreferCodeFences`             | Boolean                           | false        | Always fence code blocks (surround them by triple backticks)                                                                                                            |
+| `jsdocEmptyCommentStrategy`         | ("remove","keep")                 | "remove"     | How to handle empty JSDoc comment blocks                                                                                                                                |
 | `tsdoc`                             | Boolean                           | false        | See [TSDoc](#tsdoc)                                                                                                                                                     |
 | `jsdocPrintWidth`                   | Number                            | undefined    | If you don't set the value to `jsdocPrintWidth`, `printWidth` will be used as `jsdocPrintWidth`                                                                         |
 | `jsdocLineWrappingStyle`            | String                            | "greedy"     | "greedy": lines wrap as soon as they reach `printWidth`. "balance": preserve existing line breaks if lines are shorter than `printWidth`, otherwise use greedy wrapping |

src/index.ts

@@ -176,6 +176,23 @@ const options = {
     default: true,
     description: "Format import tags",
   },
+  jsdocEmptyCommentStrategy: {
+    name: "jsdocEmptyCommentStrategy",
+    type: "choice",
+    choices: [
+      {
+        value: "remove",
+        description: "Remove empty JSDoc comment blocks",
+      },
+      {
+        value: "keep",
+        description: "Keep empty JSDoc comment blocks",
+      },
+    ] as ChoiceSupportOption["choices"],
+    category: "jsdoc",
+    default: "remove",
+    description: "How to handle empty JSDoc comment blocks",
+  },
 } as const satisfies Record<keyof JsdocOptions, SupportOption>;
 
 const defaultOptions: JsdocOptions = {
@@ -200,6 +217,7 @@ const defaultOptions: JsdocOptions = {
   jsdocNamedImportPadding: options.jsdocNamedImportPadding.default,
   jsdocMergeImports: options.jsdocMergeImports.default,
   jsdocNamedImportLineSplitting: options.jsdocNamedImportLineSplitting.default,
+  jsdocEmptyCommentStrategy: options.jsdocEmptyCommentStrategy.default,
 };
 
 const parsers = {

src/parser.ts

@@ -46,6 +46,7 @@ export const getParser = (originalParse: Parser["parse"], parserName: string) =>
     options = {
       ...options,
       printWidth: options.jsdocPrintWidth ?? options.printWidth,
+      jsdocEmptyCommentStrategy: options.jsdocEmptyCommentStrategy ?? "remove",
     };
 
     const eol =
@@ -241,9 +242,11 @@ export const getParser = (originalParse: Parser["parse"], parserName: string) =>
       }),
     );
 
-    ast.comments = ast.comments.filter(
-      (comment) => !(isBlockComment(comment) && !comment.value),
-    );
+    if (options.jsdocEmptyCommentStrategy === "remove") {
+      ast.comments = ast.comments.filter(
+        (comment) => !(isBlockComment(comment) && !comment.value),
+      );
+    }
 
     return ast;
   };

src/types.ts

@@ -26,6 +26,7 @@ export interface JsdocOptions {
   jsdocNamedImportPadding: boolean;
   jsdocMergeImports: boolean;
   jsdocNamedImportLineSplitting: boolean;
+  jsdocEmptyCommentStrategy: "remove" | "keep";
 }
 
 export interface AllOptions extends ParserOptions, JsdocOptions {}

tests/__snapshots__/main.test.ts.snap

@@ -61,6 +61,27 @@ exports[`Block quote 2`] = `
 "
 `;
 
+exports[`Empty JSDoc comment - default behavior (should remove) 1`] = `
+"function test() {}
+
+const value = 1;
+
+class MyClass {}
+"
+`;
+
+exports[`Empty JSDoc comment - with jsdocEmptyCommentStrategy keep 1`] = `
+"/**/
+function test() {}
+
+/**/
+const value = 1;
+
+/**/
+class MyClass {}
+"
+`;
+
 exports[`Empty comment 1`] = `
 "// Line Comment
 //
@@ -141,6 +162,27 @@ exports[`Long description memory leak 1`] = `
 "
 `;
 
+exports[`Mixed empty and non-empty JSDoc comments - with jsdocEmptyCommentStrategy keep 1`] = `
+"/**/
+function emptyDoc() {}
+
+/**
+ * This has content
+ *
+ * @param {string} name
+ */
+function withContent(name) {}
+
+/**/
+const emptyValue = 1;
+
+/** @returns {number} */
+function withReturn() {
+  return 42;
+}
+"
+`;
+
 exports[`Non-jsdoc comment 1`] = `
 "// @type   { something  }
 /* @type   { something  }  */

tests/main.test.ts

@@ -454,6 +454,74 @@ test("Empty comment", async () => {
   expect(result).toMatchSnapshot();
 });
 
+test("Empty JSDoc comment - default behavior (should remove)", async () => {
+  const result = await subject(`
+/**
+ */
+function test() {}
+
+/** */
+const value = 1;
+
+/**
+ *
+ */
+class MyClass {}
+  `);
+
+  expect(result).toMatchSnapshot();
+});
+
+test("Empty JSDoc comment - with jsdocEmptyCommentStrategy keep", async () => {
+  const result = await subject(
+    `
+/**
+ */
+function test() {}
+
+/** */
+const value = 1;
+
+/**
+ *
+ */
+class MyClass {}
+  `,
+    { jsdocEmptyCommentStrategy: "keep" },
+  );
+
+  expect(result).toMatchSnapshot();
+});
+
+test("Mixed empty and non-empty JSDoc comments - with jsdocEmptyCommentStrategy keep", async () => {
+  const result = await subject(
+    `
+/**
+ */
+function emptyDoc() {}
+
+/**
+ * This has content
+ * @param {string} name
+ */
+function withContent(name) {}
+
+/** */
+const emptyValue = 1;
+
+/**
+ * @returns {number}
+ */
+function withReturn() {
+  return 42;
+}
+  `,
+    { jsdocEmptyCommentStrategy: "keep" },
+  );
+
+  expect(result).toMatchSnapshot();
+});
+
 test("Optional parameters", async () => {
   const result = await subject(`
   /**