Merge pull request #39 from tnorbye/update-docs

Update lint documentation snapshot

Author: tnorbye

docs/README.md.html

@@ -15,13 +15,16 @@
 * [Lint Features](features.md.html)
 * [Recent Changes](changes.md.html)
 * Documents for users of lint, in the `usage` folder:
+  - [Complete Book](user-guide.md.html), containing all of the below
+    documents as chapters, suitable for offline reading
+  - [Performance Tuning Tips](usage/performance-tuning.md.html)
   - [How to suppress incidents](usage/suppressing.md.html)
   - [How to use baselines](usage/baselines.md.html)
   - [How to use `lint.xml` files](usage/lintxml.md.html)
   - [Environment variables and properties](usage/variables.md.html)
 * Documents for authors of additional lint checks, in the
   `api-guide` folder:
-  - [Complete Book](book.md.html), containing all of the below
+  - [Complete Book](api-guide.md.html), containing all of the below
     documents as chapters, suitable for offline reading
   - [Basics](api-guide/basics.md.html)
   - [A Sample Lint Check](api-guide/example.md.html)

docs/api-guide.html

@@ -0,0 +1,21 @@
+<meta charset="utf-8" lang="kotlin">
+
+**Android Lint API Guide**
+
+This chapter inlines all the API documentation into a single
+long book, suitable for printing or reading on a tablet.
+
+            (insert api-guide/terminology.md.html here)
+            (insert api-guide/basics.md.html here)
+            (insert api-guide/example.md.html here)
+            (insert api-guide/publishing.md.html here)
+            (insert api-guide/unit-testing.md.html here)
+            (insert api-guide/quickfixes.md.html here)
+            (insert api-guide/partial-analysis.md.html here)
+            (insert api-guide/faq.md.html here)
+
+            # Appendix: Recent Changes
+            (insert api-guide/changes.md.html here)
+            (insert usage/variables.md.html here)
+
+<!-- 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.md.html

@@ -1061,6 +1061,13 @@
 it, unless you want to look at individual details like specific
 whitespace between AST nodes, which is represented in PSI but not UAST.
 
