fix(lint): don't flag missing-jsdoc when @deprecated carries docs

A JSDoc comment whose first block is @deprecated absorbs any following
description into the tag (per JSDoc semantics, the description must
precede all tags), leaving the symbol with no top-level doc field. The
missing-jsdoc lint then fired even though the symbol was clearly
documented.

Treat a symbol as documented when it has a @deprecated tag carrying a
non-empty explanation.

Author: crowlbot

src/diagnostics.rs

@@ -2,6 +2,7 @@
 
 use crate::Location;
 use crate::js_doc::JsDoc;
+use crate::js_doc::JsDocTag;
 use crate::node::DeclarationDef;
 use crate::node::DeclarationKind;
 use crate::node::NamespaceDef;
@@ -181,6 +182,24 @@ impl Diagnostic for DocDiagnostic {
   }
 }
 
+/// Whether a JSDoc block documents its symbol through a tag, even though it has
+/// no top-level description.
+///
+/// A `@deprecated` notice that carries an explanation counts as documentation.
+/// When `@deprecated` is the first block of a comment, any description that
+/// follows it is absorbed into the tag (per JSDoc semantics, the description
+/// must precede all tags), so the symbol ends up with no `doc` field even
+/// though it is clearly documented. Treating such a symbol as missing JSDoc
+/// would be a false positive.
+fn has_documenting_tag(js_doc: &JsDoc) -> bool {
+  js_doc.tags.iter().any(|tag| {
+    matches!(
+      tag,
+      JsDocTag::Deprecated { doc: Some(doc) } if !doc.trim().is_empty()
+    )
+  })
+}
+
 pub struct DiagnosticsCollector<'a> {
   root_symbol: Rc<RootSymbol<'a>>,
   seen_private_types_in_public: HashSet<(UniqueSymbolId, UniqueSymbolId)>,
@@ -278,6 +297,7 @@ impl<'a> DiagnosticsCollector<'a> {
 
   fn check_missing_js_doc(&mut self, js_doc: &JsDoc, location: &Location) {
     if js_doc.doc.is_none()
+      && !has_documenting_tag(js_doc)
       && !has_ignorable_js_doc_tag(js_doc)
       && self.seen_jsdoc_missing.insert(location.clone())
       && let Some(text_info) = self.maybe_get_text_info(location)

tests/specs/jsdoc_deprecated_before_description.txt

@@ -0,0 +1,117 @@
+# mod.ts
+/**
+ * @deprecated Use {@link bar} instead.
+ *
+ * Does a thing with the given value and returns it unchanged.
+ */
+export function foo(value: string): string {
+  return value;
+}
+
+/** @deprecated */
+export function baz(): void {}
+
+# diagnostics
+error[missing-jsdoc]: exported symbol is missing JSDoc documentation
+  --> /mod.ts:11:1
+   | 
+11 | export function baz(): void {}
+   | ^
+
+# output.txt
+Defined in file:///mod.ts:10:1
+
+function baz(): void
+
+  @deprecated
+
+Defined in file:///mod.ts:5:1
+
+function foo(value: string): string
+
+  @deprecated
+      Use {@link bar} instead.
+
+      Does a thing with the given value and returns it unchanged.
+
+
+
+# output.json
+{
+  "symbols": [
+    {
+      "name": "foo",
+      "declarations": [
+        {
+          "location": {
+            "filename": "file:///mod.ts",
+            "line": 5,
+            "col": 0,
+            "byteIndex": 114
+          },
+          "declarationKind": "export",
+          "jsDoc": {
+            "tags": [
+              {
+                "kind": "deprecated",
+                "doc": "Use {@link bar} instead.\n\nDoes a thing with the given value and returns it unchanged."
+              }
+            ]
+          },
+          "kind": "function",
+          "def": {
+            "params": [
+              {
+                "kind": "identifier",
+                "name": "value",
+                "optional": false,
+                "tsType": {
+                  "repr": "string",
+                  "kind": "keyword",
+                  "value": "string"
+                }
+              }
+            ],
+            "returnType": {
+              "repr": "string",
+              "kind": "keyword",
+              "value": "string"
+            },
+            "hasBody": true
+          }
+        }
+      ]
+    },
+    {
+      "name": "baz",
+      "declarations": [
+        {
+          "location": {
+            "filename": "file:///mod.ts",
+            "line": 10,
+            "col": 0,
+            "byteIndex": 197
+          },
+          "declarationKind": "export",
+          "jsDoc": {
+            "tags": [
+              {
+                "kind": "deprecated"
+              }
+            ]
+          },
+          "kind": "function",
+          "def": {
+            "params": [],
+            "returnType": {
+              "repr": "void",
+              "kind": "keyword",
+              "value": "void"
+            },
+            "hasBody": true
+          }
+        }
+      ]
+    }
+  ]
+}