Update documentation snapshot

...from latest manually edited docs in the lint source tree.

Author: tnorbye

docs/api-guide/basics.md.html

@@ -714,10 +714,11 @@
    example layouts are processed before value files like translations)
 3. Kotlin and Java files
 4. Bytecode (local `.class` files and library `.jar` files)
-5. Gradle files
-6. Other files
-7. ProGuard files
-8. Property Files
+5. TOML files
+6. Gradle files
+7. Other files
+8. ProGuard files
+9. Property Files
 
 Similarly, lint will always process libraries before the modules
 that depend on them.

docs/api-guide/changes.md.html

@@ -5,6 +5,58 @@
 information about user visible changes to lint, see the User
 Guide.
 
+**8.2**
+
+* For unit tests, you can now specify the language level to be used
+  for Kotlin and Java. For example, if your unit test is using Java
+  records, add `.javaLanguageLevel("17")` to your `lint()` test
+  configuration.
+
+**8.1**
+
+* The [data flow analyzer](dataflow-analyzer.md.html) has been
+  improved; in addition to fixing a few bugs, there are a couple of
+  new convenience sub classes which makes common tasks easier to
+  accomplish; see the documentation for `TargetMethodDataFlowAnalyzer`
+  for example.
+
+* The new `mavenLibrary` (and `binaryStub`) test files make it simple
+  to create binary stub files in your tests, without having to perform
+  compilation and check in base64 and gzip encoded test files. When
+  your detector resolves references, the PSI elements you get back
+  differ whether you're calling into source or into binary (jar/.class
+  file) elements, so testing both (which the new test files automate
+  using test modes) is helpful. More information about this is
+  available in [](unit-testing.md.html).
+
+* Lint now supports analyzing TOML files. There is a new
+  Scope.TOML_FILE detectors can register an interest in, a new
+  TomlScanner interface to implement for visitTomlDocument callbacks,
+  etc. From a GradleScanner, you can directly resolve version catalog
+  libraries via lookup methods on the GradleContext.
+
+* Lint's “diff” output for unit test verification has been improved;
+  it's now smarter about combining nearby chunks. (This should not
+  break existing tests; the test infrastructure will try the older
+  format as a fallback if the diffs aren't matching for the new
+  format.)
+
+* Lint contains JVM 17 bytecode. You will now need to use JDK 17+
+  when compiling custom Lint checks. You should also configure
+  the Kotlin compiler to target JVM 17, otherwise you may see errors
+  when calling inline functions declared in Lint, UAST, or PSI.
+
+* Lint's testing infrastructure now looks not just for test/
+  but also androidTest/ and testFixtures/ to set the corresponding
+  source set type on each test context.
+
+**8.0**
+
+* A new testmode which makes sure lint checks are all suppressible.
+  It analyzes the reported error locations from the expected test
+  output, and inserts suppress annotations in XML, Kotlin and Java
+  files and makes sure that the corresponding warnings disappear.
+
 **7.4**
 
 * Annotation detectors can now specify just an annotation name instead

docs/api-guide/dataflow-analyzer.md.html

@@ -44,6 +44,13 @@
 `DataFlowAnalyzer` class, and override one or more of its callbacks,
 and then tell it to analyze a method scope.
 
+!!! Tip
+   In recent versions of lint, there is a new special subclass of the
+   `DataFlowAnalyzer`, `TargetMethodDataFlowAnalyzer`, which makes it
+   easier to write flow analyzers where you are looking for a specific
+   “cleanup” or close function invoked on an instance. See the separate
+   section on `TargetMethodDataFlowAnalyzer` below for more information.
+
 For the above transaction scenario, it might look like this:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin linenumbers
@@ -303,6 +310,12 @@
 case you want to perform additional analysis to track field values; see
 the next section.
 
