Merge pull request #88 from googlesamples/update-docs

Update docs

Author: tnorbye

docs/api-guide/annotations.md.html

@@ -106,7 +106,7 @@
 The second case shows a similar situation where the array syntax will
 end up calling our extension method, `get()`.
 
-And the third case shows the most common scenario: a straight forward
+And the third case shows the most common scenario: a straightforward
 method call to an annotated method.
 
 In many cases, the above detector implementation is nearly all you have
@@ -322,7 +322,7 @@
 
 The `fileStack.push` call on line 4 also resolves to the same method
 as the call on line 2 (even though the concrete type is a `FileStack`
-instead of a `Stack), so like on line 2, this call is taken to be
+instead of a `Stack`), so like on line 2, this call is taken to be
 thread safe.
 
 However, the `fileStack.pop` call on line 6 resolves to the API method

docs/api-guide/basics.md.html

@@ -169,13 +169,13 @@
 
 Many detector methods will pass in a `Context`, or a more specific
 subclass of `Context` such as `JavaContext` or `XmlContext`. This
-allows lint to provide access to the detectors information they may
-need, without passing in a lot of parameters (and allowing lint to add
-additional data over time without breaking signatures).
+allows lint to give the detectors information they may need, without
+passing in a lot of parameters. It also allows lint to add additional data
+over time without breaking signatures.
 
 The `Context` classes also provide many convenience APIs. For example,
 for `XmlContext` there are methods for creating locations for XML tags,
-XML attributes, just the name part of an XML attribute and just the
+XML attributes, just the name part of an XML attribute, and just the
 value part of an XML attribute. For a `JavaContext` there are also
 methods for creating locations, such as for a method call, including
 whether to include the receiver and/or the argument list.
@@ -204,7 +204,7 @@
 Lint's API has two halves:
 
 - The **Client API**: “Integrate (and run) lint from within a tool”.
-  For example, both the IDE and the build system uses this API to embed
+  For example, both the IDE and the build system use this API to embed
   and invoke lint to analyze the code in the project or editor.
 
 - The **Detector API**: “Implement a new lint check”. This is the API
@@ -213,27 +213,26 @@
 The class in the Client API which represents lint running in a tool is
 called `LintClient`. This class is responsible for, among other things:
 
-* Reporting incidents found by detectors. For example, in the IDE, it
+* **Reporting incidents found by detectors**. For example, in the IDE, it
   will place error markers into the source editor, and in a build
   system, it may write warnings to the console or generate a report or
   even fail the build.
 
-* Handling I/O. Detectors should never read files from disk directly.
+* **Handling I/O**. Detectors should never read files from disk directly.
   This allows lint checks to work smoothly in for example the IDE. When
   lint runs on the fly, and a lint check asks for the source file
   contents (or other supporting files), the `LintClient` in the IDE
   will implement the `readFile` method to first look in the open source
   editors and if the requested file is being edited, it will return the
   current (often unsaved!) contents.
 
-* Handling network traffic. Lint checks should never open
-  URLConnections themselves. By going through the lint API to request
-  data for a URL, not only can the LintClient for example use any
-  configured IDE proxy settings which is done in the IntelliJ
-  integration of lint, but even the lint check's own unit tests can
-  easily be tested because the special unit test implementation of a
-  `LintClient` provides a simple way to provide exact responses for
-  specific URLs:
+* **Handling network traffic**. Lint checks should never open
+  URLConnections themselves. Instead, they should go through the lint API
+  to request data for URLs. Among other things, this allows the
+  `LintClient` to use configured IDE proxy settings (as is done in the
+  IntelliJ integration of lint). This is also good for testing, because
+  the special unit test implementation of a `LintClient` has a simple way
+  to provide exact responses for specific URLs:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 lint()
@@ -256,8 +255,8 @@
 
 And much, much, more. **However, most of the implementation of
 `LintClient` is intended for integration of lint itself, and as a check
-author you don't need to worry about it.** It's the detector API that
-matters, and is also less likely to change than the client API.
+author you don't need to worry about it.** The detector API will matter
+more, and it's also less likely to change than the client API.
 
 !!! Tip
    The division between the two halves is not perfect; some classes
@@ -273,8 +272,8 @@
    for internal lint usage have been made `public` such that lint's
    code in one package can access it from the other. There's normally a
    comment explaining that this is for internal use only, but be aware
-   that just because something is `public` or not `final` it's a good
-   idea to call or override it.
+   that even when something is `public` or not `final`, it might not be a
+   good idea to call or override it.
 
 ## Creating an Issue
 
@@ -283,7 +282,7 @@
 [publishing](publishing.md.html) chapters.
 
 `Issue` is a final class, so unlike `Detector`, you don't subclass
-it, you instantiate it via `Issue.create`.
+it; you instantiate it via `Issue.create`.
 
 By convention, issues are registered inside the companion object of the
 corresponding detector, but that is not required.
@@ -631,16 +630,16 @@
 
 * When implementing **`SourceCodeScanner`**, in Kotlin and Java files
   you can be called back
-  - When a method of a given name is invoked (`getApplicableMethodNames`
+  - when a method of a given name is invoked (`getApplicableMethodNames`
     and `visitMethodCall`)
-  - When a class of the given type is instantiated
+  - when a class of the given type is instantiated
     (`getApplicableConstructorTypes` and `visitConstructor`)
-  - When a new class is declared which extends (possibly indirectly)
+  - when a new class is declared which extends (possibly indirectly)
     a given class or interface (`applicableSuperClasses` and
     `visitClass`)
-  - When annotated elements are referenced or combined
+  - when annotated elements are referenced or combined
     (`applicableAnnotations` and `visitAnnotationUsage`)
-  - When any AST nodes of given types appear (`getApplicableUastTypes`
+  - when any AST nodes of given types appear (`getApplicableUastTypes`
     and `createUastHandler`)
 
 * When implementing a **`ClassScanner`**, in `.class` and `.jar` files
@@ -650,7 +649,7 @@
   - when a given bytecode instruction occurs
     (`getApplicableAsmNodeTypes` and `checkInstruction`)
   - like with XmlScanner's `visitDocument`, you can perform your own
-    ASM bytecode iteration via `checkClass`.
+    ASM bytecode iteration via `checkClass`
 
 * There are various other scanners too, for example `GradleScanner`
   which lets you visit `build.gradle` and `build.gradle.kts` DSL
@@ -677,9 +676,9 @@
 the detector in fields and accumulate information for analysis at the
 end.
 
-There are some callbacks both before each individual file is analyzed
-(`beforeCheckFile` and `afterCheckFile`), as well as before and after
-analysis of all the modules (`beforeCheckRootProject` and
+There are some callbacks both before and after each individual file is
+analyzed (`beforeCheckFile` and `afterCheckFile`), as well as before and
+after analysis of all the modules (`beforeCheckRootProject` and
 `afterCheckRootProject`).
 
 This is for example how the ”unused resources“ check works: we store
@@ -764,8 +763,7 @@
   like the `ResourceRepository` and the `ResourceEvaluator`.
 
 * Finally, there are a number of utility methods; for example there is
-  an `editDistance` method used to find likely typos used by a number
-  of checks.
+  an `editDistance` method used to find likely typos.
 
 ## Scanner Example
 
@@ -807,7 +805,7 @@
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The second, older form, may seem simpler, but the new API allows a lot
+The second (older) form may seem simpler, but the new API allows a lot
 more metadata to be attached to the report, such as an override
 severity. You don't have to convert to the builder syntax to do this;
 you could also have written the second form as
@@ -1003,7 +1001,7 @@
 
 !!! Warning
    Resolving only works if lint has a correct classpath such that the
-   referenced method, field or class are actually present. If it is
+   referenced method, field, or class is actually present. If it is
    not, resolve will return null, and various lint callbacks will not
    be invoked. This is a common source of questions for lint checks
    ”not working“; it frequently comes up in lint unit tests where a

docs/api-guide/dataflow-analyzer.md.html

@@ -83,7 +83,7 @@
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Aas you can see, the `DataFlowAnalyzer` is a visitor, so when we find a
+As you can see, the `DataFlowAnalyzer` is a visitor, so when we find a
 call we're interested in, we construct a `DataFlowAnalyzer` and
 initialize it with the instance we want to track, and then we visit the
 surrounding method with this visitor.
@@ -254,8 +254,8 @@
 call.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin linenumbers
-fun test) {
-     val transaction = getFragmentManager().beginTransaction()
+fun test() {
+    val transaction = getFragmentManager().beginTransaction()
     process(transaction)
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/api-guide/faq.md.html

@@ -110,14 +110,14 @@
 
 ### How do I get the `UMethod` for a `PsiMethod` ?
 
-Call `psiMethod.toUElementOfType<UMethod>()`. Note that this may return
+Call `psiMethod.toUElementOfType&lt;UMethod>()`. Note that this may return
 null if UAST cannot find valid Java or Kotlin source code for the
 method.
 
 For `PsiField` and `PsiClass` instances use the equivalent
 `toUElementOfType` type arguments.
 
-### How do get a `JavaEvaluator` ?
+### How do get a `JavaEvaluator`?
 
 The `Context` passed into most of the `Detector` callback methods
 relevant to Kotlin and Java analysis is of type `JavaContext`, and it
@@ -173,7 +173,7 @@
     abstract fun getTypeClass(psiType: PsiType?): PsiClass?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-### How do I look up hierarhcy annotations for an element?
+### How do I look up hierarchy annotations for an element?
 
 You can directly look up annotations via the modified list
 of PsiElement or the annotations for a `UAnnotated` element,
@@ -254,7 +254,7 @@
     open fun computeArgumentMapping(
         call: UCallExpression,
         method: PsiMethod
-    ): Map<UExpression, PsiParameter> { /* ... */
+    ): Map&lt;UExpression, PsiParameter> { /* ... */
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This returns a map from UAST expressions (each argument to a UAST call
@@ -290,7 +290,7 @@
 ### Why are overloaded operators not handled?
 
 Kotlin supports overloaded operators, but these are not handled as
-calls in the AST - instead, an implicit `get` or `set` method from an
+calls in the AST -- instead, an implicit `get` or `set` method from an
 array access will show up as a `UArrayAccessExpression`. Lint has
 specific support to help handling these scenarios; see the “Implicit
 Calls” section in the [basics chapter](basics.md.html).

docs/api-guide/messages.md.html

@@ -41,7 +41,7 @@
 
 ## Punctuation
 
-One line error messages should not be punctuated - e.g. the error message
+One line error messages should not be punctuated -- e.g. the error message
 should be “Unused import foo”, not “Unused import foo.”
 
 However, if there are multiple sentences in the error message, all sentences

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

@@ -308,8 +308,8 @@
 represents it. To report an incident you simply call
 `context.report(incident)`. There are several ways to create these
 incidents. The easiest is to simply edit your existing call above by
-adding `Incident(` (or from Java, `new Incident(`) inside the
-`context.report` block like this:
+putting it inside `Incident(...)` (in Java, `new Incident(...)`) inside
+the `context.report` block like this:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
     context.report(Incident(
@@ -390,7 +390,7 @@
 from the `Constraints` class.
 
 Recording an incident with a constraint is easy; first construct the
-`Incident` as before, and then report them via
+`Incident` as before, and then report it via
 `context.report(incident, constraint)`:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~java
@@ -403,7 +403,7 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Finally, note that you can combine constraints; there are both “and”
-and “or” operators defined for the `Constraint` class. so the following
+and “or” operators defined for the `Constraint` class, so the following
 is valid:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin

docs/api-guide/publishing.md.html

@@ -126,7 +126,7 @@
  * 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()
+open val deletedIssues: List&lt;String> = emptyList()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The reason you'll want to do this is listed right there in the doc: If
@@ -136,7 +136,7 @@
 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
+“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.)

docs/api-guide/terminology.md.html

@@ -9,15 +9,15 @@
 
 Configuration
 : A configuration provides extra information or parameters to lint on a
-  per project, or even per directory basis. For example, the `lint.xml`
+  per-project, or even per-directory, basis. For example, the `lint.xml`
   files can change the severity for issues, or list incidents to ignore
   (matched for example by a regular expression), or even provide values
   for options read by a specific detector.
 
 Context
 : An object passed into detectors in many APIs, providing data about
   (for example) which file is being analyzed (and in which project),
-  and for specific types of analysis additional information; for
+  and (for specific types of analysis) additional information; for
   example, an XmlContext points to the DOM document, a JavaContext
   includes the AST, and so on.
 
@@ -97,7 +97,7 @@
   Java and Kotlin files, there is a scope for .class files, and so on.
 
   Typically lint cares about which **set** of scopes apply,
-  so most of the APIs take an `EnumSet< Scope>`, but we'll often
+  so most of the APIs take an `EnumSet&lt;Scope>`, but we'll often
   refer to this as just “the scope” instead of the “scope set”.
 
 Severity

docs/api-guide/test-modes.md.html

@@ -9,7 +9,7 @@
 
 There are a number of built-in test modes:
 
-* Test modes which makes small tweaks to the source files which
+* Test modes which make small tweaks to the source files which
   should be compatible, such as
   * Inserting unnecessary parentheses
   * Replacing imported symbols with fully qualified names
@@ -36,7 +36,7 @@
 `skipTestModes` DSL method, as described below.
 
 You can also add in your own test modes. For example, lint adds its own
-internal test mode for making sure the built-in annotation checks works
+internal test mode for making sure the built-in annotation checks work
 with Android platform annotations in the following test mode:
 
 [](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/AndroidPlatformAnnotationsTestMode.kt)
@@ -322,7 +322,7 @@
 last argument is a literal expression such as a number or a String. You
 *can't* just use `if (call.valueArguments.lastOrNull() is
 ULiteralExpression)`, because that first argument could be a
-`UParenthesizedExpression`, as in `call(1, true, ("hello")), so you'd
+`UParenthesizedExpression`, as in `call(1, true, ("hello"))`, so you'd
 need to look inside the parentheses.
 
 UAST comes with two functions to help you handle this correctly:

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

@@ -174,7 +174,7 @@
 ## Trimming indents?
 
 Notice how in the above Kotlin unit tests we used raw strings, **and**
-we indented the sources to be flush with the opening “”“ string
+we indented the sources to be flush with the opening `"""` string
 delimiter.
 
 You might be tempted to call `.trimIndent()` on the raw string.
@@ -412,7 +412,7 @@
                 "BwAAAAIAAQAIAAkAAQAKAAAAHQABAAEAAAAFKrcAAbEAAAABAAsAAAAGAAEA" +
                 "AAAEAAgADAAJAAEACgAAAB4AAQAAAAAABhICswADsQAAAAEACwAAAAYAAQAA" +
                 "AAUAAQANAAAAAgAO"
-        )`
+        )
     ).run().expect(
 ```
 
@@ -450,7 +450,7 @@
 and emit the full test file registration.
 
 This isn't just a convenience; lint's test infrastructure also uses
-this to test some additional scenarios (for example, in a multi- module
+this to test some additional scenarios (for example, in a multi-module
 project it will only provide the binaries, not the sources, for
 upstream modules.)