From 75d1cbdf91f4d75625634d3afd3f6acf6384fa7a Mon Sep 17 00:00:00 2001
From: Jeff Williams <jeffrey.l.williams@gmail.com>
Date: Tue, 21 Nov 2023 20:44:25 -0800
Subject: [PATCH] feat(jsdoc-tag): add `includesInlineTag` method

---
 packages/jsdoc-tag/lib/inline.js            | 14 +++++++
 packages/jsdoc-tag/test/specs/lib/inline.js | 43 ++++++++++++++++++++-
 2 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/packages/jsdoc-tag/lib/inline.js b/packages/jsdoc-tag/lib/inline.js
index 563d4159..6f004a6a 100644
--- a/packages/jsdoc-tag/lib/inline.js
+++ b/packages/jsdoc-tag/lib/inline.js
@@ -77,6 +77,20 @@ export function isInlineTag(string, tagName) {
   return regExpFactory(tagName, '^', '$').test(string);
 }
 
+/**
+ * Check whether a string includes one or more inline tags. You can check for a specific inline tag
+ * or for any valid inline tag.
+ *
+ * @param {string} string - The string to check.
+ * @param {?string} tagName - The inline tag to match. May contain regexp characters. If this
+ * parameter is omitted, this method returns `true` for any valid inline tag.
+ * @returns {boolean} Set to `true` if the string includes at least one valid inline tag or `false`
+ * in all other cases.
+ */
+export function includesInlineTag(string, tagName) {
+  return regExpFactory(tagName).test(string);
+}
+
 /**
  * Replace all instances of multiple inline tags with other text.
  *
diff --git a/packages/jsdoc-tag/test/specs/lib/inline.js b/packages/jsdoc-tag/test/specs/lib/inline.js
index f757bda0..101e44b2 100644
--- a/packages/jsdoc-tag/test/specs/lib/inline.js
+++ b/packages/jsdoc-tag/test/specs/lib/inline.js
@@ -20,6 +20,10 @@ describe('@jsdoc/tag/lib/inline', () => {
     expect(inline).toBeObject();
   });
 
+  it('exports an `includesInlineTag` function', () => {
+    expect(inline.includesInlineTag).toBeFunction();
+  });
+
   it('exports an isInlineTag function', () => {
     expect(inline.isInlineTag).toBeFunction();
   });
@@ -32,8 +36,45 @@ describe('@jsdoc/tag/lib/inline', () => {
     expect(inline.extractInlineTag).toBeFunction();
   });
 
+  describe('includesInlineTag', () => {
+    const { includesInlineTag } = inline;
+
+    it('identifies a string that is an inline tag', () => {
+      expect(includesInlineTag('{@mytag hooray}', 'mytag')).toBeTrue();
+    });
+
+    it('identifies when a string does not include an inline tag', () => {
+      expect(includesInlineTag('mytag hooray', 'mytag')).toBeFalse();
+    });
+
+    it('identifies when a string contains an inline tag, plus extra characters', () => {
+      expect(includesInlineTag('this is {@mytag hooray}', 'mytag')).toBeTrue();
+    });
+
+    it('allows any inline tag by default', () => {
+      expect(includesInlineTag('Hello, {@anyoldtag will do}')).toBeTrue();
+    });
+
+    it('identifies things that are not inline tags when a tag name is not provided', () => {
+      expect(includesInlineTag('mytag hooray')).toBeFalse();
+    });
+
+    it('allows regexp characters in the tag name', () => {
+      expect(includesInlineTag('{@mytags hooray}', 'mytag\\S')).toBeTrue();
+    });
+
+    it('returns false (rather than throwing) with invalid input', () => {
+      function badInput() {
+        return includesInlineTag();
+      }
+
+      expect(badInput).not.toThrow();
+      expect(badInput()).toBeFalse();
+    });
+  });
+
   describe('isInlineTag', () => {
-    const isInlineTag = inline.isInlineTag;
+    const { isInlineTag } = inline;
 
     it('identifies an inline tag', () => {
       expect(isInlineTag('{@mytag hooray}', 'mytag')).toBeTrue();