feat: support tsdoc

issue: microsoft/tsdoc#20
#46

Author: hosseinmd

README.md

@@ -181,6 +181,7 @@ Description is formatting as Markdown, so you could use any features of Markdown
 | jsdocVerticalAlignment            | Boolean | false   |
 | jsdocKeepUnParseAbleExampleIndent | Boolean | false   |
 | jsdocSingleLineComment            | Boolean | true    |
+| tsdoc                             | Boolean | false   |
 
 Full up to date list and description of options can be found in Prettier help. First install plugin then run Prettier with "--help" option.
 
@@ -207,6 +208,16 @@ Then, in your .eslintrc.json:
 }
 ```
 
+## Tsdoc
+
+We hope to support whole tsdoc, if we missed somethings please create an issue.
+
+```json
+{
+  "tsdoc": true
+};
+```
+
 ## Contribute
 
 1- Get a clone/fork of repo

src/index.ts

@@ -56,16 +56,25 @@ const options: Record<keyof JsdocOptions, SupportOption> = {
     default: true,
     description: "Should compact single line comment",
   },
+  tsdoc: {
+    name: "tsdoc",
+    type: "boolean",
+    category: "jsdoc",
+    default: false,
+    description: "Should format as tsdoc",
+  },
 };
 
 const defaultOptions: JsdocOptions = {
-  jsdocParser: true,
-  jsdocSpaces: 1,
-  jsdocDescriptionWithDot: false,
-  jsdocDescriptionTag: false,
-  jsdocVerticalAlignment: false,
-  jsdocKeepUnParseAbleExampleIndent: false,
-  jsdocSingleLineComment: true,
+  jsdocParser: options.jsdocParser.default as boolean,
+  jsdocSpaces: options.jsdocSpaces.default as number,
+  jsdocDescriptionWithDot: options.jsdocDescriptionWithDot.default as boolean,
+  jsdocDescriptionTag: options.jsdocDescriptionTag.default as boolean,
+  jsdocVerticalAlignment: options.jsdocVerticalAlignment.default as boolean,
+  jsdocKeepUnParseAbleExampleIndent: options.jsdocKeepUnParseAbleExampleIndent
+    .default as boolean,
+  jsdocSingleLineComment: options.jsdocSingleLineComment.default as boolean,
+  tsdoc: options.tsdoc.default as boolean,
 };
 
 const languages = prettier

src/stringify.ts

@@ -29,6 +29,7 @@ const stringify = (
     jsdocSpaces,
     jsdocVerticalAlignment,
     jsdocDescriptionTag,
+    tsdoc,
     useTabs,
     tabWidth,
   } = options;
@@ -61,8 +62,22 @@ const stringify = (
   }
   if (name) tagString += `${gap}${name}${" ".repeat(tagNameGapAdj)}`;
 
-  // Add description (complicated because of text wrap)
-  if (description && tag !== EXAMPLE) {
+  // Try to use prettier on @example tag description
+  if (tag === EXAMPLE && !tsdoc) {
+    const exampleCaption = description.match(/<caption>([\s\S]*?)<\/caption>/i);
+
+    if (exampleCaption) {
+      description = description.replace(exampleCaption[0], "");
+      tagString = `${tagString} ${exampleCaption[0]}`;
+    }
+
+    const beginningSpace = useTabs ? "\t" : " ".repeat(tabWidth);
+    const formattedExample = formatCode(description, beginningSpace, options);
+    tagString += formattedExample.startsWith("\n")
+      ? formattedExample.trimEnd()
+      : "\n" + formattedExample;
+  } // Add description (complicated because of text wrap)
+  else if (description) {
     if (useTagTitle) tagString += gap + " ".repeat(descGapAdj);
     if (
       TAGS_PEV_FORMATE_DESCRIPTION.includes(tag) ||
@@ -85,22 +100,6 @@ const stringify = (
     }
   }
 
-  // Try to use prettier on @example tag description
-  if (tag === EXAMPLE) {
-    const exampleCaption = description.match(/<caption>([\s\S]*?)<\/caption>/i);
-
-    if (exampleCaption) {
-      description = description.replace(exampleCaption[0], "");
-      tagString = `${tagString} ${exampleCaption[0]}`;
-    }
-
-    const beginningSpace = useTabs ? "\t" : " ".repeat(tabWidth);
-    const formattedExample = formatCode(description, beginningSpace, options);
-    tagString += formattedExample.startsWith("\n")
-      ? formattedExample.trimEnd()
-      : "\n" + formattedExample;
-  }
-
   // Add empty line after some tags if there is something below
   tagString += descriptionEndLine({
     description: tagString,

src/types.ts

@@ -9,6 +9,7 @@ export interface JsdocOptions {
   jsdocParser: boolean;
   /** default is true */
   jsdocSingleLineComment: boolean;
+  tsdoc: boolean;
 }
 
 export interface AllOptions extends ParserOptions, JsdocOptions {}

tests/__snapshots__/files/tsdoc.ts.shot

@@ -0,0 +1,71 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`File: tsdoc.ts Options: {"tsdoc":true} 1`] = `
+"/**
+ * @example Adding one adds one
+ *
+ * \`\`\`typescript
+ * import plusOne from \\"plus-one\\";
+ * import expect from \\"test-lib\\";
+ *
+ * const actual = plusOne(3);
+ * expect(actual).toEqual(4);
+ * \`\`\`
+ */
+export function plusOne(input: number) {
+  return input + 1;
+}
+
+/**
+ * Parses a JSON file.
+ *
+ * @example Parsing a basic JSON file
+ *
+ *   # Contents of \`file.json\`
+ *
+ * \`\`\`json
+ * {
+ *   \\"exampleItem\\": \\"text\\"
+ * }
+ * \`\`\`
+ *
+ * # Usage
+ *
+ * \`\`\`ts
+ * const result = parseFile(\\"file.json\\");
+ * \`\`\`
+ *
+ * # Result
+ *
+ * \`\`\`ts
+ * {
+ *   exampleItem:'text',
+ * }
+ * \`\`\`
+ *
+ * @param path - Full path to the file.
+ * @returns An object containing the JSON data.
+ */
+
+/**
+ * Adds two numbers together.
+ *
+ * @example Here's a simple example:
+ *
+ * \`\`\`js
+ * // Prints \\"2\\":
+ * console.log(add(1, 1));
+ * \`\`\`
+ *
+ * @example Here's an example with negative numbers:
+ *
+ * \`\`\`
+ * // Prints \\"0\\":
+ * console.log(add(1,-1));
+ * \`\`\`
+ */
+export function add(x: number, y: number): number {
+  return x * y;
+}
+"
+`;

