Merge pull request googlesamples#42 from tnorbye/issuedocs

Add issue documentation and update documentation snapshot

Author: tnorbye

README.md

@@ -5,7 +5,7 @@ The lint source code contains a lot of documentation on how to write
 custom checks; this git repository contains a snapshot of this
 documentation which you can read here:
 
-* [Full API Guide](https://googlesamples.github.io/android-custom-lint-rules/book.html)
+* [Full API Guide](https://googlesamples.github.io/android-custom-lint-rules/api-guide.html)
 * [Other docs](https://googlesamples.github.io/android-custom-lint-rules/index.html)
 
 Lint

docs/README.md.html

@@ -17,6 +17,8 @@
 * 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
+  - [Issue documentation](checks/index.md.html) which lists all the
+    available checks and provides documentation for each one.
   - [Performance Tuning Tips](usage/performance-tuning.md.html)
   - [How to suppress incidents](usage/suppressing.md.html)
   - [How to use baselines](usage/baselines.md.html)
@@ -37,6 +39,8 @@
 * Documents for lint internals, intended for developers of lint
   itself, in the `internal` folder:
   - [Guidelines](internal/guidelines.md.html)
+  - [Generating Issue Documentation](internal/document-checks.md.html)
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Documentation History:

docs/api-guide.html

@@ -3131,8 +3131,8 @@
 </p><p>
 
 </p><ol start="1">
-<li class="number">Local analysis which doesn't depend on anything else. For example, a
-   lint check which flags typos can report incidents immediately.
+<li class="number">Local analysis which doesn't depend on anything else. For example,
+   a lint check which flags typos can report incidents immediately.
    Lint calls these “definite incidents”.
 
 <p></p><p>
@@ -4266,8 +4266,8 @@
 <li class="asterisk">Bytecode verification: Instead of warning about 3rd party lint checks
   being obsolete because they were not compiled against the latest Lint
   API, lint now run its own bytecode verification against the lint jar
-  and will silently accept accept older (and newer!) lint checks if
-  they do not reference APIs that are not available.
+  and will silently accept older (and newer!) lint checks if they do
+  not reference APIs that are not available.
 
 <p></p><p>
 
@@ -4320,8 +4320,8 @@
 
 </p></li>
 <li class="asterisk">There are additional modifier lookup methods for Kotlin modifiers
-  on `JavaEvaluator, like isReified(), isCompanion(), isTailRec(), and
-  so on.
+  on <code>JavaEvaluator</code>, like <code>isReified()</code>, <code>isCompanion()</code>,
+  <code>isTailRec()</code>, and so on.
 
 <p></p><p>
 
@@ -4331,19 +4331,19 @@
 <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 PSI queries “directly from source” rather than
-  delegating to the Kotlin compiler backend. You may see ultra
-  light classes when accessing the <code>UElement.javaPsi</code> 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 <code>KtUltraLightFieldForSourceDeclaration</code>.
-  As a reminder, Kotlin light classes represent the “Java view” of an
+<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
+  PSI queries “directly from source” rather than delegating to the
+  Kotlin compiler backend. You may see ultra light classes when
+  accessing the <code>UElement.javaPsi</code> 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 <code>KtUltraLightFieldForSourceDeclaration</code>. 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 <code>UElement.sourcePsi</code> (preferred)
-  or otherwise the extension property <code>PsiElement.unwrapped</code> (declared
-  in <code>org.jetbrains.kotlin.asJava</code>).
+  element you should use <code>UElement.sourcePsi</code> (preferred) or otherwise
+  the extension property <code>PsiElement.unwrapped</code> (declared in
+  <code>org.jetbrains.kotlin.asJava</code>).
 
 <p></p><p>
 
@@ -4358,7 +4358,19 @@
 </p></li>
 <li class="asterisk">Kotlin references to Java methods now trigger both the
   <code>visitMethodCall()</code> callback <em class="underscore">and</em> the <code>visitReference()</code> callback.
-  Previously only <code>visitMethodCall()</code> was triggered.</li></ul>
+  Previously only <code>visitMethodCall()</code> was triggered.
+
+<p></p><p>
+
+</p></li>
+<li class="asterisk">Quickfixes can now create and delete new files; see
+  <code>LintFix#newFile</code> and <code>LintFix#deleteFile</code>..
+
+<p></p><p>
+
+</p></li>
+<li class="asterisk">For quickfixes, the <code>independent</code> property had inverted logic;
+  this has now been reversed to follow the meaning of the name.</li></ul>
 
 <p></p>
 <a class="target" name="appendix:environmentvariablesandsystemproperties">&nbsp;</a><a class="target" name="appendix:environmentvariablesandsystemproperties">&nbsp;</a><a class="target" name="toc10">&nbsp;</a><h1>Appendix: Environment Variables and System Properties</h1>
@@ -4515,5 +4527,8 @@
 
 </p></dd></td></tr><tr valign="top"><td><dt><code>lint.do.not.reuse.uast.env</code></dt></td><td><dd><p>  Alias for <code>$LINT_DO_NOT_REUSE_UAST_ENV</code>
 
+</p></dd></td></tr><tr valign="top"><td><dt><code>android.lint.log-jar-problems</code></dt></td><td><dd><p>  Controls whether lint will complain about custom check lint jar
+  loading problems. By default, true.
+
 </p></dd></td></tr></tbody></table></dl><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility=&ldquo;visible&rdquo;)</script>
 <p></p></span><div id="mdContextMenu" style="visibility:hidden"></div><div class="markdeepFooter"><i>formatted by <a href="https://casual-effects.com/markdeep" style="color:#999">Markdeep&nbsp;1.13&nbsp;&nbsp;</a></i><div style="display:inline-block;font-size:13px;font-family:'Times New Roman',serif;vertical-align:middle;transform:translate(-3px,-1px)rotate(135deg);">✒</div></div></body></html>

docs/api-guide/changes.md.html

@@ -31,8 +31,8 @@
 * Bytecode verification: Instead of warning about 3rd party lint checks
   being obsolete because they were not compiled against the latest Lint
   API, lint now run its own bytecode verification against the lint jar
-  and will silently accept older (and newer!) lint checks if
-  they do not reference APIs that are not available.
+  and will silently accept older (and newer!) lint checks if they do
+  not reference APIs that are not available.
 
 * Android Lint checks can now always access the resource repository for
   random access to resources, instead of having to gather them in batch
@@ -67,24 +67,24 @@
   warnings or errors.
 
 * There are additional modifier lookup methods for Kotlin modifiers
-  on `JavaEvaluator, like isReified(), isCompanion(), isTailRec(), and
-  so on.
+  on `JavaEvaluator`, like `isReified()`, `isCompanion()`,
+  `isTailRec()`, and so on.
 
 * 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
+* 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`).
+  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`
@@ -95,4 +95,10 @@
   `visitMethodCall()` callback _and_ the `visitReference()` callback.
   Previously only `visitMethodCall()` was triggered.
 
+* Quickfixes can now create and delete new files; see
+  `LintFix#newFile` and `LintFix#deleteFile`..
+
+* For quickfixes, the `independent` property had inverted logic;
+  this has now been reversed to follow the meaning of the name.
+
 <!-- 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/partial-analysis.md.html

@@ -68,9 +68,9 @@
 Detectors fit into one of the following categories (and these
 categories will be explained in subsequent sessions) :
 
-1. Local analysis which doesn't depend on anything else. For example, a
-   lint check which flags typos can report incidents immediately. Lint
-   calls these “definite incidents”.
+1. Local analysis which doesn't depend on anything else. For example,
+   a lint check which flags typos can report incidents immediately.
+   Lint calls these “definite incidents”.
 
 2. Local analysis which depends on a few, common conditions. For
    example, in Android, a check may only apply if the `minSdkVersion <

docs/book.html

@@ -37,14 +37,20 @@
 </p><p>
 
 </p><ol start="1">
-<li class="number"><a href="user-guide.html">User Guide</a> which documents how to
-   use, configure and tune lint.
+<li class="number"><a href="user-guide.html">User Guide</a> which documents how to use,
+   configure and tune lint.
 
 <p></p><p>
 
 </p></li>
-<li class="number"><a href="api-guide.html">API Guide</a> which documents how to
-   write your own lint checks.</li></ol>
+<li class="number"><a href="api-guide.html">API Guide</a> which documents how to write your
+   own lint checks.
+
+<p></p><p>
+
+</p></li>
+<li class="number"><a href="checks/index.md.html">Issue documentation</a> which lists all the
+   available checks and provides documentation for each one.</li></ol>
 
 <p></p><p>
 

docs/book.md.html

@@ -4,10 +4,13 @@
 
 There are two books:
 
-1. [User Guide](user-guide.md.html) which documents how to
-   use, configure and tune lint.
+1. [User Guide](user-guide.md.html) which documents how to use,
+   configure and tune lint.
 
-2. [API Guide](api-guide.md.html) which documents how to
-   write your own lint checks.
+2. [API Guide](api-guide.md.html) which documents how to write your
+   own lint checks.
+
+3. [Issue documentation](checks/index.md.html) which lists all the
+   available checks and provides documentation for each one.
 
 <!-- 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

@@ -0,0 +1,118 @@
+<meta charset="utf-8">
+(#) Potential AAPT crash
+
+!!! ERROR: Potential AAPT crash
+   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
+:   `AaptCrash`
+Summary
+:   Potential AAPT crash
+Severity
+:   Fatal
+Category
+:   Correctness
+Platform
+:   Android
+Vendor
+:   Android Open Source Project
+Affects
+:   Resource files
+Editing
+:   This check runs on the fly in the IDE editor
+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/ResourceCycleDetector.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/ResourceCycleDetectorTest.java)
+
+Defining a style which sets `android:id` to a dynamically generated id
+can cause many versions of `aapt`, the resource packaging tool, to
+crash. To work around this, declare the id explicitly with `<item
+type="id" name="..." />` instead.
+
+(##) Example
+
+Here is an example of lint warnings produced by this check:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~text
+res/values/aaptcrash.xml:5:Error: This construct can potentially crash
+aapt during a build. Change @+id/titlebar to @id/titlebar and define the
+id explicitly using <item type="id" name="titlebar"/> instead.
+[AaptCrash]
+
+    &lt;item name="android:id"&gt;@+id/titlebar&lt;/item&gt;
+    --------------------------------------------
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here is the source file referenced above:
+
+`res/values/aaptcrash.xml`:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~xml linenumbers
+&lt;?xml version="1.0" encoding="utf-8"?&gt;
+&lt;resources xmlns:android="http://schemas.android.com/apk/res/android"&gt;
+    &lt;style name="TitleBar"&gt;
+        &lt;item name="android:orientation"&gt;horizontal&lt;/item&gt;
+        &lt;item name="android:id"&gt;@+id/titlebar&lt;/item&gt;
+        &lt;item name="android:background"&gt;@drawable/bg_titlebar&lt;/item&gt;
+        &lt;item name="android:layout_width"&gt;fill_parent&lt;/item&gt;
+        &lt;item name="android:layout_height"&gt;@dimen/titlebar_height&lt;/item&gt;
+    &lt;/style&gt;
+&lt;/resources&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/ResourceCycleDetectorTest.java)
+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, `ResourceCycleDetector.testAaptCrash`.
+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="AaptCrash"` 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"`
+
+* 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="AaptCrash" 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 'AaptCrash'
+  }
+  ```
+  In Android projects this should be nested inside an `android { }`
+  block.
+
+* For manual invocations of `lint`, using the `--ignore` flag:
+  ```
+  $ lint --ignore AaptCrash ...`
+  ```
+
+* 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>