gajus/eslint-plugin-jsdoc

check-tag-names: autofix @prop tags onto props if they exist?

Open

#1,054 opened on Apr 27, 2023

View on GitHub
 (0 comments) (1 reaction) (0 assignees)JavaScript (172 forks)github user discovery
enhancementhelp wanted

Repository metrics

Stars
 (1,215 stars)
PR merge metrics
 (PR metrics pending)

Description

Motivation

From https://github.com/DefinitelyTyped/DefinitelyTyped/pull/65080/files#r1162947538: sometimes we see JSDoc @prop comments on an object that really should be on individual properties of the object. For example:

/**
 * @prop BASIC - icon, title, message, expandedMessage, up to two buttons.
 * @prop IMAGE - icon, title, message, expandedMessage, image, up to two buttons.
 */
declare const TemplateType: {
    BASIC: 'basic',
    IMAGE: 'image',
}

Current behavior

Right now check-tag-names only knows to fix this by removing @prop:

/**
- * @prop BASIC - icon, title, message, expandedMessage, up to two buttons.
- * @prop IMAGE - icon, title, message, expandedMessage, image, up to two buttons.
+ * BASIC - icon, title, message, expandedMessage, up to two buttons.
+ * IMAGE - icon, title, message, expandedMessage, image, up to two buttons.
 */
declare const TemplateType: {
    BASIC: 'basic',
    IMAGE: 'image',
}

Desired behavior

It'd be nice in situations where the prop name matches the @prop tag to move the comment onto the property itself:

/**
- * @prop BASIC - icon, title, message, expandedMessage, up to two buttons.
- * @prop IMAGE - icon, title, message, expandedMessage, image, up to two buttons.
 */
declare const TemplateType: {
+    /** 
+	  * icon, title, message, expandedMessage, up to two buttons.
+	  */
    BASIC: 'basic',

+    /** 
+	  * icon, title, message, expandedMessage, image, up to two buttons.
+	  */
    IMAGE: 'image',
}

Alternatives considered

Honestly this feels pretty low priority to me. The "before" pattern mentioned here is not very common. But it'd be cool to see this happen, maybe? 🤷

Contributor guide