refactor(semantic/jsdoc): Rework JSDoc struct for better Span handling

crates/oxc_linter/src/rules/jsdoc/check_access.rs

@@ -11,7 +11,7 @@ use crate::{context::LintContext, rule::Rule};
 
 #[derive(Debug, Error, Diagnostic)]
 enum CheckAccessDiagnostic {
-    #[error("eslint-plugin-jsdoc(check-access): Invalid access level is specified.")]
+    #[error("eslint-plugin-jsdoc(check-access): Invalid access level is specified or missing.")]
     #[diagnostic(
         severity(warning),
         help("Valid access levels are `package`, `private`, `protected`, and `public`.")
@@ -77,19 +77,23 @@ impl Rule for CheckAccess {
 
         for jsdoc in ctx.semantic().jsdoc().iter_all() {
             let mut access_related_tags_count = 0;
-            for (span, tag) in jsdoc.tags() {
-                if access_related_tag_names.contains(tag.kind) {
+            for tag in jsdoc.tags() {
+                let kind = tag.kind.parsed();
+                if access_related_tag_names.contains(kind) {
                     access_related_tags_count += 1;
                 }
 
                 // Has valid access level?
-                if tag.kind == resolved_access_tag_name && !ACCESS_LEVELS.contains(&tag.comment()) {
-                    ctx.diagnostic(CheckAccessDiagnostic::InvalidAccessLevel(*span));
+                let comment = tag.comment();
+                if kind == resolved_access_tag_name && !ACCESS_LEVELS.contains(&comment.parsed()) {
+                    ctx.diagnostic(CheckAccessDiagnostic::InvalidAccessLevel(
+                        comment.span_trimmed_first_line(),
+                    ));
                 }
 
                 // Has redundant access level?
                 if 1 < access_related_tags_count {
-                    ctx.diagnostic(CheckAccessDiagnostic::RedundantAccessTags(*span));
+                    ctx.diagnostic(CheckAccessDiagnostic::RedundantAccessTags(tag.kind.span));
                 }
             }
         }

crates/oxc_linter/src/rules/jsdoc/empty_tags.rs

@@ -11,7 +11,7 @@ use crate::{context::LintContext, rule::Rule};
 
 #[derive(Debug, Error, Diagnostic)]
 #[error("eslint-plugin-jsdoc(empty-tags): Expects the void tags to be empty of any content.")]
-#[diagnostic(severity(warning), help("`@{1}` tag should be empty."))]
+#[diagnostic(severity(warning), help("`@{1}` tag should not have body."))]
 struct EmptyTagsDiagnostic(#[label] Span, String);
 
 #[derive(Debug, Default, Clone)]
@@ -106,15 +106,20 @@ impl Rule for EmptyTags {
         };
 
         for jsdoc in ctx.semantic().jsdoc().iter_all() {
-            for (span, tag) in jsdoc.tags() {
-                if !is_empty_tag_kind(tag.kind) {
+            for tag in jsdoc.tags() {
+                let kind = tag.kind.parsed();
+                if !is_empty_tag_kind(kind) {
                     continue;
                 }
-                if tag.comment().is_empty() {
+                let comment = tag.comment();
+                if comment.parsed().is_empty() {
                     continue;
                 }
 
-                ctx.diagnostic(EmptyTagsDiagnostic(*span, tag.kind.to_string()));
+                ctx.diagnostic(EmptyTagsDiagnostic(
+                    comment.span_trimmed_first_line(),
+                    kind.to_string(),
+                ));
             }
         }
     }
@@ -308,7 +313,8 @@ fn test() {
         (
             "
 			      /**
-			       * @private {someType}
+			       * @private foo
+			       * bar
 			       */
 			      function quux () {
 
@@ -320,7 +326,8 @@ fn test() {
         (
             "
 			      /**
-			       * @internal {someType}
+			       * @internal
+                   * foo
 			       */
 			      function quux () {
 

crates/oxc_linter/src/snapshots/check_access.snap

@@ -2,47 +2,47 @@
 source: crates/oxc_linter/src/tester.rs
 expression: check_access
 ---
-  ⚠ eslint-plugin-jsdoc(check-access): Invalid access level is specified.
-   ╭─[check_access.tsx:3:17]
+  ⚠ eslint-plugin-jsdoc(check-access): Invalid access level is specified or missing.
+   ╭─[check_access.tsx:3:25]
  2 │                       /**
  3 │                        * @access foo
-   ·                          ───────
+   ·                                  ───
  4 │                        */
    ╰────
   help: Valid access levels are `package`, `private`, `protected`, and `public`.
 
-  ⚠ eslint-plugin-jsdoc(check-access): Invalid access level is specified.
-   ╭─[check_access.tsx:3:17]
+  ⚠ eslint-plugin-jsdoc(check-access): Invalid access level is specified or missing.
+   ╭─[check_access.tsx:3:25]
  2 │                       /**
  3 │                        * @access foo
-   ·                          ───────
+   ·                                  ───
  4 │                        */
    ╰────
   help: Valid access levels are `package`, `private`, `protected`, and `public`.
 
-  ⚠ eslint-plugin-jsdoc(check-access): Invalid access level is specified.
-   ╭─[check_access.tsx:3:25]
+  ⚠ eslint-plugin-jsdoc(check-access): Invalid access level is specified or missing.
+   ╭─[check_access.tsx:3:38]
  2 │                               /**
  3 │                                * @accessLevel foo
-   ·                                  ────────────
+   ·                                               ───
  4 │                                */
    ╰────
   help: Valid access levels are `package`, `private`, `protected`, and `public`.
 
-  ⚠ eslint-plugin-jsdoc(check-access): Invalid access level is specified.
-   ╭─[check_access.tsx:3:17]
+  ⚠ eslint-plugin-jsdoc(check-access): Invalid access level is specified or missing.
+   ╭─[check_access.tsx:3:24]
  2 │                       /**
  3 │                        * @access
-   ·                          ───────
+   ·                                 ▲
  4 │                        */
    ╰────
   help: Valid access levels are `package`, `private`, `protected`, and `public`.
 
-  ⚠ eslint-plugin-jsdoc(check-access): Invalid access level is specified.
-   ╭─[check_access.tsx:4:15]
+  ⚠ eslint-plugin-jsdoc(check-access): Invalid access level is specified or missing.
+   ╭─[check_access.tsx:4:22]
  3 │                     /**
  4 │                      * @access
-   ·                        ───────
+   ·                               ▲
  5 │                      */
    ╰────
   help: Valid access levels are `package`, `private`, `protected`, and `public`.

crates/oxc_linter/src/snapshots/empty_tags.snap

@@ -3,73 +3,73 @@ source: crates/oxc_linter/src/tester.rs
 expression: empty_tags
 ---
   ⚠ eslint-plugin-jsdoc(empty-tags): Expects the void tags to be empty of any content.
-   ╭─[empty_tags.tsx:3:17]
+   ╭─[empty_tags.tsx:3:27]
  2 │                       /**
  3 │                        * @abstract extra text
-   ·                          ─────────
+   ·                                    ──────────
  4 │                        */
    ╰────
-  help: `@abstract` tag should be empty.
+  help: `@abstract` tag should not have body.
 
   ⚠ eslint-plugin-jsdoc(empty-tags): Expects the void tags to be empty of any content.
-   ╭─[empty_tags.tsx:4:17]
+   ╭─[empty_tags.tsx:4:27]
  3 │                       /**
  4 │                        * @abstract extra text
-   ·                          ─────────
+   ·                                    ──────────
  5 │                        */
    ╰────
-  help: `@abstract` tag should be empty.
+  help: `@abstract` tag should not have body.
 
   ⚠ eslint-plugin-jsdoc(empty-tags): Expects the void tags to be empty of any content.
-   ╭─[empty_tags.tsx:3:17]
+   ╭─[empty_tags.tsx:3:27]
  2 │                       /**
  3 │                        * @abstract extra text
-   ·                          ─────────
+   ·                                    ──────────
  4 │                        * @inheritdoc
    ╰────
-  help: `@abstract` tag should be empty.
+  help: `@abstract` tag should not have body.
 
   ⚠ eslint-plugin-jsdoc(empty-tags): Expects the void tags to be empty of any content.
-   ╭─[empty_tags.tsx:5:17]
+   ╭─[empty_tags.tsx:5:24]
  4 │                        * @inheritdoc
  5 │                        * @async out of place
-   ·                          ──────
+   ·                                 ────────────
  6 │                        */
    ╰────
-  help: `@async` tag should be empty.
+  help: `@async` tag should not have body.
 
   ⚠ eslint-plugin-jsdoc(empty-tags): Expects the void tags to be empty of any content.
-   ╭─[empty_tags.tsx:3:17]
+   ╭─[empty_tags.tsx:3:24]
  2 │                       /**
  3 │                        * @event anEvent
-   ·                          ──────
+   ·                                 ───────
  4 │                        */
    ╰────
-  help: `@event` tag should be empty.
+  help: `@event` tag should not have body.
 
   ⚠ eslint-plugin-jsdoc(empty-tags): Expects the void tags to be empty of any content.
-   ╭─[empty_tags.tsx:3:13]
+   ╭─[empty_tags.tsx:3:22]
  2 │                   /**
- 3 │                    * @private {someType}
-   ·                      ────────
- 4 │                    */
+ 3 │                    * @private foo
+   ·                               ───
+ 4 │                    * bar
    ╰────
-  help: `@private` tag should be empty.
+  help: `@private` tag should not have body.
 
   ⚠ eslint-plugin-jsdoc(empty-tags): Expects the void tags to be empty of any content.
-   ╭─[empty_tags.tsx:3:13]
- 2 │                   /**
- 3 │                    * @internal {someType}
-   ·                      ─────────
- 4 │                    */
+   ╭─[empty_tags.tsx:4:20]
+ 3 │                    * @internal
+ 4 │                    * foo
+   ·                    ─────
+ 5 │                    */
    ╰────
-  help: `@internal` tag should be empty.
+  help: `@internal` tag should not have body.
 
   ⚠ eslint-plugin-jsdoc(empty-tags): Expects the void tags to be empty of any content.
-   ╭─[empty_tags.tsx:3:13]
+   ╭─[empty_tags.tsx:3:22]
  2 │                   /**
  3 │                    * @private {someType}
-   ·                      ────────
+   ·                               ──────────
  4 │                    */
    ╰────
-  help: `@private` tag should be empty.
+  help: `@private` tag should not have body.

crates/oxc_semantic/src/jsdoc/builder.rs

@@ -429,11 +429,11 @@ mod test {
         // Should be [farthest, ..., nearest]
         let mut iter = jsdocs.iter();
         let c1 = iter.next().unwrap();
-        assert_eq!(c1.comment(), "c1");
+        assert_eq!(c1.comment().parsed(), "c1");
         let c2 = iter.next().unwrap();
-        assert_eq!(c2.comment(), "c2");
+        assert_eq!(c2.comment().parsed(), "c2");
         let c3 = iter.next().unwrap();
-        assert_eq!(c3.comment(), "c3");
+        assert_eq!(c3.comment().parsed(), "c3");
     }
 
     #[test]