Merge pull request #60 from tnorbye/snapshot8

Update lint documentation snapshot

Author: tnorbye

docs/api-guide.html

@@ -6,8 +6,8 @@
 enforce. There are many examples of these, along with existing lint
 checks:
 
-* `@VisibleForTesting`: this private API should only be accessed
-  from outside this package from unit tests
+* `@VisibleForTesting`: this API is considered private, and has been
+   exposed only for unit testing purposes
 * `@CheckResult`: anyone calling this method is expected to do
   something with the return value
 * `@CallSuper`: anyone overriding this method must also invoke `super`
@@ -190,10 +190,11 @@
 Note also that this would have worked if the annotation had been
 inherited from a super method instead of being explicitly set here.
 
-Lint uses this mechanism for example for its resource type lint check
-which makes sure that if a method has been annotated with say
-`@DrawableRes`, that any return values are not of some incompatible
-esource type (such as `@StringRes`).
+One usage of this mechanism in Lint is the enforcement of return values
+in methods. For example, if a method has been marked with
+`@DrawableRes`, Lint will make sure that the returned value of that
+method will not be of an incompatible resource type (such as
+`@StringRes`).
 
 ### Handling Usage Types
 
@@ -393,11 +394,12 @@
 deliberately supporting the operation, not just from tests. If
 annotations were always inherited, you would have to create some sort
 of annotation to "revert" the semantics, e.g.
-`@VisibleNotJustForTesting`, which would be ... anoying.
+`@VisibleNotJustForTesting`, which would require a lot of noisy
+annotations.
 
-Lint let's you choose what the semantics are for each annotation. For
-example, the lint check which enforces the `@VisibleForTesting` and
-`@RestrictTo` annotations handles it like this:
+Lint lets you specify the inheritance behavior of individual
+annotations. For example, the lint check which enforces the
+`@VisibleForTesting` and `@RestrictTo` annotations handles it like this:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
 override fun inheritAnnotation(annotation: String): Boolean {

docs/api-guide/annotations.md.html

@@ -7,6 +7,11 @@
 
 **7.1**
 
+* Lint now bundles IntelliJ version 2021.1 and Kotlin compiler version 1.5.30.
+  You may see minor API changes in these dependencies. For example,
+  the Kotlin UAST class `KotlinUMethod` changed packages from
+  `org.jetbrains.uast.kotlin.declarations` to `org.jetbrains.uast.kotlin`.
+
 * The default behaviour of ResourceXmlDetector will change.
   It will skip res/raw folder and you have to override appliesTo method
   if you want your Lint checks to run there.
@@ -101,15 +106,7 @@
 * Partial analysis. Lint's architecture has changed to support better
   scalability across large projects, where module results can be
   cached, etc. See the api-guide's dedicated chapter for more details.
-  It is enabled by default starting in AGP 7.0.0-alpha13, but you can
-  disable it by adding
-
-      `android.enableParallelLint=false`
-
-  to your `gradle.properties` file. If you want to debug your lint check
-  you may want to also set
-
-      `android.experimental.runLintInProcess=true`
+  It is enabled by default starting in AGP 7.0.0-alpha13.
 
 * Issue registration now takes an optional `Vendor` property, where you
   can specify information about which company or team provided this

docs/api-guide/changes.md.html

@@ -108,15 +108,18 @@
 are a number of different types of test source files, such as for
 Kotlin files, manifest files, icons, property files, and so on.
 
-Using test file descriptors like this has a number of advantages
-over the traditional approach of checking in test files as sources:
+Using test file descriptors like this to **describe** an input file has
+a number of advantages over the traditional approach of checking in
+test files as sources:
 
 * Everything is kept together, so it's easier to look at a test and see
   what it analyzes and what the expected results are. This is
   particularly important for complex lint checks which test a lot of
   scenarios. As of this writing, `ApiDetectorTest` has 157 individual
   unit tests.
 
+  ![Multiple test files shown inline](nested-test-files.png)
+
 * Lint can provide a DSL to construct test files easily. For example,
   `projectProperties().compileSdk(17)` and
   `manifest().minSdk(5).targetSdk(17)` construct a `project.properties`
@@ -136,14 +139,19 @@
   code and figure out what the class file should be named and where to
   place it.
 
-* We can easily “parameterize” our test files. For example, if you
-  want to run your unit test against a 100K json file, you can
-  construct it programmatically; you don't have to check one in.
+* We can easily “parameterize” our test files. For example, if you want
+  to run your unit test against a 100K json file, you can construct it
+  programmatically; you don't have to check one in. As another example
+  you can programmatically create a number of repetitive scenarios.
+
+* Since test sources often (deliberately!) have errors in them (which
+  is relevant when lint is unning on the fly inside the IDE editor),
+  this sometimes causes problems with the tooling; for example, some
+  code review tools will flag “disallowed” constructs or things like
+  tabs or trailing spaces, which may be deliberate in a lint unit test.
 
-* Since test sources often (deliberately!) have errors in them, this
-  sometimes causes problems with the tooling; for example, some code
-  review tools will flag “disallowed” constructs or things like tabs or
-  trailing spaces, which may be deliberate in a lint unit test.
+* You can test running in single-file mode, which is how lint is run
+  on the fly in the editor.
 
 * Lint originally checked in test sources as individual files.
   Unfortunately over time, source files ended up getting reused by
@@ -157,6 +165,12 @@
 
   ![Screenshot of nested highlighting](nested-syntax-highlighting.png)
 
+* Finally, but most importantly, with the descriptors of your test
+  scenarios, lint can re-run your tests under a number of different
+  scenarios, including modifying your source files and project layout.
+  This concept is documented in more detail in the [test
+  modes](test-modes.md.html) chapter.
+
 ## Trimming indents?
 
 Notice how in the above Kotlin unit tests we used raw strings, **and**
@@ -303,7 +317,7 @@
 
 Here's an example of a test failure for an unresolved import:
 
-```
+```text
 java.lang.IllegalStateException:
 app/src/com/example/MyDiffUtilCallbackJava.java:4: Error:
 Couldn't resolve this import [LintError]
@@ -375,6 +389,10 @@
 files (since a single source file can create multiple class files, and
 for Kotlin, some META-INF data).
 
+Here's an example of a lint test which is using `bytecode(...)` to
+describe binary files:
+[](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/client/api/JarFileIssueRegistryTest.kt?q=testNewerLintBroken)
+
 Initially, you just specify the sources, and when no binary data
 has been provided, lint will instead attempt to compile the sources
 and emit the full test file registration.
@@ -384,33 +402,6 @@
 project it will only provide the binaries, not the sources, for
 upstream modules.)
 
-## Test Modes
-
-"Describing” your source inputs using `TestFile` objects like this
-instead of just checking in your test files as real `.kt` and `.java`
-has a number of advantages:
-
-* It's really easy to see what a test is doing; all the test files are
-  placed right next to each other, with full syntax highlighting if you
-  open the test cases in IntelliJ; example:
-
-  ![Figure [screen]: Nested syntax highlighting](nested-test-files.png)
-
-* You can test handling broken sources (which is relevant when lint is
-  running on the fly inside the IDE editor).
-
-* You can test running in single-file mode, which is how lint is run
-  on the fly in the editor.
-
-* You can create test files programmatically if you want to cover
-  a number of repetitive scenarios
-
-* Finally, but most importantly, with the descriptors of your test
-  scenarios, lint can re-run your tests under a number of different
-  scenarios, including modifying your source files and project layout.
-  This concept is documented in more detail in the [test
-  modes](test-modes.md.html) chapter.
-
 ## My Detector Isn't Invoked From a Test!
 
 One common question we hear is

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

@@ -1,155 +1,7 @@
 <meta charset="utf-8">
-(#) AllowBackup/FullBackupContent Problems
+(#) AllowBackup
 
-!!! WARNING: AllowBackup/FullBackupContent Problems
-   This is a warning.
+The issue for this id has been deleted or marked obsolete and can now be
+ignored.
 
-Id
-:   `AllowBackup`
-Summary
-:   AllowBackup/FullBackupContent Problems
-Severity
-:   Warning
-Category
-:   Security
-Platform
-:   Android
-Vendor
-:   Android Open Source Project
-Feedback
-:   https://issuetracker.google.com/issues/new?component=192708
-Affects
-:   Manifest files
-Editing
-:   This check runs on the fly in the IDE editor
-See
-:   https://developer.android.com/guide/topics/data/autobackup
-See
-:   https://developer.android.com/reference/android/R.attr.html#allowBackup
-Implementation
-:   [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-checks/src/main/java/com/android/tools/lint/checks/ManifestDetector.kt)
-Tests
-:   [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/ManifestDetectorTest.kt)
-
-The `allowBackup` attribute determines if an application's data can be
-backed up and restored. It is documented at
-https://developer.android.com/reference/android/R.attr.html#allowBackup
-
-By default, this flag is set to `true` which means application data can
-be backed up and restored by the OS. Setting `allowBackup="false"` opts
-the application out of being backed up and so users can't restore data
-related to it when they go through the device setup wizard.
-
-Allowing backups may have security consequences for an application.
-Currently `adb backup` allows users who have enabled USB debugging to
-copy application data off of the device. Once backed up, all application
-data can be read by the user. `adb restore` allows creation of
-application data from a source specified by the user. Following a
-restore, applications should not assume that the data, file permissions,
-and directory permissions were created by the application itself.
-
-To fix this warning, decide whether your application should support
-backup, and explicitly set `android:allowBackup=(true|false)"`.
-
-If not set to false, and if targeting API 23 or later, lint will also
-warn that you should set `android:fullBackupContent` or
-`android:fullBackupOnly` to configure auto backup.
-
-!!! Tip
-   This lint check has an associated quickfix available in the IDE.
-
-(##) Example
-
-Here is an example of lint warnings produced by this check:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~text
-AndroidManifest.xml:8:Warning: Should explicitly set android:allowBackup
-to true or false (it's true by default, and that can have some security
-implications for the application's data) [AllowBackup]
-
-    &lt;application
-     -----------
-
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Here is the source file referenced above:
-
-`AndroidManifest.xml`:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~xml linenumbers
-&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="test.bytecode"
-    android:versionCode="1"
-    android:versionName="1.0" &gt;
-
-    &lt;uses-sdk android:minSdkVersion="14" /&gt;
-
-    &lt;application
-        android:icon="@drawable/ic_launcher"
-        android:label="@string/app_name" &gt;
-    &lt;/application&gt;
-
-&lt;/manifest&gt;
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can also visit the
-[source code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/ManifestDetectorTest.kt)
-for the unit tests for this check to see additional scenarios.
-
-The above example was automatically extracted from the first unit test
-found for this lint check, `ManifestDetector.testAllowBackup`.
-To report a problem with this extracted sample, visit
-https://issuetracker.google.com/issues/new?component=192708.
-
-(##) Suppressing
-
-You can suppress false positives using one of the following mechanisms:
-
-* Adding the suppression attribute `tools:ignore="AllowBackup"` on the
-  problematic XML element (or one of its enclosing elements). You may
-  also need to add the following namespace declaration on the root
-  element in the XML file if it's not already there:
-  `xmlns:tools="http://schemas.android.com/tools"`.
-
-  ```xml
-  &lt;?xml version="1.0" encoding="UTF-8"?&gt;
-  &lt;manifest xmlns:tools="http://schemas.android.com/tools"&gt;
-      ...
-      &lt;application tools:ignore="AllowBackup" .../&gt;
-    ...
-  &lt;/manifest&gt;
-  ```
-
-* Using a special `lint.xml` file in the source tree which turns off
-  the check in that folder and any sub folder. A simple file might look
-  like this:
-  ```xml
-  &lt;?xml version="1.0" encoding="UTF-8"?&gt;
-  &lt;lint&gt;
-      &lt;issue id="AllowBackup" severity="ignore" /&gt;
-  &lt;/lint&gt;
-  ```
-  Instead of `ignore` you can also change the severity here, for
-  example from `error` to `warning`. You can find additional
-  documentation on how to filter issues by path, regular expression and
-  so on
-  [here](https://googlesamples.github.io/android-custom-lint-rules/usage/lintxml.md.html).
-
-* In Gradle projects, using the DSL syntax to configure lint. For
-  example, you can use something like
-  ```gradle
-  lintOptions {
-      disable 'AllowBackup'
-  }
-  ```
-  In Android projects this should be nested inside an `android { }`
-  block.
-
-* For manual invocations of `lint`, using the `--ignore` flag:
-  ```
-  $ lint --ignore AllowBackup ...`
-  ```
-
-* Last, but not least, using baselines, as discussed
-  [here](https://googlesamples.github.io/android-custom-lint-rules/usage/baselines.md.html).
-
-<!-- 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>
+(Additional metadata not available.)<!-- 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/AllowBackup.md.html

@@ -42,10 +42,10 @@
 Here is an example of lint warnings produced by this check:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~text
 build.gradle:7:Warning: A newer version of
-com.android.tools.build:gradle than 2.4.0-alpha3 is available:
-3.5.0-alpha10 [AndroidGradlePluginVersion]
+com.android.tools.build:gradle than 3.4.0-alpha3 is available:
+3.6.0-alpha01 [AndroidGradlePluginVersion]
 
-    classpath 'com.android.tools.build:gradle:2.4.0-alpha3'
+    classpath 'com.android.tools.build:gradle:3.4.0-alpha3'
     -------------------------------------------------------
 
 
@@ -61,7 +61,7 @@
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:2.4.0-alpha3'
+        classpath 'com.android.tools.build:gradle:3.4.0-alpha3'
     }
 }
 dependencies {