Updated issue documentation to include sorting and AndroidX

Author: tnorbye

docs/README.md

@@ -10,3 +10,6 @@ Let's go there right now: [Link](README.md.html)
 
 There is also a pre-rendered HTML version of the API Guide
 [here](book.html) suitable for online hosting.
+
+Finally, a (usually recent) snapshot of these docs are hosted
+[here](http://googlesamples.github.io/android-custom-lint-rules/).

docs/README.md.html

@@ -44,6 +44,7 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Documentation History:
+* May 2021: Adding documentation for individual lint issues
 * March 2021: Initial version
 
 <!-- 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.html

@@ -127,8 +127,9 @@
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#frequentlyaskedquestions//howdoilookupifaclassisasubclassofanother?" class="level3"><span class="tocNumber">8.0.13&nbsp; </span>How do I look up if a class is a subclass of another?</a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#frequentlyaskedquestions//howdoiknowwhichparameteracallargumentcorrespondsto?" class="level3"><span class="tocNumber">8.0.14&nbsp; </span>How do I know which parameter a call argument corresponds to?</a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#frequentlyaskedquestions//howcanmylintcheckstargettwodifferentversionsoflint?" class="level3"><span class="tocNumber">8.0.15&nbsp; </span>How can my lint checks target two different versions of lint?</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#frequentlyaskedquestions//howdoicheckoutthecurrentlintsourcecode?" class="level3"><span class="tocNumber">8.0.16&nbsp; </span>How do I check out the current lint source code?</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#frequentlyaskedquestions//wheredoifindexamplesoflintchecks?" class="level3"><span class="tocNumber">8.0.17&nbsp; </span>Where do I find examples of lint checks?</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#frequentlyaskedquestions//canimakemylintcheck%E2%80%9Cnotsuppressible?%E2%80%9D" class="level3"><span class="tocNumber">8.0.16&nbsp; </span>Can I make my lint check “not suppressible?”</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#frequentlyaskedquestions//howdoicheckoutthecurrentlintsourcecode?" class="level3"><span class="tocNumber">8.0.17&nbsp; </span>How do I check out the current lint source code?</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#frequentlyaskedquestions//wheredoifindexamplesoflintchecks?" class="level3"><span class="tocNumber">8.0.18&nbsp; </span>Where do I find examples of lint checks?</a><br>
 <a href="#appendix:recentchanges" class="level1"><span class="tocNumber">9&nbsp; </span>Appendix: Recent Changes</a><br>
 <a href="#appendix:environmentvariablesandsystemproperties" class="level1"><span class="tocNumber">10&nbsp; </span>Appendix: Environment Variables and System Properties</a><br>
 &nbsp;&nbsp;<a href="#appendix:environmentvariablesandsystemproperties/environmentvariables" class="level2"><span class="tocNumber">10.1&nbsp; </span>Environment Variables</a><br>
@@ -3332,7 +3333,7 @@
   This means that instead, you need to aggregate data along the way.
   For example, the way lint handles the version check method lookup is
   to look for SDK_INT comparisons, and if found, stores a reference to
-  the method in ther partial results map which it can later consult
+  the method in the partial results map which it can later consult
   from downstream modules.
 
 </p><p>
@@ -4175,7 +4176,23 @@
 outside of the current API level.
 
 </p>
-<a class="target" name="howdoicheckoutthecurrentlintsourcecode?">&nbsp;</a><a class="target" name="frequentlyaskedquestions//howdoicheckoutthecurrentlintsourcecode?">&nbsp;</a><a class="target" name="toc8.0.16">&nbsp;</a><h3>How do I check out the current lint source code?</h3>
+<a class="target" name="canimakemylintcheck%E2%80%9Cnotsuppressible?%E2%80%9D">&nbsp;</a><a class="target" name="frequentlyaskedquestions//canimakemylintcheck%E2%80%9Cnotsuppressible?%E2%80%9D">&nbsp;</a><a class="target" name="toc8.0.16">&nbsp;</a><h3>Can I make my lint check “not suppressible?”</h3>
+<p>
+
+
+In some (hopefully rare) cases, you may want your lint checks to not be
+suppressible using the normal mechanisms — suppress annotations,
+comments, lint.xml files, baselines, and so on. The usecase for this is
+typically strict company guidelines around compliance or security and
+you want to remove the easy possibility of just silencing the check.
+
+</p><p>
+
+This is possible as part of the issue registration. After creating your
+<code>Issue</code>, set the <code>suppressNames</code> property to an <strong class="asterisk">empty</strong> collection.
+
+</p>
+<a class="target" name="howdoicheckoutthecurrentlintsourcecode?">&nbsp;</a><a class="target" name="frequentlyaskedquestions//howdoicheckoutthecurrentlintsourcecode?">&nbsp;</a><a class="target" name="toc8.0.17">&nbsp;</a><h3>How do I check out the current lint source code?</h3>
 <pre class="listing backtick"><code><span class="line"><span class="hljs-meta">$</span><span class="bash"> git <span class="hljs-built_in">clone</span> --branch=mirror-goog-studio-master-dev --single-branch \</span>
 <span class="line">   https://android.googlesource.com/platform/tools/base</span></span>
 <span class="line">Cloning into 'base'...</span>
@@ -4192,7 +4209,7 @@
 <span class="line">.gitignore              MODULE_LICENSE_APACHE2  cli/</span>
 <span class="line"><span class="hljs-meta">$</span><span class="bash"> ls libs/</span></span>
 <span class="line">intellij-core/   kotlin-compiler/ lint-api/        lint-checks/     lint-gradle/     lint-model/      lint-tests/      uast/</span></code></pre>
-<a class="target" name="wheredoifindexamplesoflintchecks?">&nbsp;</a><a class="target" name="frequentlyaskedquestions//wheredoifindexamplesoflintchecks?">&nbsp;</a><a class="target" name="toc8.0.17">&nbsp;</a><h3>Where do I find examples of lint checks?</h3>
+<a class="target" name="wheredoifindexamplesoflintchecks?">&nbsp;</a><a class="target" name="frequentlyaskedquestions//wheredoifindexamplesoflintchecks?">&nbsp;</a><a class="target" name="toc8.0.18">&nbsp;</a><h3>Where do I find examples of lint checks?</h3>
 <p>
 
 
@@ -4330,6 +4347,11 @@
 
 <p></p><p>
 
+</p></li>
+<li class="asterisk">UAST for Kotlin is now based on Kotlin 1.5.
+
+<p></p><p>
+
 </p></li>
 <li class="asterisk">Certain Kotlin PSI elements have new implementations known as <em class="underscore">ultra
   light classes</em>. Ultra light classes improve performance by answering

docs/api-guide/changes.md.html

@@ -72,6 +72,8 @@
 
 * API documentation is now available.
 
+* UAST for Kotlin is now based on Kotlin 1.5.
+
 * Certain Kotlin PSI elements have new implementations known as _ultra
   light classes_. Ultra light classes improve performance by answering
   PSI queries “directly from source” rather than delegating to the

docs/api-guide/faq.md.html

@@ -276,6 +276,17 @@
 lint loads the issue registries it will ignore registries with a range
 outside of the current API level.
 
+### Can I make my lint check “not suppressible?”
+
+In some (hopefully rare) cases, you may want your lint checks to not be
+suppressible using the normal mechanisms -- suppress annotations,
+comments, lint.xml files, baselines, and so on. The usecase for this is
+typically strict company guidelines around compliance or security and
+you want to remove the easy possibility of just silencing the check.
+
+This is possible as part of the issue registration. After creating your
+`Issue`, set the `suppressNames` property to an **empty** collection.
+
 ### How do I check out the current lint source code?
 
 ```shell

docs/api-guide/partial-analysis.md.html

@@ -217,7 +217,7 @@
   This means that instead, you need to aggregate data along the way.
   For example, the way lint handles the version check method lookup is
   to look for SDK_INT comparisons, and if found, stores a reference to
-  the method in ther partial results map which it can later consult
+  the method in the partial results map which it can later consult
   from downstream modules.
 
 * Multiple passes across the modules (lint has a way to request

docs/checks/AnnotateVersionCheck.md.html

@@ -224,7 +224,7 @@
 }
 
 @ChecksSdkIntAtLeast(api = Build.VERSION_CODES.N)
-fun isNougat3(): Boolean {  // Should NOT annotate (already annotateD)
+fun isNougat3(): Boolean {  // Should NOT annotate (already annotated)
     return VERSION.SDK_INT >= VERSION_CODES.N
 }
 

docs/checks/AppLinksAutoVerifyError.md.html

@@ -1,7 +1,7 @@
 <meta charset="utf-8">
 (#) AppLinksAutoVerifyError
 
-The issue for this id has been deleted or marked obsolete and can now be
-ignored.
+This issue id is an alias for
+[AppLinksAutoVerify](AppLinksAutoVerify.md.html).
 
 (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/AppLinksAutoVerifyWarning.md.html

@@ -1,7 +1,7 @@
 <meta charset="utf-8">
 (#) AppLinksAutoVerifyWarning
 
-The issue for this id has been deleted or marked obsolete and can now be
-ignored.
+This issue id is an alias for
+[AppLinksAutoVerify](AppLinksAutoVerify.md.html).
 
 (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/BadConfigurationProvider.md.html

@@ -0,0 +1,97 @@
+<meta charset="utf-8">
+(#) Invalid WorkManager Configuration Provider
+
+!!! ERROR: Invalid WorkManager Configuration Provider
+   This is an error, and is also enforced at build time when
+   supported by the build system. For Android this means it will
+   run during release builds.
+
+Id
+:   `BadConfigurationProvider`
+Summary
+:   Invalid WorkManager Configuration Provider
+Severity
+:   Fatal
+Category
+:   Correctness
+Platform
+:   Android
+Vendor
+:   Android Open Source Project (androidx.work.lint.workmanager)
+Affects
+:   Kotlin and Java files
+Editing
+:   This check runs on the fly in the IDE editor
+Implementation
+:   [Source Code](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:/work/workmanager-lint/src/main/java/androidx/work/lint/BadConfigurationProviderIssueDetector.kt)
+
+An `android.app.Application` must implement
+`androidx.work.Configuration.Provider`
+for on-demand initialization.
+
+(##) 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("BadConfigurationProvider")
+  fun method() {
+     problematicStatement()
+  }
+  ```
+
+  or
+
+  ```java
+  // Java
+  @SuppressWarnings("BadConfigurationProvider")
+  void method() {
+     problematicStatement();
+  }
+  ```
+
+* Using a suppression comment like this on the line above:
+
+  ```kt
+  //noinspection BadConfigurationProvider
+  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="BadConfigurationProvider" 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 'BadConfigurationProvider'
+  }
+  ```
+  In Android projects this should be nested inside an `android { }`
+  block.
+
+* For manual invocations of `lint`, using the `--ignore` flag:
+  ```
+  $ lint --ignore BadConfigurationProvider ...`
+  ```
+
+* 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/BadPeriodicWorkRequestEnqueue.md.html

@@ -0,0 +1,99 @@
+<meta charset="utf-8">
+(#) Use `enqueueUniquePeriodicWork()` instead of `enqueue()`
+
+!!! WARNING: Use `enqueueUniquePeriodicWork()` instead of `enqueue()`
+   This is a warning.
+
+Id
+:   `BadPeriodicWorkRequestEnqueue`
+Summary
+:   Use `enqueueUniquePeriodicWork()` instead of `enqueue()`
+Severity
+:   Warning
+Category
+:   Correctness
+Platform
+:   Android
+Vendor
+:   Android Open Source Project (androidx.work.lint.workmanager)
+Affects
+:   Kotlin and Java files
+Editing
+:   This check runs on the fly in the IDE editor
+Implementation
+:   [Source Code](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:/work/workmanager-lint/src/main/java/androidx/work/lint/PeriodicEnqueueIssueDetector.kt)
+Tests
+:   [Source Code](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:/work/workmanager-lint/src/test/java/androidx/work/lint/PeriodicEnqueueIssueDetectorTest.kt)
+
+When using `enqueue()` for `PeriodicWorkRequest`s, you might end up
+enqueuing
+duplicate requests unintentionally. You should be using
+`enqueueUniquePeriodicWork` with an `ExistingPeriodicWorkPolicy.KEEP`
+instead.
+
+(##) 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("BadPeriodicWorkRequestEnqueue")
+  fun method() {
+     problematicStatement()
+  }
+  ```
+
+  or
+
+  ```java
+  // Java
+  @SuppressWarnings("BadPeriodicWorkRequestEnqueue")
+  void method() {
+     problematicStatement();
+  }
+  ```
+
+* Using a suppression comment like this on the line above:
+
+  ```kt
+  //noinspection BadPeriodicWorkRequestEnqueue
+  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="BadPeriodicWorkRequestEnqueue" 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 'BadPeriodicWorkRequestEnqueue'
+  }
+  ```
+  In Android projects this should be nested inside an `android { }`
+  block.
+
+* For manual invocations of `lint`, using the `--ignore` flag:
+  ```
+  $ lint --ignore BadPeriodicWorkRequestEnqueue ...`
+  ```
+
+* 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>