+!!! Tip
+   You can find additional documentation from JetBrains for both
+   [PSI](https://plugins.jetbrains.com/docs/intellij/psi.html) and
+   [UAST](https://plugins.jetbrains.com/docs/intellij/uast.html).
+   Just note that their documentation is aimed at IDE plugin developers
+   rather than lint developers.
+
 ## Testing
 
 Writing unit tests for the lint check is important, and this is covered

docs/api-guide/basics.md.html

@@ -2,8 +2,8 @@
 
 This chapter lists recent changes to lint that affect lint check
 authors: new features, API and behavior changes, and so on. For
-information about user visible changes to lint, see
-[](../usage/changes.md.html).
+information about user visible changes to lint, see the User
+Guide.
 
 **7.0**
 
@@ -12,10 +12,10 @@
 * 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.
-  To opt in before it's turned on by default to test this on your full
-  Gradle projects rather than just the detector tests, add
+  It is enabled by default starting in AGP 7.0.0-alpha13, but you can
+  disable it by adding
 
-      `android.experimental.useLintPartialAnalysis=true`
+      `android.enableParallelLint=false`
 
   to your `gradle.properties` file. If you want to debug your lint check
   you may want to also set
@@ -72,4 +72,27 @@
 
 * API documentation is now available.
 
+* 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 Kotlin compiler backend. You may see ultra
+  light classes when accessing the `UElement.javaPsi` property of a
+  Kotlin UAST element. They can also appear when resolving references.
+  For example, resolving a Kotlin field reference to its declaration
+  may result in an instance of `KtUltraLightFieldForSourceDeclaration`.
+  As a reminder, Kotlin light classes represent the "Java view" of an
+  underlying Kotlin PSI element. To access the underlying Kotlin PSI
+  element you should use `UElement.sourcePsi` (preferred)
+  or otherwise the extension property `PsiElement.unwrapped` (declared
+  in `org.jetbrains.kotlin.asJava`).
+
+* There is a new bug where calling `getNameIdentifier()` on Kotlin
+  fields may return `null`
+  ([KT-45629](https://youtrack.jetbrains.com/issue/KT-45629)).
+  As a workaround you can use `JavaContext.findNameElement()` instead.
+
+* Kotlin references to Java methods now trigger both the
+  `visitMethodCall()` callback _and_ the `visitReference()` callback.
+  Previously only `visitMethodCall()` was triggered.
+
 <!-- 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/changes.md.html

@@ -71,7 +71,7 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin linenumbers
 buildscript {
     ext {
-        kotlinVersion = '1.4.31'
+        kotlinVersion = '1.4.32'
 
         // Current lint target: Studio 4.2 / AGP 7
         //gradlePluginVersion = '4.2.0-beta06'

docs/api-guide/example.md.html

@@ -112,7 +112,7 @@
 * 4% were updated to report incidents with data for later filtering
 * 1% were updated to perform map recording and later reduce filtering
 
-## Does my Detector Need Work?
+## Does My Detector Need Work?
 
 At this point you're probably wondering whether your checks are in the
 89% category where you don't need to do anything, or in the remaining
@@ -494,7 +494,7 @@
 you cannot just create incidents and filter or customize them later.
 
 The most complicated example of this is lint's built-in
-UnusedResourceDetector, which locates unused resources. This “requires”
+[UnusedResourceDetector](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/UnusedResourceDetector.java), which locates unused resources. This “requires”
 global analysis, since we want to include all resources in the entire
 project. We also cannot just store lists of “resources declared” and
 "resources referenced“ since we really want to treat this as a graph.

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

@@ -111,4 +111,34 @@
    clean builds. There are some bugs in the Android Gradle Plugin issue
    tracker for this.
 
+### Unpublishing
+
+If you end up “deleting” a lint check, perhaps because the original
+conditions for the lint check are not true, don't just stop
+distributing lint checks with your library. Instead, you'll want to
+update your `IssueRegistry` to override the `deletedIssues` property to
+return your deleted issue id or ids:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+/**
+ * The issue id's from any issues that have been deleted from this
+ * registry. This is here such that when an issue no longer applies
+ * and is no longer registered, any existing mentions of the issue
+ * id in baselines, lint.xml files etc are gracefully handled.
+ */
+open val deletedIssues: List<String> = emptyList()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The reason you'll want to do this is listed right there in the doc: If
+you don't do this, and if users have for example listed your issue id
+in their `build.gradle` file or in `lint.xml` to say change the
+severity, then lint will report an error that it's an unknown id. This
+is done to catch issue id typos. And if the user has a baseline file
+listing incidents from your check, then if your issue id is not
+registered as deleted, lint will think this is an issue that has been
+"fixed“ since it's no longer reported, and lint will issue an
+informational message that the baseline contains issues no longer
+reported (which is done such that users can update their baseline
+files, to ensure that the fixed issues aren't reintroduced again.)
+
 <!-- 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/publishing.md.html

@@ -82,6 +82,13 @@
   apply (such as “Android”, or “Server”, and so on). This means that an
   Android-specific check won't trigger warnings on non-Android code.
 
+Scanner
+: A `Scanner` is a particular interface a detector can implement to
+  indicate that it supports a specific set of callbacks. For example,
+  the `XmlScanner` interface is where the methods for visiting XML
+  elements and attributes are defined, and the `ClassScanner` is where
+  the ASM bytecode handling methods are defined, and so on.
+
 Scope
 : `Scope` is an enum which lists various types of files that a detector
   may want to analyze.

docs/api-guide/terminology.md.html

@@ -236,23 +236,23 @@
 
 ## Library Dependencies and Stubs
 
-Let's say you're writing a lint check for something like the
-AndroidX library's `RecyclerView` widget.
+Let's say you're writing a lint check for something like the Android
+Jetpack library's `RecyclerView` widget.
 
 In this case, it's highly likely that your unit test will reference
 `RecyclerView`. But how does lint know what `RecyclerView` is? If it
 doesn't, type resolve won't work, and as a result the detector won't.
 
-You could make your test ”depend“ on the recyclerview. This is
+You could make your test ”depend“ on the `RecyclerView`. This is
 possible, using the `LibraryReferenceTestFile`, but is not recommended.
 
 Instead, the recommended approach is to just use ”stubs“; create
 skeleton classes which represent only the **signatures** of the
-library, and in particular, only the subset that your lint check
-cares about.
+library, and in particular, only the subset that your lint check cares
+about.
 
-For example, for lint's own recycler view test, the unit test
-declares a field holding the recycler view stub:
+For example, for lint's own `RecyclerView` test, the unit test declares
+a field holding the recycler view stub:
 
 ```
 private val recyclerViewStub = java(
@@ -349,4 +349,16 @@
 project it will only provide the binaries, not the sources, for
 upstream modules.)
 
+## My Detector Isn't Invoked From a Test!
+
+One common question we hear is
+
+> My Detector works fine when I run it in the IDE or from Gradle, but
+> from my unit test, my detector is never called! Why?
+
+This is almost always because the test sources are referring to some
+library or dependency which isn't on the class path. See the ”Library
+Dependencies and Stubs“ section above, as well as the [frequently asked
+questions](faq.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>