Document some lint diagnostics

Change-Id: I38ba6f77a7d25e3f4716c2b2432b790c973c5650
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/390303
Reviewed-by: Phil Quitslund <[email protected]>
Commit-Queue: Brian Wilkerson <[email protected]>

Author: bwilkerson

pkg/analysis_server/test/services/completion/dart/declaration/record_type_test.dart

@@ -60,6 +60,9 @@ suggestions
   toString
     kind: methodInvocation
     returnType: String
+  jsify
+    kind: methodInvocation
+    returnType: JSAny?
   noSuchMethod
     kind: methodInvocation
     returnType: dynamic
@@ -94,6 +97,9 @@ suggestions
   toString
     kind: methodInvocation
     returnType: String
+  jsify
+    kind: methodInvocation
+    returnType: JSAny?
   noSuchMethod
     kind: methodInvocation
     returnType: dynamic
@@ -130,6 +136,9 @@ suggestions
   foo
     kind: methodInvocation
     returnType: void
+  jsify
+    kind: methodInvocation
+    returnType: JSAny?
   noSuchMethod
     kind: methodInvocation
     returnType: dynamic
@@ -160,6 +169,9 @@ suggestions
   toString
     kind: methodInvocation
     returnType: String
+  jsify
+    kind: methodInvocation
+    returnType: JSAny?
   noSuchMethod
     kind: methodInvocation
     returnType: dynamic
@@ -190,6 +202,9 @@ suggestions
   toString
     kind: methodInvocation
     returnType: String
+  jsify
+    kind: methodInvocation
+    returnType: JSAny?
   noSuchMethod
     kind: methodInvocation
     returnType: dynamic
@@ -220,6 +235,9 @@ suggestions
   toString
     kind: methodInvocation
     returnType: String
+  jsify
+    kind: methodInvocation
+    returnType: JSAny?
   noSuchMethod
     kind: methodInvocation
     returnType: dynamic

pkg/analyzer/lib/src/test_utilities/mock_sdk.dart

@@ -1526,6 +1526,23 @@ extension type JSArray<T extends JSAny?>._(List _) implements JSObject {}
 extension type JSTypedArray._(TypedData _) implements JSObject {}
 
 extension type JSUint8List._(Uint8List _) implements JSTypedArray {}
