gajus/eslint-plugin-jsdoc

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

Open

#1,054 opened on Apr 27, 2023

 (0 comments) (1 reaction) (0 assignees)JavaScript (177 forks)github user discovery
enhancementhelp wanted

Repository metrics

Stars
 (1,227 stars)
PR merge metrics
 (Avg merge 2d 8h) (10 merged PRs in 30d)

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