tests/files.test.ts

@@ -54,6 +54,12 @@ const files: {
       jsdocKeepUnParseAbleExampleIndent: true,
     },
   },
+  {
+    name: "tsdoc.ts",
+    options: {
+      tsdoc: true,
+    },
+  },
 ];
 
 for (let i = 0; i < files.length; i++) {

tests/files/tsdoc.ts

@@ -0,0 +1,63 @@
+/**
+ * @example
+ * Adding one adds one
+ * ```typescript
+ * import plusOne from 'plus-one'
+ * import expect from 'test-lib'
+ *
+ * const actual=plusOne(3);
+ * expect(actual).toEqual(4);
+ * ```
+ */
+export function plusOne(input: number) {
+    return input + 1;
+  }
+
+
+
+  /**
+ * Parses a JSON file.
+ *
+ * @param path - Full path to the file.
+ * @returns An object containing the JSON data.
+ *
+ * @example Parsing a basic JSON file
+ *
+ * # Contents of `file.json`
+ * ```json
+ * {
+ *   "exampleItem":"text"
+ * }
+ * ```
+ *
+ * # Usage
+ * ```ts
+ * const result = parseFile("file.json");
+ * ```
+ *
+ * # Result
+ * ```ts
+ * {
+ *   exampleItem:'text',
+ * }
+ * ```
+ */
+
+ /**
+ * Adds two numbers together.
+ * @example
+ * Here's a simple example:
+ * ```js
+ * // Prints "2":
+ * console.log(add(1,1));
+ * ```
+ * @example
+ * Here's an example with negative numbers:
+ * ```
+ * // Prints "0":
+ * console.log(add(1,-1));
+ * ```
+ */
+export function add(x: number, y: number): number {
+    return x* y
+}