+
+extension JSAnyUtilityExtension on JSAny? {
+  external bool typeofEquals(String typeString);
+
+  external bool instanceof(JSFunction constructor);
+
+  bool instanceOfString(String constructorName) => false;
+
+  @Since('3.4')
+  external bool isA<T extends JSAny?>();
+
+  external Object? dartify();
+}
+
+extension NullableObjectUtilExtension on Object? {
+  external JSAny? jsify();
+}
 ''',
     )
   ],

pkg/analyzer/test/verify_diagnostics_test.dart

@@ -112,6 +112,8 @@ class DocumentationValidator {
     // Doesn't produce a lint for the second example, even though the analyzer
     // does when the example is pasted into a file.
     'LintCode.prefer_inlined_adds_single',
+    // No mock 'test' package, no good library annotations in 'meta'.
+    'LintCode.library_annotations',
     // Produces an unused import diagnostic.
     'LintCode.library_prefixes',
     // Produces an unused element diagnostic.

pkg/analyzer/tool/diagnostics/diagnostics.md

@@ -25993,6 +25993,77 @@ void f() {
 }
 ```
 
+### invalid_runtime_check_with_js_interop_types
+
+_Cast from '{0}' to '{1}' casts a Dart value to a JS interop type, which might
+not be platform-consistent._
+
+_Cast from '{0}' to '{1}' casts a JS interop value to a Dart type, which might
+not be platform-consistent._
+
+_Cast from '{0}' to '{1}' casts a JS interop value to an incompatible JS interop
+type, which might not be platform-consistent._
+
+_Runtime check between '{0}' and '{1}' checks whether a Dart value is a JS
+interop type, which might not be platform-consistent._
+
+_Runtime check between '{0}' and '{1}' checks whether a JS interop value is a
+Dart type, which might not be platform-consistent._
+
+_Runtime check between '{0}' and '{1}' involves a non-trivial runtime check
+between two JS interop types that might not be platform-consistent._
+
+_Runtime check between '{0}' and '{1}' involves a runtime check between a JS
+interop value and an unrelated JS interop type that will always be true and won't check the underlying type._
+
+#### Description
+
+The analyzer produces this diagnostic when an `is` test has either:
+- a JS interop type on the right-hand side, whether directly or as a type
+  argument to another type, or
+- a JS interop value on the left-hand side.
+
+#### Examples
+
+The following code produces this diagnostic because the JS interop type
+`JSBoolean` is on the right-hand side of an `is` test:
+
+```dart
+import 'dart:js_interop';
+
+bool f(Object b) => [!b is JSBoolean!];
+```
+
+The following code produces this diagnostic because the JS interop type
+`JSString` is used as a type argument on the right-hand side of an `is`
+test:
+
+```dart
+import 'dart:js_interop';
+
+bool f(List<Object> l) => [!l is List<JSString>!];
+```
+
+The following code produces this diagnostic because the JS interop value
+`a` is on the left-hand side of an `is` test:
+
+```dart
+import 'dart:js_interop';
+
+bool f(JSAny a) => [!a is String!];
+```
+
+#### Common fixes
+
+Use a JS interop helper, such as `isA`, to check the underlying type of
+JS interop values:
+
+```dart
+import 'dart:js_interop';
+
+void f(Object b) => b.jsify()?.isA<JSBoolean>();
+```
+
 ### invalid_use_of_do_not_submit_member
 
 _Uses of '{0}' should not be submitted to source control._
@@ -26046,6 +26117,43 @@ void emulateCrashWithOtherFunctionality() {
 }
 ```
 
+### library_annotations
+
+_This annotation should be attached to a library directive._
+
+#### Description
+
+The analyzer produces this diagnostic when an annotation that applies to
+a whole library isn't associated with a `library` directive.
+
+#### Example
+
+The following code produces this diagnostic because the `TestOn`
+annotation, which applies to the whole library, is associated with an
+`import` directive rather than a `library` directive:
+
+```dart
+[!@TestOn('browser')!]
+
+import 'package:test/test.dart';
+
+void main() {}
+```
+
+#### Common fixes
+
+Associate the annotation with a `library` directive, adding one if
+necessary:
+
+```dart
+@TestOn('browser')
+library;
+
+import 'package:test/test.dart';
+
+void main() {}
+```
+
 ### library_names
 
 _The library name '{0}' isn't a lower\_case\_with\_underscores identifier._
@@ -28251,6 +28359,59 @@ Future<void> f() async {
 Future<int> g() => Future.value(0);
 ```
 
+### unintended_html_in_doc_comment
+
+_Angle brackets will be interpreted as HTML._
+
+#### Description
+
+The analyzer produces this diagnostic when a documentation comment
+contains angle bracketed text (`<...>`) that isn't one of the allowed
+exceptions.
+
+Such text is interpreted by markdown to be an HTML tag, which is rarely
+what was intended.
+
+See the [lint rule description](https://dart.dev/tools/linter-rules/unintended_html_in_doc_comment)
+for the list of allowed exceptions.
+
+#### Example
+
+The following code produces this diagnostic because the documentation
+comment contains the text `<int>`, which isn't one of the allowed
+exceptions:
+
+```dart
+/// Converts a List[!<int>!] to a comma-separated String.
+String f(List<int> l) => '';
+```
+
+#### Common fixes
+
+If the text was intended to be part of a code span, then add backticks
+around the code:
+
+```dart
+/// Converts a `List<int>` to a comma-separated String.
+String f(List<int> l) => '';
+```
+
+If the text was intended to be part of a link, then add square brackets
+around the code:
+
+```dart
+/// Converts a [List<int>] to a comma-separated String.
+String f(List<int> l) => '';
+```
+
+If the text was intended to be printed as-is, including the angle
+brackets, then add backslash escapes before the angle brackets:
+
+```dart
+/// Converts a List\<int\> to a comma-separated String.
+String f(List<int> l) => '';
+```
+
 ### unnecessary_brace_in_string_interps
 
 _Unnecessary braces in a string interpolation._
@@ -28481,6 +28642,39 @@ class C {
 }
 ```
 
+### unnecessary_library_name
+
+_Library names are not necessary._
+
+#### Description
+
+The analyzer produces this diagnostic when a `library` directive specifies
+a name.
+
+#### Example
+
+The following code produces this diagnostic because the `library`
+directive includes a name:
+
+```dart
+library [!some.name!];
+
+class C {}
+```
+
+#### Common fixes
+
+Remove the name from the `library` directive:
+
+```dart
+library;
+
+class C {}
+```
+
+If the library has any parts, then any `part of` declarations that use
+the library name should be updated to use the URI of the library instead.
+
 ### unnecessary_new
 
 _Unnecessary 'new' keyword._
@@ -29522,6 +29716,35 @@ class B extends A {
 }
 ```
 
+### use_truncating_division
+
+_Use truncating division._
+
+#### Description
+
+The analyzer produces this diagnostic when the result of dividing two
+numbers is converted to an integer using `toInt`.
+
+Dart has a built-in integer division operator that is both more efficient
+and more concise.
+
+#### Example
+
+The following code produces this diagnostic because the result of dividing
+`x` and `y` is converted to an integer using `toInt`:
+
+```dart
+int divide(int x, int y) => [!(x / y).toInt()!];
+```
+
+#### Common fixes
+
+Use the integer division operator (`~/`):
+
+```dart
+int divide(int x, int y) => x ~/ y;
+```
+
 ### valid_regexps
 
 _Invalid regular expression syntax._