Improve UNUSED_ELEMENT documentation

For dart-archive/linter#3513

Change-Id: Ia522fc8958c2c7c48e3366a874ceae28cb9ed6bf
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/253302
Reviewed-by: Brian Wilkerson <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>

Author: srawlins

pkg/analyzer/messages.yaml

@@ -21251,11 +21251,19 @@ HintCode:
       The analyzer produces this diagnostic when a private declaration isn't
       referenced in the library that contains the declaration. The following
       kinds of declarations are analyzed:
-      - Private top-level declarations, such as classes, enums, mixins, typedefs,
-        top-level variables, and top-level functions
-      - Private static and instance methods
+      - Private top-level declarations and all of their members
+      - Private members of public declarations
       - Optional parameters of private functions for which a value is never
-        passed, even when the parameter doesn't have a private name
+        passed
+
+      Not all references to an element will mark it as "used":
+      - Assigning a value to a top-level variable (with a standard `=`
+        assignment, or a null-aware `??=` assignment) does not count as using
+        it.
+      - Refering to an element in a doc comment reference does not count as
+        using it.
+      - Refering to a class, mixin, or enum in the right side of an `is`
+        expression does not count as using it.
 
       #### Example
 

pkg/analyzer/tool/diagnostics/diagnostics.md

@@ -19398,11 +19398,19 @@ _The declaration '{0}' isn't referenced._
 The analyzer produces this diagnostic when a private declaration isn't
 referenced in the library that contains the declaration. The following
 kinds of declarations are analyzed:
-- Private top-level declarations, such as classes, enums, mixins, typedefs,
-  top-level variables, and top-level functions
-- Private static and instance methods
+- Private top-level declarations and all of their members
+- Private members of public declarations
 - Optional parameters of private functions for which a value is never
-  passed, even when the parameter doesn't have a private name
+  passed
+
+Not all references to an element will mark it as "used":
+- Assigning a value to a top-level variable (with a standard `=`
+  assignment, or a null-aware `??=` assignment) does not count as using
+  it.
+- Refering to an element in a doc comment reference does not count as
+  using it.
+- Refering to a class, mixin, or enum in the right side of an `is`
+  expression does not count as using it.
 
 #### Example