fix(prettier-plugin-jsdoc): transform sentences on tags that use name

src/fns/constants.js

@@ -65,6 +65,7 @@ const getTagsWithNameAsDescription = () => [
   'see',
   'borrows',
   'yields',
+  'returns',
 ];
 
 module.exports.getTagsSynonyms = getTagsSynonyms;

src/fns/prepareTagDescription.js

@@ -1,29 +1,58 @@
 const R = require('ramda');
 const { ensureSentence, hasValidProperty, isTag } = require('./utils');
+const { getTagsWithNameAsDescription } = require('./constants');
 const { get, provider } = require('./app');
 
 /**
  * @typedef {import('../types').CommentTag} CommentTag
  */
 
+/**
+ * Takes a tag property, transforms it into a sentence and updates the tag.
+ *
+ * @callback MakePropertyIntoSentenceFn
+ * @param {string}     property The name of the property to transform.
+ * @param {CommentTag} tag      The tag where the property will be updated.
+ * @returns {CommentTag}
+ */
+
+/**
+ * @type {MakePropertyIntoSentenceFn}
+ */
+const makePropertyIntoSentence = R.curry((property, tag) => R.compose(
+  R.assoc(property, R.__, tag),
+  get(ensureSentence),
+  R.prop(property),
+)(tag));
+
 /**
  * Prepares the description of a tag in order for it to be rendered.
  *
  * @param {CommentTag} tag The tag which description will be formatted.
  * @returns {CommentTag}
  */
-const prepareTagDescription = (tag) => R.when(
-  R.allPass([
-    get(hasValidProperty)('description'),
-    R.complement(get(isTag)(['example', 'examples'])),
-  ]),
-  R.compose(
-    R.assoc('description', R.__, tag),
-    get(ensureSentence),
-    R.prop('description'),
-  ),
-  tag,
-);
+const prepareTagDescription = (tag) => {
+  const useHasValidProperty = get(hasValidProperty);
+  const useIsStag = get(isTag);
+  const useMakePropertyInstoSentence = get(makePropertyIntoSentence);
+  return R.when(
+    R.complement(useIsStag(['example', 'examples'])),
+    R.compose(
+      R.when(
+        useHasValidProperty('description'),
+        useMakePropertyInstoSentence('description'),
+      ),
+      R.when(
+        R.allPass([
+          useIsStag(get(getTagsWithNameAsDescription)()),
+          useHasValidProperty('name'),
+        ]),
+        useMakePropertyInstoSentence('name'),
+      ),
+    ),
+    tag,
+  );
+};
 
 module.exports.prepareTagDescription = prepareTagDescription;
 module.exports.provider = provider('prepareTagDescription', module.exports);

test/e2e/fixtures/random-01.fixture.js

@@ -1,3 +1,7 @@
+module.exports = {
+  only: true,
+};
+
 //# input
 
 /**
@@ -26,6 +30,7 @@ const log = (name = 'batman', logger) => {};
  * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec malesuada fermentum nibh, sed aliquet ante porta a. Nullam blandit posuere fringilla. Nullam vel risus vitae lectus luctus auctor a venenatis ante. In hac habitasse platea dictumst.
  * @summary
  * something else
+ * @returns {User} some description for the return value
  */
 
 //# output
@@ -71,6 +76,7 @@ const log = (name = 'batman', logger) => {};
  *   };
  * }} newUser
  * Something else.
+ * @returns {User} Some description for the return value.
  * @summary
  * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec malesuada fermentum nibh, sed
  * aliquet ante porta a. Nullam blandit posuere fringilla. Nullam vel risus vitae lectus luctus

test/unit/fns/prepareTagDescription.test.js

@@ -24,6 +24,19 @@ describe('prepareTagDescription', () => {
         description: 'Something.',
       },
     },
+    {
+      it: 'should transform a tag name',
+      input: {
+        tag: 'see',
+        name: 'something',
+        description: '',
+      },
+      output: {
+        tag: 'see',
+        name: 'Something.',
+        description: '',
+      },
+    },
     {
       it: 'should transform a tag description, respecting any leading and/or trailing space',
       input: {