Merge pull request #81 from googlesamples/update-docs

Update docs

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/checks/AaptCrash.md.html

@@ -47,8 +47,6 @@
 
     <item name="android:id">@+id/titlebar</item>
     --------------------------------------------
-
-
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Here is the source file referenced above:

docs/checks/AcceptsUserCertificates.md.html

@@ -23,6 +23,8 @@
 Editing
 :   This check runs on the fly in the IDE editor
 See
+:   https://goo.gle/AcceptsUserCertificates
+See
 :   https://developer.android.com/training/articles/security-config#TrustingDebugCa
 Implementation
 :   [Source Code](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/NetworkSecurityConfigDetector.java)
@@ -47,8 +49,6 @@
 
     <certificates src="user"/>
     --------------------------
-
-
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Here is the source file referenced above:

docs/checks/AccidentalOctal.md.html

@@ -43,8 +43,6 @@
 
     versionCode 010
                 ---
-
-
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Here is the source file referenced above:

docs/checks/AdapterViewChildren.md.html

@@ -43,8 +43,6 @@
 
 <ListView
  --------
-
-
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Here is the source file referenced above: