Merge pull request #77 from tnorbye/snapshot13

Update documentation snapshot

Author: tnorbye

docs/README.md.html

@@ -42,6 +42,8 @@
   - [Adding Quick Fixes](api-guide/quickfixes.md.html)
   - [Terminology](api-guide/terminology.md.html)
   - [Partial analysis](api-guide/partial-analysis.md.html)
+  - [Crafting error messages](api-guide/messages.md.html)
+  - [Configuring detectors with options](api-guide/options.md.html)
   - [Frequently Asked Questions](api-guide/faq.md.html)
 * Documents for lint internals, intended for developers of lint
   itself, in the `internal` folder:
@@ -52,6 +54,8 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Documentation History:
+* June 2022: Added documentation for [crafting error
+  messages](messages.md.html)
 * May 2022: Noticed that the document rendering
   was broken, such that many chapters were missing from
   the api-guide: "Adding Quickfixes", "Partial Analysis",

docs/api-guide/messages.md.html

@@ -44,7 +44,7 @@
 should be “Unused import foo”, not “Unused import foo.”
 
 However, if there are multiple sentences in the error message, all sentences
-should be punctuate.
+should be punctuated.
 
 Note that there should be no space before an exclamation (!) or question mark
 (?) sign.
@@ -62,7 +62,7 @@
 cause problems as soon as the line numbers drift after edits to the file), lint
 matches by error message in the file, so the more unique error messages are,
 the better. If all unused import warnings were just “Unused import”, lint would
-match them in order, which often would be the wrong thing.
+match them in order, which often would match the wrong import.
 
 ## Reference Android By Number
 
@@ -103,7 +103,6 @@
 
 * [AccidentalOctal] The leading 0 turns this number into octal which is probably not what was intended (interpreted as 8)
 * [AdapterViewChildren] A list/grid should have no children declared in XML
-* [AddJavascriptInterface] \`WebView.addJavascriptInterface\` should not be called with minSdkVersion < 17 for security reasons: JavaScript can use reflection to manipulate application
 * [AllCaps] Using \`textAllCaps\` with a string (\`has_markup\`) that contains markup; the markup will be dropped by the caps conversion
 * [AllowAllHostnameVerifier] Using the \`AllowAllHostnameVerifier\` HostnameVerifier is unsafe because it always returns true, which could cause insecure network traffic due to trusting TLS/SSL server certificates for wrong hostnames
 * [AlwaysShowAction] Prefer \`ifRoom\` instead of \`always\`

docs/checks/LifecycleAnnotationProcessorWithJava8.md.html

@@ -51,8 +51,8 @@
 Here is an example of lint warnings produced by this check:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~text
 build.gradle:3:Warning: Use the Lifecycle Java 8 API provided by the
-lifecycle-common-java8 library instead of Lifecycle annotations for
-faster incremental build. [LifecycleAnnotationProcessorWithJava8]
+lifecycle-common library instead of Lifecycle annotations for faster
+incremental build. [LifecycleAnnotationProcessorWithJava8]
 
   annotationProcessor "android.arch.lifecycle:compiler:1.1.1"
                       ---------------------------------------

docs/checks/OutdatedLibrary.md.html

@@ -54,8 +54,8 @@
 
 
 build.gradle:8:Error: log4j:log4j version 1.2.12 has been marked as
-outdated by its author and will block publishing to Play Console
-[OutdatedLibrary]
+outdated by its author and will block publishing of your app to Play
+Console [OutdatedLibrary]
 
     compile 'log4j:log4j:1.2.12' // OUTDATED BLOCKING
             --------------------

docs/checks/ReturnFromAwaitPointerEventScope.md.html

@@ -0,0 +1,105 @@
+<meta charset="utf-8">
+(#) Returning from awaitPointerEventScope may cause some input events to be dropped
+
+!!! WARNING: Returning from awaitPointerEventScope may cause some input events to be dropped
+   This is a warning.
+
+Id
+:   `ReturnFromAwaitPointerEventScope`
+Summary
+:   Returning from awaitPointerEventScope may cause some input events to be dropped
+Severity
+:   Warning
+Category
+:   Correctness
+Platform
+:   Any
+Vendor
+:   Jetpack Compose
+Identifier
+:   androidx.compose.ui
+Feedback
+:   https://issuetracker.google.com/issues/new?component=612128
+Affects
+:   Kotlin and Java files and test sources
+Editing
+:   This check runs on the fly in the IDE editor
+Implementation
+:   [Source Code](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:/compose/ui/ui-lint/src/main/java/androidx/compose/ui/lint/ReturnFromAwaitPointerEventScopeDetector.kt)
+Tests
+:   [Source Code](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:/compose/ui/ui-lint/src/test/java/androidx/compose/ui/lint/ReturnFromAwaitPointerEventScopeDetectorTest.kt)
+Copyright Year
+:   2022
+
+Pointer Input events are queued inside awaitPointerEventScope. By using
+the return value of awaitPointerEventScope one might unexpectedly lose
+events. If another awaitPointerEventScope is restarted there is no
+guarantee that the events will persist between those calls. In this case
+you should keep all events inside the awaitPointerEventScope block.
+
+(##) Suppressing
+
+You can suppress false positives using one of the following mechanisms:
+
+* Using a suppression annotation like this on the enclosing
+  element:
+
+  ```kt
+  // Kotlin
+  @Suppress("ReturnFromAwaitPointerEventScope")
+  fun method() {
+     awaitPointerEventScope(...)
+  }
+  ```
+
+  or
+
+  ```java
+  // Java
+  @SuppressWarnings("ReturnFromAwaitPointerEventScope")
+  void method() {
+     awaitPointerEventScope(...);
+  }
+  ```
+
+* Using a suppression comment like this on the line above:
+
+  ```kt
+  //noinspection ReturnFromAwaitPointerEventScope
+  problematicStatement()
+  ```
+
+* 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="ReturnFromAwaitPointerEventScope" 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 'ReturnFromAwaitPointerEventScope'
+  }
+  ```
+  In Android projects this should be nested inside an `android { }`
+  block.
+
+* For manual invocations of `lint`, using the `--ignore` flag:
+  ```
+  $ lint --ignore ReturnFromAwaitPointerEventScope ...`
+  ```
+
+* 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>

docs/checks/RiskyLibrary.md.html

@@ -50,9 +50,9 @@
 
 Here is an example of lint warnings produced by this check:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~text
-build.gradle:7:Error: log4j:log4j version 1.2.13 has an associated
-message from its author that will block publishing to Play Console
-[RiskyLibrary]
+build.gradle:7:Error: log4j:log4j version 1.2.13 has been reported as
+problematic by its author and will block publishing of your app to Play
+Console [RiskyLibrary]
 
     compile 'log4j:log4j:1.2.13' // Critical BLOCKING
             --------------------