fix(prettier-plugin-jsdoc): make the constants into fns

.jestrc-unit.js

@@ -3,7 +3,7 @@ module.exports = {
   collectCoverage: true,
   coverageDirectory: 'coverage-unit',
   testPathIgnorePatterns: ['/node_modules/'],
-  unmockedModulePathPatterns: ['/node_modules/', 'app.js', 'utils.js'],
+  unmockedModulePathPatterns: ['/node_modules/', 'app.js', 'utils.js', 'constants.js'],
   testEnvironment: 'node',
   testMatch: ['**/unit/**/*.test.js'],
 };

src/fns/constants.js

@@ -0,0 +1,73 @@
+const { provider } = require('../app');
+
+/**
+ * Gets a dictionary where the keys are old tags' names, and values the current tag name for which
+ * they are synonym.
+ *
+ * This is used by one of the plugin functionalitites that updates tags' names.
+ *
+ * @returns {Object.<string,string>}
+ */
+const getTagsSynonyms = () => ({
+  virtual: 'abstract',
+  extends: 'augments',
+  constructor: 'class',
+  const: 'constant',
+  defaultvalue: 'default',
+  desc: 'description',
+  host: 'external',
+  fileoverview: 'file',
+  overview: 'file',
+  emits: 'fires',
+  func: 'function',
+  method: 'function',
+  var: 'member',
+  arg: 'param',
+  argument: 'param',
+  prop: 'property',
+  return: 'returns',
+  exception: 'throws',
+  yield: 'yields',
+  examples: 'example',
+});
+/**
+ * Gets a list of tags that shouldn't have a `name` property, like `summary`. This list exists
+ * because the parser package, incorrectly, takes the first word of the description and assigns it
+ * as the `name`.
+ * This plugin has a functionality that, based on this list, will move the `name` word to the
+ * `description` property.
+ *
+ * @returns {string[]}
+ */
+const getTagsWithDescriptionAsName = () => [
+  'author',
+  'classdesc',
+  'copyright',
+  'deprecated',
+  'description',
+  'desc',
+  'example',
+  'examples',
+  'file',
+  'license',
+  'summary',
+  'throws',
+  'todo',
+];
+/**
+ * This is almost the same as {@link getTagsWithDescriptionAsName}; the difference here is that
+ * after putting together the `name` and the `description`, instead of saving the result on
+ * `description`, it will be saved on `name`, as it will be better for the rendering.
+ *
+ * @returns {string[]}
+ */
+const getTagsWithNameAsDescription = () => [
+  'see',
+  'borrows',
+  'yields',
+];
+
+module.exports.getTagsSynonyms = getTagsSynonyms;
+module.exports.getTagsWithDescriptionAsName = getTagsWithDescriptionAsName;
+module.exports.getTagsWithNameAsDescription = getTagsWithNameAsDescription;
+module.exports.provider = provider('constants');

src/fns/formatTagsDescription.js

@@ -1,8 +1,5 @@
 const R = require('ramda');
-const {
-  TAGS_WITH_DESCRIPTION_AS_NAME,
-  TAGS_WITH_NAME_AS_DESCRIPTION,
-} = require('../constants');
+const { getTagsWithDescriptionAsName, getTagsWithNameAsDescription } = require('./constants');
 const { isTag, hasValidProperty } = require('./utils');
 const { get, provider } = require('../app');
 
