From 3c68f21f36d08f91ff3dcbafb23ab0f11304dfb9 Mon Sep 17 00:00:00 2001
From: Jeff Williams <jeffrey.l.williams@gmail.com>
Date: Sun, 12 Jan 2025 15:06:45 -0800
Subject: [PATCH] feat: add a doclet `kind` for enums

---
 packages/jsdoc-doclet/lib/doclet.js                  |  2 +-
 packages/jsdoc-doclet/lib/schema.js                  |  4 +---
 packages/jsdoc-parse/lib/parser.js                   |  2 +-
 packages/jsdoc-tag/lib/definitions/core.js           |  5 +++--
 packages/jsdoc-template-legacy/lib/templateHelper.js |  2 +-
 packages/jsdoc-template-legacy/tmpl/container.tmpl   | 11 +++++++++++
 packages/jsdoc-template-legacy/tmpl/properties.tmpl  |  2 +-
 packages/jsdoc/test/specs/tags/enumtag.js            |  4 +++-
 8 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/packages/jsdoc-doclet/lib/doclet.js b/packages/jsdoc-doclet/lib/doclet.js
index e84b45f1..4e58acb4 100644
--- a/packages/jsdoc-doclet/lib/doclet.js
+++ b/packages/jsdoc-doclet/lib/doclet.js
@@ -45,7 +45,7 @@ const CLASSDESC_TAG = '@classdesc';
 const DEFAULT_SCOPE = SCOPE.NAMES.STATIC;
 const DESCRIPTION_TAG = '@description';
 // TODO: `class` should be on this list, right? What are the implications of adding it?
-const GLOBAL_KINDS = ['constant', 'function', 'member', 'typedef'];
+const GLOBAL_KINDS = ['constant', 'enum', 'function', 'member', 'typedef'];
 const ON_CHANGE_OPTIONS = {
   ignoreDetached: true,
   pathAsArray: true,
diff --git a/packages/jsdoc-doclet/lib/schema.js b/packages/jsdoc-doclet/lib/schema.js
index 4433ed08..980d598c 100644
--- a/packages/jsdoc-doclet/lib/schema.js
+++ b/packages/jsdoc-doclet/lib/schema.js
@@ -331,15 +331,13 @@ export const DOCLET_SCHEMA = {
         inherited: true,
       },
     },
-    isEnum: {
-      type: BOOLEAN,
-    },
     // what kind of symbol is this?
     kind: {
       type: STRING,
       enum: [
         'class',
         'constant',
+        'enum',
         'event',
         'external',
         'file',
diff --git a/packages/jsdoc-parse/lib/parser.js b/packages/jsdoc-parse/lib/parser.js
index d2295b34..0c20b43a 100644
--- a/packages/jsdoc-parse/lib/parser.js
+++ b/packages/jsdoc-parse/lib/parser.js
@@ -595,7 +595,7 @@ export class Parser extends EventEmitter {
     const doclets = this.resolvePropertyParents(e.code.node.parent);
 
     doclets.forEach((doclet) => {
-      if (doclet?.isEnum) {
+      if (doclet.kind === 'enum') {
         doclet.properties = doclet.properties || [];
 
         // members of an enum inherit the enum's type
diff --git a/packages/jsdoc-tag/lib/definitions/core.js b/packages/jsdoc-tag/lib/definitions/core.js
index 9820f1e2..c774855d 100644
--- a/packages/jsdoc-tag/lib/definitions/core.js
+++ b/packages/jsdoc-tag/lib/definitions/core.js
@@ -184,8 +184,9 @@ export const getTags = (env) => ({
   enum: {
     canHaveType: true,
     onTagged(doclet, tag) {
-      doclet.kind ??= 'member';
-      doclet.isEnum = true;
+      if (!doclet.kind) {
+        util.setDocletKindToTitle(doclet, tag);
+      }
       util.setDocletTypeToValueType(doclet, tag);
     },
   },
diff --git a/packages/jsdoc-template-legacy/lib/templateHelper.js b/packages/jsdoc-template-legacy/lib/templateHelper.js
index 05ed5dc4..52f20d8a 100644
--- a/packages/jsdoc-template-legacy/lib/templateHelper.js
+++ b/packages/jsdoc-template-legacy/lib/templateHelper.js
@@ -565,7 +565,7 @@ export function getMembers(data) {
     externals: find(data, { kind: 'external' }),
     events: find(data, { kind: 'event' }),
     globals: find(data, {
-      kind: ['member', 'function', 'constant', 'typedef'],
+      kind: ['enum', 'member', 'function', 'constant', 'typedef'],
       memberof: { isUndefined: true },
     }),
     mixins: find(data, { kind: 'mixin' }),
diff --git a/packages/jsdoc-template-legacy/tmpl/container.tmpl b/packages/jsdoc-template-legacy/tmpl/container.tmpl
index 2e8366f6..905694b5 100644
--- a/packages/jsdoc-template-legacy/tmpl/container.tmpl
+++ b/packages/jsdoc-template-legacy/tmpl/container.tmpl
@@ -145,6 +145,17 @@
         <?js }); ?></dl>
     <?js } ?>
 
+    <?js
+        var enums = self.find({kind: 'enum', memberof: isGlobalPage ? {isUndefined: true} : doc.longname});
+        if (enums && enums.length && enums.forEach) {
+    ?>
+        <h3 class="subsection-title">Enums</h3>
+
+        <?js enums.forEach(function(e) { ?>
+            <?js= self.partial('members.tmpl', e) ?>
+        <?js }); ?>
+    <?js } ?>
+
     <?js
         var members = self.find({kind: 'member', memberof: isGlobalPage ? {isUndefined: true} : doc.longname});
 
diff --git a/packages/jsdoc-template-legacy/tmpl/properties.tmpl b/packages/jsdoc-template-legacy/tmpl/properties.tmpl
index 2263bc1f..5d00a0ff 100644
--- a/packages/jsdoc-template-legacy/tmpl/properties.tmpl
+++ b/packages/jsdoc-template-legacy/tmpl/properties.tmpl
@@ -49,7 +49,7 @@
             props.hasName = true;
         }
 
-        if (typeof prop.defaultvalue !== 'undefined' && !data.isEnum) {
+        if (typeof prop.defaultvalue !== 'undefined' && !data.kind === 'enum') {
             props.hasDefault = true;
         }
     });
diff --git a/packages/jsdoc/test/specs/tags/enumtag.js b/packages/jsdoc/test/specs/tags/enumtag.js
index 4c7f338c..56faab0e 100644
--- a/packages/jsdoc/test/specs/tags/enumtag.js
+++ b/packages/jsdoc/test/specs/tags/enumtag.js
@@ -13,11 +13,13 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
 describe('@enum tag', () => {
   const docSet = jsdoc.getDocSetFromFile('test/fixtures/enumtag.js');
   const tristate = docSet.getByLongname('TriState')[0];
 
-  it('When a symbol has an @enum tag, it has a properties array.', () => {
+  it('When a symbol has an @enum tag, it has the kind `enum` and a properties array.', () => {
+    expect(tristate.kind).toBe('enum');
     expect(tristate.properties).toBeArray();
   });