+!!! Tip
+   There is a special subclass of the `DataFlowAnalyzer`, called
+   `EscapeCheckingDataFlowAnalyzer`, which you can extend instead. This
+   handles recording all the scenarios where the instance escapes from
+   the method, and at the end you can just check its `escaped` property.
+
 ## Non Local Analysis
 
 In the above examples, if we found that the value escaped via a return
@@ -347,4 +360,40 @@
 [Source](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-checks/src/main/java/com/android/tools/lint/checks/SliceDetector.kt)
 [Test](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/SliceDetectorTest.kt)
 
+## TargetMethodDataFlowAnalyzer
+
+The `TargetMethodDataFlowAnalyzer` is a special subclass of the
+`DataFlowAnalyzer` which makes it simple to see if you eventually wind up
+calling a target method on a particular instance. For example, calling
+`close` on a file that was opened, or calling `start` on an animation you
+created.
+
+In addition, there is an extension function on `UMethod` which visits
+this analyzer, and then checks for various conditions, e.g. whether the
+instance “escaped” (for example by being stored in a field or passed to
+another method), in which case you probably don't want to conclude (and
+report) that the close method is never called. It also handles failures
+to resolve, where it remembers whether there was a resolve failure, and
+if so it looks to see if it finds a likely match (with the same name as
+the target function), and if so also makes sure you don't report a false
+positive.
+
+A simple way to do this is as follows:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin linenumbers
+val targets = mapOf("show" to listOf("android.widget.Toast",
+      "com.google.android.material.snackbar.Snackbar")
+val analyzer = TargetMethodDataFlowAnalyzer.create(node, targets)
+if (method.isMissingTarget(analyzer)) {
+    context.report(...)
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can subclass `TargetMethodDataFlowAnalyzer` directly and override the
+`getTargetMethod` methods and any other UAST visitor methods if you want
+to customize the behavior further.
+
+One advantage of using the `TargetMethodDataFlowAnalyzer` is that it also
+correctly handles method references.
+
 <!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js" charset="utf-8"></script><script src="https://morgan3d.github.io/markdeep/latest/markdeep.min.js" charset="utf-8"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

docs/api-guide/messages.md.html

@@ -89,6 +89,18 @@
   ”Hello.“ to ”Hello, world!“ is compatible.
 * Adding a prefix
 
+## Plurals
+
+Avoid trying to make sentences gramatically correct and flexible by
+using constructs like ”(s)“ to quantity strings. In other words,
+instead of for example saying
+
+    *”register your receiver(s) in the manifest“*
+
+just use the plural form,
+
+    *”register your receivers in the manifest“*
+
 ## Examples
 
 Here are some examples from lint's built-in checks. Note that these are not

docs/api-guide/test-modes.md.html

@@ -517,4 +517,18 @@
 string resources, and will convert regular text into `CDATA` and makes
 sure the results continue to be the same.
 
+### Suppressible Mode
+
+Users should be able to ignore lint warnings by inserting suppress annotations
+(in Kotlin and Java), and via `tools:ignore` attributes in XML files.
+
+This normally works for simple checks, but if you are combining results from
+different parts of the code, or for example caching locations and reporting
+them later, this is sometimes broken.
+
+This test mode looks at the reported warnings from your unit tests, and then
+for each one, it looks up the corresponding error location's source file, and
+inserts a suppress directive at the nearest applicable location. It then
+re-runs the analysis, and makes sure that the warning no longer appears.
+
 <!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js" charset="utf-8"></script><script src="https://morgan3d.github.io/markdeep/latest/markdeep.min.js" charset="utf-8"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

docs/api-guide/unit-testing.md.html

@@ -338,10 +338,65 @@
 
 ## Binary and Compiled Source Files
 
-If you need to use binaries in your unit tests, there is
-a special test file type for that: base64gzip. Here's an
-example from a lint check which tries to recognize usage
-of Cordova in the bytecode:
+If you need to use binaries in your unit tests, there are two options:
+
+ 1. base64gzip
+ 2. API stubs
+
+If you want to analyze bytecode of method bodies, you'll need to use
+the first option.
+
+The first type requires you to actually compile your test file into a
+set of .class files, and check those in as a gzip-compressed, base64
+encoded string. Lint has utilities for this; see the next section.
+
+The second option is using API stubs. For simple stub files (where you
+only need to provide APIs you'll call as binaries, but not code), lint
+can produce the corresponding bytecode on the fly, so you don't need
+to pre-create binary contents of the class. This is particularly
+helpful when you just want to create stubs for a library your lint
+check is targeting and you want to make sure the detector is seeing
+the same types of elements as it will when analyzing real code outside
+of tests (since there is a difference between resolving into APIs from
+source and form binaries; when you're analyzing calls into source, you
+can access for example method bodies, and this isn't available via
+UAST from byte code.)
+
+These test files also let you specify an artifact name instead of a
+jar path, and lint will use this to place the jar in a special place
+such that it recognizes it (via `JavaEvaluator.findOwnerLibrary`) as
+belonging to this library.
+
+Here's an example of how you can create one of these binary stub
+files:
+
+```
+fun testIdentityEqualsOkay() {
+    lint().files(
+        kotlin(
+            "/*test contents here *using* some recycler view APIs*/"
+        ).indented(),
+        mavenLibrary(
+            "androidx.recyclerview:recyclerview:1.0.0",
+            java(
+                """
+                    package androidx.recyclerview.widget;
+                    public class DiffUtil {
+                        public abstract static class ItemCallback<T> {
+                            public abstract boolean areItemsTheSame(T oldItem, T newItem);
+                            public abstract boolean areContentsTheSame(T oldItem, T newItem);
+                        }
+                    }
+                    """
+            ).indented()
+        )
+    ).run().expect(
+```
+
+## Base64-encoded gzipped byte code
+
+Here's an example from a lint check which tries to recognize usage of
+Cordova in the bytecode:
 
 ```
 fun testVulnerableCordovaVersionInClasses() {
@@ -411,4 +466,26 @@
 Dependencies and Stubs“ section above, as well as the [frequently asked
 questions](faq.md.html).
 
+## Language Level
+
+Lint will analyze Java and Kotlin test files using its own default
+language levels. If you need a higher (or lower) language level in order
+to test a particular scenario, you can use the `kotlinLanguageLevel`
+and `javaLanguageLevel` setter methods on the lint test configuration.
+Here's an example of a unit test setup for Java records:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
+    lint()
+      .files(
+        java("""
+            record Person(String name, int age) {
+            }
+            """)
+          .indented()
+      )
+      .javaLanguageLevel("17")
+      .run()
+      .expect(...)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 <!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js" charset="utf-8"></script><script src="https://morgan3d.github.io/markdeep/latest/markdeep.min.js" charset="utf-8"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

docs/internal/document-checks.md.html

@@ -27,6 +27,10 @@
 --builtins                        Generate documentation for the built-in
                                   issues. This is implied if --lint-jars is
                                   not specified
+--gmaven                          Generate documentation for the lint checks
+                                  found on maven.google.com.
+--maven-central                   Generate documentation for a few well known
+                                  lint libraries distributed on Maven Central.
 --lint-jars <jar-path>            Read the lint issues from the specific path
                                   (separated by : of custom jar files
 --issues [issues]                 Limits the issues documented to the specific
@@ -85,34 +89,6 @@
 checks. If your lint check are packaged as an AAR file, you can unzip
 this file to find `lint.jar` inside.
 
-## Generating AndroidX documentation
-
-To generate the AndroidX documentation, check out the androidx
-repository into `$ANDROIDX_REPO`; then run
-
-```shell
-$ cd $ANDROIDX_REPO/frameworks/support
-$ ./gradlew createArchive
-```
-
-This will build all the lint custom checks in AndroidX. Then invoke the
-documentation generation tool like this:
-
-```shell
-$ export ANDROID_URI_PREFIX=https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:
-
-$ lint \
-    --generate-docs \
-    --output /tmp/lint-docs/ \
-    --lint-jars $ANDROIDX_REPO/out \
-    --source-url $ANDROID_URI_PREFIX $ANDROIDX_REPO/frameworks/support \
-    --test-url $ANDROID_URI_PREFIX $ANDROIDX_REPO/frameworks/support
-```
-
-If you want to include all the built-in Studio checks as well into a
-documentation set containing both, merge in the `--builtins` and
-`--source-url` and `--test-url` flags from above.
-
 ## Special Conventions
 
 If you include a test URL search path (and note that the URI prefix is

docs/internal/verify.md.html

@@ -46,7 +46,8 @@
 ```ksh
 runGradleForAndroidX() {
     CUSTOM_REPO=$ADT_SOURCE_TREE/out/repo \
-    GRADLE_PLUGIN_VERSION=7.1.0-dev \
+    GRADLE_PLUGIN_VERSION=8.0.0-dev \
+    LINT_VERSION=31.0.0-dev \
     GRADLE_PLUGIN_REPO=$ADT_SOURCE_TREE/out/repo:$ADT_SOURCE_TREE/prebuilts/tools/common/m2/repository \
     $ADT_SOURCE_TREE/tools/gradlew --parallel ${@}
 }
@@ -64,6 +65,11 @@
 flag with `--no-daemon -Dorg.gradle.debug=true`, run the build, and
 create a Remote configuration in IntelliJ and use it to attach.
 
+You can also run `gwx updateLintBaseline` to have lint successfully
+run all targets and update the baselines and then inspect the diffs if
+you've added/updated lint checks and don't want it to stop after the
+first new (and correct) failure.
+
 ## Testing against Android Platform
 
 Lint is run as part of the Android platform builds, including a number of custom lint checks specific to the platform.

docs/usage/agp-dsl.md.html

@@ -135,19 +135,19 @@
   standard output or standard error streams respectively. In recent
   versions of lint, this will also imply `textReport true`.
 
-  Example: `textOutput file(“$reportsDir/lint-results.txt”)`
+  Example: `textOutput file(“$buildDir/reports/lint-results.txt”)`
 
 `xmlReport` *true or false*
 : Whether lint should generate an XML report. If you don't specify a
   location using `xmlOutput`, lint will default to
   `lint-results-`*$variant*`.xml` in $module`/build/reports/, such as
   `app/build/reports/lint-results-debug.xml`.
 
-`xmlOutput file("$reportsDir/lint-report.xml")`
+`xmlOutput file("$buildDir/reports/lint-report.xml")`
 : Where lint should write its XML report. In recent versions of lint,
   this will also imply `xmlReport true`.
 
-  Example: `xmlOutput file("$reportsDir/lint-results.xml")`
+  Example: `xmlOutput file("$buildDir/reports/lint-results.xml")`
 
 `htmlReport` *true or false*
 : Whether lint should generate an HTML report, with issue explanations,
@@ -162,7 +162,7 @@
   chapter](variables.md.html) for some flags to configure the HTML
   report.
 
-  Example: `htmlOutput file(“$reportsDir/lint-results.html”)`
+  Example: `htmlOutput file(“$buildDir/reports/lint-results.html”)`
 
 `sarifReport` *true or false*
 : Whether lint should generate a
@@ -176,7 +176,7 @@
 : Where lint should write its HTML SARIF. In recent versions of lint,
   this will also imply `sarifReport true`.
 
-  Example: `sarifOutput file("$reportsDir/lint-report.sarif.json")`
+  Example: `sarifOutput file("$buildDir/reports/lint-report.sarif.json")`
 
 `quiet` *true or false*
 : Whether lint should limit its diagnostic output. *False by default.*