@@ -88,11 +85,11 @@ const formatTagsDescription = (tags) => {
     R.compose(
       addParagraphFlag,
       R.when(
-        useIsTag(TAGS_WITH_NAME_AS_DESCRIPTION),
+        useIsTag(get(getTagsWithNameAsDescription)()),
         useJoinProperties('name', 'description', 'name'),
       ),
       R.when(
-        useIsTag(TAGS_WITH_DESCRIPTION_AS_NAME),
+        useIsTag(get(getTagsWithDescriptionAsName)()),
         useJoinProperties('name', 'description', 'description'),
       ),
       R.when(

src/fns/render.js

@@ -4,7 +4,7 @@ const { isTag, ensureSentence } = require('./utils');
 const { renderExampleTag } = require('./renderExampleTag');
 const { renderTagInLine } = require('./renderTagInLine');
 const { renderTagInColumns } = require('./renderTagInColumns');
-const { TAGS_WITH_NAME_AS_DESCRIPTION } = require('../constants');
+const { getTagsWithNameAsDescription } = require('./constants');
 const { get, provider } = require('../app');
 
 /**
@@ -254,33 +254,36 @@ const calculateColumnsWidth = (options, data, width) => {
  * @param {PrettierOptions}            options      The options sent to the plugin.
  * @returns {Object.<string,TagColumnsWidthData>}
  */
-const getTagsData = (lengthByTag, width, options) => Object.entries(lengthByTag).reduce(
-  (acc, [tagName, tagInfo]) => {
-    const columnsWidth = get(calculateColumnsWidth)(options, tagInfo, width);
-    if (TAGS_WITH_NAME_AS_DESCRIPTION.includes(tagName)) {
-      columnsWidth.description = 0;
-      columnsWidth.name = width - columnsWidth.tag - columnsWidth.type;
-    }
-    return {
-      ...acc,
-      [tagName]: {
-        canUseColumns: (
-          !tagInfo.hasMultilineType &&
-          (
-            !options.jsdocAllowDescriptionOnNewLinesForTags.includes(tagName) ||
-            !tagInfo.hasADescriptionParagraph
-          ) &&
-          (
-            !columnsWidth.description ||
-            columnsWidth.description >= options.jsdocDescriptionColumnMinLength
-          )
-        ),
-        columnsWidth,
-      },
-    };
-  },
-  {},
-);
+const getTagsData = (lengthByTag, width, options) => {
+  const tagsWithNameAsDesc = get(getTagsWithNameAsDescription)();
+  return Object.entries(lengthByTag).reduce(
+    (acc, [tagName, tagInfo]) => {
+      const columnsWidth = get(calculateColumnsWidth)(options, tagInfo, width);
+      if (tagsWithNameAsDesc.includes(tagName)) {
+        columnsWidth.description = 0;
+        columnsWidth.name = width - columnsWidth.tag - columnsWidth.type;
+      }
+      return {
+        ...acc,
+        [tagName]: {
+          canUseColumns: (
+            !tagInfo.hasMultilineType &&
+            (
+              !options.jsdocAllowDescriptionOnNewLinesForTags.includes(tagName) ||
+              !tagInfo.hasADescriptionParagraph
+            ) &&
+            (
+              !columnsWidth.description ||
+              columnsWidth.description >= options.jsdocDescriptionColumnMinLength
+            )
+          ),
+          columnsWidth,
+        },
+      };
+    },
+    {},
+  );
+};
 
 /**
  * Renders a JSDoc block in a list of lines.

src/fns/replaceTagsSynonyms.js

@@ -1,6 +1,6 @@
 const R = require('ramda');
-const { TAGS_SYNONYMS } = require('../constants');
-const { provider } = require('../app');
+const { getTagsSynonyms } = require('./constants');
+const { get, provider } = require('../app');
 
 /**
  * @typedef {import('../types').CommentTag} CommentTag
@@ -12,13 +12,16 @@ const { provider } = require('../app');
  * @param {CommentTag[]} tags  The list of tags where the replacement should happen.
  * @returns {CommentTag[]}
  */
-const replaceTagsSynonyms = (tags) => R.map(
-  (tag) => ({
-    ...tag,
-    tag: R.propOr(tag.tag, tag.tag, TAGS_SYNONYMS),
-  }),
-  tags,
-);
+const replaceTagsSynonyms = (tags) => {
+  const synonyms = get(getTagsSynonyms)();
+  return R.map(
+    (tag) => ({
+      ...tag,
+      tag: R.propOr(tag.tag, tag.tag, synonyms),
+    }),
+    tags,
+  );
+};
 
 module.exports.replaceTagsSynonyms = replaceTagsSynonyms;
 module.exports.provider = provider('replaceTagsSynonyms', module.exports);

test/unit/fns/formatTags.test.js

@@ -4,7 +4,6 @@ jest.unmock('../../../src/fns/replaceTagsSynonyms');
 jest.unmock('../../../src/fns/sortTags');
 jest.unmock('../../../src/fns/trimTagsProperties');
 jest.unmock('../../../src/fns/formatTagsDescription');
-jest.unmock('../../../src/constants');
 
 const { formatTags } = require('../../../src/fns/formatTags');
 

test/unit/fns/formatTagsDescription.test.js

@@ -1,5 +1,4 @@
 jest.unmock('../../../src/fns/formatTagsDescription');
-jest.unmock('../../../src/constants');
 
 const { formatTagsDescription } = require('../../../src/fns/formatTagsDescription');
 

test/unit/fns/render.test.js

@@ -4,7 +4,6 @@ jest.unmock('../../../src/fns/renderTagInColumns');
 jest.unmock('../../../src/fns/renderExampleTag');
 jest.unmock('../../../src/fns/splitText');
 jest.unmock('../../../src/fns/getOptions');
-jest.unmock('../../../src/constants');
 
 const { render } = require('../../../src/fns/render');
 const { getDefaultOptions } = require('../../../src/fns/getOptions');