fix: default tag type bug (#160)

* Getting the debugger to work for me

* #159 - Adding tests for expected default values

* FIX: `@default []` and `@default {}` turns into `@default` #159

* #159 Updating the `@default` tests

* Don't need to default to an array

This was outdated code from an earlier idea I had

* Adding `@defaultValue` tests

* Adding tests for non empty defaults

* Attempt at using the fix method mentioned in comment-parser issue 155

syavorsky/comment-parser#155

* Revert "Attempt at using the fix method mentioned in comment-parser issue 155"

This reverts commit 52800c5.

* Update to the `@default` tests (Warning: tests are failing)

* Exporting util funcitons directly rather than at the end

* Moving the `@default` tag value into the type property

* Updating expectations for `@default` tests

* Almost working, only 1 failing test left to fix

* Failed attempt at getting `@default {{ obj: 'val' }}` to work

* Dropping attempted support for curly bracket boilerplate `@default` value

It is being too troublesome to implement.
It also isn't part of the official jsDoc spec.
I think people would most likely either use values directly or use the JS doc official syntax so I don't see much reason in trying to support it.

* simplifying squareBracketBoilerplateMatch

I'm not trying to match against both square and curly boilerplates so I only need the one boiler plate type to match against

* Adding empty array/object in square bracket boilerplate tests

* Revert "Exporting util funcitons directly rather than at the end"

This reverts commit cc89717.

* Adding `@defaultvalue` (all lowercase) as a valid tag type

* Removing support for `@default [value]` syntax

That was a misunderstanding. The documentation means that the value is optional. It doesn't want you to put litteral square brackets in your code.

* Updating tests

* Making use of new `TAGS_DEFAULT` role for less repitition

* Dropping (attempted) support for all lowercase `@defaultvalue`

The official documentation says that `@defaultvalue` should be all lowercase.

Implementing support for this was more difficult than I expected. I'm droping this as being out of scope for this PR.

I have no intention of using the all lowercase `@defaultvalue` tag so I don't care about trying to support it.

* order fix in TAGS_PEV_FORMATE_DESCRIPTION

Co-authored-by: Daniel Tonon <[email protected]>

.vscode/launch.json

@@ -10,8 +10,9 @@
             "request": "launch",
             "runtimeArgs": [
                 "--inspect",
-                "./node_modules/.bin/jest",
-                "-i"
+                "./node_modules/jest/bin/jest.js",
+                "--runInBand",
+                "--watch"
             ],
             "cwd": "${workspaceRoot}",
             "protocol": "inspector",

src/parser.ts

@@ -6,6 +6,7 @@ import {
   detectEndOfLine,
   findTokenIndex,
   findPluginByParser,
+  isDefaultTag,
 } from "./utils";
 import { DESCRIPTION, PARAM, RETURNS } from "./tags";
 import {
@@ -538,9 +539,24 @@ function assignOptionalAndDefaultToName({
   default: default_,
   tag,
   type,
+  source,
+  description,
   ...rest
 }: Spec): Spec {
-  if (optional) {
+
+  if (isDefaultTag(tag)) {
+    const usefulSourceLine = source.find(x => x.source.includes(`@${tag}`))?.source || ''
+
+    const tagMatch = usefulSourceLine.match(/@default(Value)? (\[.*]|{.*}|\(.*\)|'.*'|".*"|`.*`|[A-z0-9_]+)( (.+))?/)
+    const tagValue = tagMatch?.[2] || ''
+    const tagDescription = tagMatch?.[4] || ''
+
+    if (tagMatch) {
+      type = tagValue
+      name = ''
+      description = tagDescription
+    }
+  } else if (optional) {
     if (name) {
       // Figure out if tag type have default value
       if (default_) {
@@ -557,8 +573,10 @@ function assignOptionalAndDefaultToName({
     ...rest,
     tag,
     name,
+    description,
     optional,
     type,
+    source,
     default: default_,
   };
 }

src/roles.ts

@@ -9,7 +9,7 @@ import {
   CLASS,
   CONSTANT,
   DEFAULT,
-  DEFAULT_Value,
+  DEFAULT_VALUE,
   DEPRECATED,
   DESCRIPTION,
   EXAMPLE,
@@ -111,11 +111,15 @@ const TAGS_TYPELESS = [
   FILE,
 ];
 
+const TAGS_DEFAULT = [
+  DEFAULT,
+  DEFAULT_VALUE,
+]
+
 const TAGS_PEV_FORMATE_DESCRIPTION = [
   /** @todo should be formate like jsdoc standard saw https://jsdoc.app/tags-borrows.html  */
   BORROWS,
-  DEFAULT,
-  DEFAULT_Value,
+  ...TAGS_DEFAULT,
   MEMBEROF,
   MODULE,
   SEE,
@@ -187,8 +191,7 @@ const TAGS_ORDER = [
   ABSTRACT,
   AUGMENTS,
   CONSTANT,
-  DEFAULT,
-  DEFAULT_Value,
+  ...TAGS_DEFAULT,
   EXTERNAL,
   FIRES,
   TEMPLATE,
@@ -223,4 +226,5 @@ export {
   TAGS_TYPE_NEEDED,
   TAGS_TYPELESS,
   TAGS_VERTICALLY_ALIGN_ABLE,
+  TAGS_DEFAULT,
 };

src/stringify.ts

@@ -13,7 +13,7 @@ import {
   TAGS_VERTICALLY_ALIGN_ABLE,
 } from "./roles";
 import { AllOptions } from "./types";
-import { formatCode } from "./utils";
+import { formatCode, formatType, isDefaultTag } from "./utils";
 
 const stringify = (
   { name, description, type, tag }: Spec,
@@ -64,7 +64,26 @@ const stringify = (
     tagString += `@${tag}${" ".repeat(tagTitleGapAdj || 0)}`;
   }
   if (type) {
-    tagString += gap + `{${type}}` + " ".repeat(tagTypeGapAdj);
+    const getUpdatedType = () => {
+      if (!isDefaultTag(tag)) {
+        return `{${type}}`
+      }
+
+      // The space is to improve readability in non-monospace fonts
+      if (type === '[]') return '[ ]'
+      if (type === '{}') return '{ }'
+
+      const isAnObject = (value: string): boolean => /^{.*[A-z0-9_]+ ?:.*}$/.test(value)
+      const fixObjectCommas = (objWithBrokenCommas: string): string => objWithBrokenCommas.replace(/; ([A-z0-9_])/g, ', $1')
+
+      if (isAnObject(type)) {
+        return fixObjectCommas(type)
+      }
+
+      return type
+    }
+    const updatedType = getUpdatedType()
+    tagString += gap + updatedType + " ".repeat(tagTypeGapAdj);
   }
   if (name) tagString += `${gap}${name}${" ".repeat(tagNameGapAdj)}`;
 
@@ -105,7 +124,7 @@ const stringify = (
       // Wrap tag description
       const beginningSpace =
         tag === DESCRIPTION ||
-        ([EXAMPLE, REMARKS, PRIVATE_REMARKS].includes(tag) && tsdoc)
+          ([EXAMPLE, REMARKS, PRIVATE_REMARKS].includes(tag) && tsdoc)
           ? ""
           : "  "; // google style guide space
 

src/tags.ts

@@ -10,7 +10,7 @@ const CATEGORY = "category";
 const CLASS = "class";
 const CONSTANT = "constant";
 const DEFAULT = "default";
-const DEFAULT_Value = "defaultValue";
+const DEFAULT_VALUE = "defaultValue";
 const DEPRECATED = "deprecated";
 const DESCRIPTION = "description";
 const EXAMPLE = "example";
@@ -66,7 +66,7 @@ export {
   CLASS,
   CONSTANT,
   DEFAULT,
-  DEFAULT_Value,
+  DEFAULT_VALUE,
   DEPRECATED,
   DESCRIPTION,
   EXAMPLE,

src/utils.ts

@@ -1,6 +1,7 @@
 import { format, Options, ParserOptions, Plugin } from "prettier";
 import { AllOptions, Token } from "./types";
 import BSearch from "binary-searching";
+import { TAGS_DEFAULT } from "./roles";
 
 function convertToModernType(oldType: string): string {
   return withoutStrings(oldType, (type) => {
@@ -254,8 +255,7 @@ function formatCode(
       .split("\n")
       .map(
         (l) =>
-          `${beginningSpace}${
-            jsdocKeepUnParseAbleExampleIndent ? l : l.trim()
+          `${beginningSpace}${jsdocKeepUnParseAbleExampleIndent ? l : l.trim()
           }`,
       )
       .join("\n")}\n`;
@@ -283,6 +283,8 @@ const findPluginByParser = (parserName: string, options: ParserOptions) => {
     : tsPlugin.parsers?.[parserName];
 };
 
+const isDefaultTag = (tag: string): boolean => TAGS_DEFAULT.includes(tag)
+
 export {
   convertToModernType,
   formatType,
@@ -292,4 +294,5 @@ export {
   findTokenIndex,
   formatCode,
   findPluginByParser,
+  isDefaultTag,
 };

tests/__snapshots__/default.test.ts.snap

@@ -1,17 +1,118 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`Empty default 1`] = `
+exports[`@default filled array 1`] = `
 "/**
- * The value
+ * The summary
  *
- * @default 'type' name description
+ * @default [1, \\"two\\", { three: true }, [\\"four\\"]]
  */
 "
 `;
 
-exports[`Empty default 2`] = `
+exports[`@default filled object 1`] = `
 "/**
- * The value
+ * The summary
+ *
+ * @default { object: \\"value\\", nestingTest: { obj: \\"nested\\" } }
+ */
+"
+`;
+
+exports[`@defaultValue filled array 1`] = `
+"/**
+ * The summary
+ *
+ * @defaultValue [1, \\"two\\", { three: true }, [\\"four\\"]]
+ */
+"
+`;
+
+exports[`@defaultValue filled object 1`] = `
+"/**
+ * The summary
+ *
+ * @defaultValue { object: \\"value\\", nestingTest: { obj: \\"nested\\" } }
+ */
+"
+`;
+
+exports[`Can't convert double quote @default if a single quote character is in the string 1`] = `
+"/**
+ * The summary
+ *
+ * @default \\"This isn't bad\\"
+ */
+"
+`;
+
+exports[`convert double quote @default to single quote 1`] = `
+"/**
+ * The summary
+ *
+ * @default 'value'
+ */
+"
+`;
+
+exports[`convert single quote @default to double quote 1`] = `
+"/**
+ * The summary
+ *
+ * @default \\"value\\"
+ */
+"
+`;
+
+exports[`default empty array 1`] = `
+"/**
+ * The summary
+ *
+ * @default [ ]
+ */
+"
+`;
+
+exports[`default empty object 1`] = `
+"/**
+ * The summary
+ *
+ * @default { }
+ */
+"
+`;
+
+exports[`default string with description 1`] = `
+"/**
+ * The summary
+ *
+ * @default \\"type\\" description
+ */
+"
+`;
+
+exports[`double default one 1`] = `
+"/**
+ * The summary
+ *
+ * @default \\"something\\"
+ * @default { }
+ */
+"
+`;
+
+exports[`double default two 1`] = `
+"/**
+ * The summary
+ *
+ * @default { }
+ * @default \\"something\\"
+ */
+"
+`;
+
+exports[`empty default tag 1`] = `
+"/**
+ * The summary
  *
  * @default
  */

tests/__snapshots__/main.test.ts.snap

@@ -452,7 +452,7 @@ exports[`jsdoc tags 1`] = `
 `;
 
 exports[`jsdoc tags 2`] = `
-"/** @default 'i am a value' i am the description */
+"/** @default \\"i am a value\\" i am the description */
 "
 `;