Update changelogs and docs for release (#1505)

pyricau · web-flow · commit d468fcb41d37 · 2019-07-26T22:51:21.000-07:00
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,8 +1,31 @@
 # Change Log
 
-## Version 2.0 Alpha 3 (2019-07-04)
+## Version 2.0 Beta 1 (2019-17-30)
+
+LeakCanary 2 reached **beta status**: the internals and APIs are mostly stable.
+
+Now is a great time to adopt it and provide feedback before the stable release. We're counting on you to find bugs and suggest improvements! Check out the new [Getting Started](https://square.github.io/leakcanary/getting_started) instructions and the [migration guide](https://square.github.io/leakcanary/upgrading-to-leakcanary-2.0/). 
+
+* New standalone library! [Shark](shark.md) is the heap analyzer that powers LeakCanary 2, and it can run in any Java VM. It comes with a [CLI](shark.md#shark-cli): you can now run `shark-cli analyze-process com.example.myapp` from your computer.
+* New Heap Explorer directly on device! Open a Heap Analysis in LeakCanary, tap the options menu and select "Heap Explorer". This is still experimental and not very user friendly, contributions welcome!
+* **Large API rewrite** to improve usability. If you used the alpha with a customized configuration, there are breaking changes. Of note: LeakSentry became [AppWatcher](/api/leakcanary-object-watcher-android/leakcanary/-app-watcher/), RefWatcher became [ObjectWatcher](/api/leakcanary-object-watcher/leakcanary/-object-watcher/), AndroidExcludedRefs became [AndroidReferenceMatchers](/api/shark-android/shark/-android-reference-matchers/), AnalysisResultListener became [OnHeapAnalyzedListener](/api/leakcanary-android-core/leakcanary/-on-heap-analyzed-listener/), AndroidLeakTraceInspectors became [AndroidObjectInspectors](/api/shark-android/shark/-android-object-inspectors/).
+* The entire API surface is now documented and the documentation is available on this website: try the search bar at the top and **LeakCanary API &or;** in the navigation menu.
+* Removed the **dependency on Android X**. No more configuration issues! [#1462](https://github.com/square/leakcanary/issues/1462) 
+* Added **Proguard rules** for LeakCanary and ObjectWatcher. [#1500](https://github.com/square/leakcanary/pull/1500) 
+* Display LeakCanary version in the About screen. [#1448](https://github.com/square/leakcanary/issues/1448) 
+* Bug fixes, new reference matchers and object inspectors
+
+Many thanks to
+[@arctouch-carlosottoboni](https://github.com/arctouch-carlosottoboni),
+[@jemaystermind](https://github.com/jemaystermind),
+[@kushagrakumar27](https://github.com/kushagrakumar27),
+[@pyricau](https://github.com/pyricau),
+[@snkashis](https://github.com/snkashis)
+for the contributions, bug reports and feature requests.
 
-**Thanks for testing the alpha**, we're counting on you to help us find bugs and suggest improvements! Check out the new [Getting Started](https://square.github.io/leakcanary/getting_started) instructions and the [migration guide](https://square.github.io/leakcanary/upgrading-to-leakcanary-2.0/). 
+For more details, see the [2.0-beta-1 Milestone](https://github.com/square/leakcanary/milestone/1) and the [full diff](https://github.com/square/leakcanary/compare/v2.0-alpha-3...v2.0-beta-1).
+
+## Version 2.0 Alpha 3 (2019-07-04)
 
 * [#1401](https://github.com/square/leakcanary/pull/1401) LeakCanary can now import all hprof files created from prior LeakCanary versions.
 * [#1414](https://github.com/square/leakcanary/pull/1414) New API: `RefWatcher.retainedInstances` which returns the instances that are currently considered retained.
diff --git a/docs/faq.md b/docs/faq.md
@@ -2,12 +2,12 @@
 
 ## Can a leak be caused by the Android SDK?
 
-Yes. There are a number of known memory leaks that have been fixed over time in AOSP as well as in manufacturer implementations. When such a leak occurs, there is little you can do as an app developer to fix it. For that reason, LeakCanary has a built-in list of known Android leaks to ignore: [AndroidExcludedRefs.kt](https://github.com/square/leakcanary/blob/master/leakcanary-analyzer/src/main/java/leakcanary/AndroidExcludedRefs.kt).
+Yes. There are a number of known memory leaks that have been fixed over time in AOSP as well as in manufacturer implementations. When such a leak occurs, there is little you can do as an app developer to fix it. For that reason, LeakCanary has a built-in list of known Android leaks to ignore: [AndroidReferenceMatchers](/api/shark-android/shark/-android-reference-matchers/).
 
 If you find a new one, please [create an issue](https://github.com/square/leakcanary/issues/new/choose) and follow these steps:
 
 1. Provide the entire leak trace information (reference key, device, etc), and use backticks (`) for formatting.
-2. Read the AOSP source for that version of Android, and try to figure out why it happens. You can easily navigate through SDK versions [android/platform_frameworks_base](https://github.com/android/platform_frameworks_base).
+2. Read the AOSP source for that version of Android, and try to figure out why it happens. You can easily navigate through SDK versions by switching branches on the GitHub mirror: [android/platform_frameworks_base](https://github.com/android/platform_frameworks_base).
 3. Check if it happens on the latest version of Android, and otherwise use blame to find when it was fixed.
 4. If it's still happening, build a simple repro case.
 5. File an issue on [b.android.com](http://b.android.com) with the leak trace and the repro case.
@@ -46,7 +46,7 @@ Update your dependencies to the latest SNAPSHOT (see [build.gradle](https://gith
 
 ```gradle
  dependencies {
-   debugImplementation 'com.squareup.leakcanary:leakcanary-android:2.0-alpha-4-SNAPSHOT'
+   debugImplementation 'com.squareup.leakcanary:leakcanary-android:2.0-beta-2-SNAPSHOT'
  }
 ```
 
diff --git a/docs/fundamentals.md b/docs/fundamentals.md
@@ -143,7 +143,7 @@ The chain of references from the GC root to the leaking instance is what is prev
     &#9474;    View.mWindowAttachCount=1
 ```
 
-LeakCanary runs heuristics to determine the lifecycle state of the nodes of the leak trace, and therefore whether they are leaking or not. For example, if a view has `View#mAttachInfo = null` and `mParent != null` then it is detached yet has a parent, so that view is probably leaking. In the leak trace, for each node you'll see `Leaking: YES / NO / UNKNOWN` with an explanation in parenthesis. LeakCanary can also surface extra information about the state of a node, e.g. `View.mWindowAttachCount=1`. LeakCanary comes with a set of default heuristics ([AndroidObjectInspectors](/api/shark-android/shark/-android-object-inspectors/), you can add your own heuristics by updating [LeakCanary.Config.objectInspectors](/api/leakcanary-android-core/leakcanary/-leak-canary/-config/object-inspectors/).
+LeakCanary runs heuristics to determine the lifecycle state of the nodes of the leak trace, and therefore whether they are leaking or not. For example, if a view has `View#mAttachInfo = null` and `mParent != null` then it is detached yet has a parent, so that view is probably leaking. In the leak trace, for each node you'll see `Leaking: YES / NO / UNKNOWN` with an explanation in parenthesis. LeakCanary can also surface extra information about the state of a node, e.g. `View.mWindowAttachCount=1`. LeakCanary comes with a set of default heuristics: [AndroidObjectInspectors](/api/shark-android/shark/-android-object-inspectors/). You can add your own heuristics by updating [LeakCanary.Config.objectInspectors](/api/leakcanary-android-core/leakcanary/-leak-canary/-config/object-inspectors/) (see the [recipe](recipes.md#identifying-leaking-objects-and-labeling-objects)).
 
 ### Narrowing down the cause of a leak
 
diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -9,10 +9,10 @@ dependencies {
 }
 ```
 
-**That's it, there is no code change needed!** [Here's why](faq.md#how-does-leakcanary-get-installed-by-only-adding-a-dependency). LeakCanary will automatically show a notification when a memory leak is detected in debug builds.
+**That's it, there is no code change needed!** LeakCanary will automatically show a notification when a memory leak is detected in debug builds.
 
 What's next?
 
 * Learn the [Fundamentals](fundamentals.md)
 * Try the [code recipes](recipes.md)
-* Read the [FAQ](faq.md)
+* Read the [FAQ](faq.md), e.g. [How does LeakCanary get installed by only adding a dependency?](faq.md#how-does-leakcanary-get-installed-by-only-adding-a-dependency)
diff --git a/docs/recipes.md b/docs/recipes.md
@@ -4,7 +4,7 @@ If you think a recipe might be missing or you're not sure that what you're tryin
 
 ## Configuring AppWatcher in `object-watcher-android`
 
-AppWatcher is in charge of detecting retained objects. Its configuration can be updated at any time by replacing `AppWatcher.config`:
+AppWatcher is in charge of detecting retained objects. Its configuration can be updated at any time by replacing [AppWatcher.config](/api/leakcanary-object-watcher-android/leakcanary/-app-watcher/config/):
 ```kotlin
 class DebugExampleApplication : ExampleApplication() {
 
@@ -17,7 +17,7 @@ class DebugExampleApplication : ExampleApplication() {
 
 ## Configuring LeakCanary
 
-LeakCanary can be configured by replacing `LeakCanary.config`:
+LeakCanary can be configured by replacing [LeakCanary.config](/api/leakcanary-android-core/leakcanary/-leak-canary/config/):
 
 ```kotlin
 disableLeakCanaryButton.setOnClickListener {
@@ -27,7 +27,7 @@ disableLeakCanaryButton.setOnClickListener {
 
 ## Watching objects with a lifecycle
 
-In your application, you may have other objects with a lifecycle, such as fragments, services, Dagger components, etc. Use `AppWatcher.objectWatcher` to watch instances that should be garbage collected:
+In your application, you may have other objects with a lifecycle, such as fragments, services, Dagger components, etc. Use [AppWatcher.objectWatcher](/api/leakcanary-object-watcher-android/leakcanary/-app-watcher/object-watcher/) to watch instances that should be garbage collected:
 
 ```kotlin
 class MyService : Service {
@@ -118,7 +118,7 @@ res/
 
 You can change the default behavior to upload the analysis result to a server of your choosing.
 
-Create a custom `AnalysisResultListener` that delegates to the default: 
+Create a custom [OnHeapAnalyzedListener](/api/leakcanary-android-core/leakcanary/-on-heap-analyzed-listener/) that delegates to [DefaultOnHeapAnalyzedListener](/api/leakcanary-android-core/leakcanary/-default-on-heap-analyzed-listener/): 
 
 ```kotlin
 class LeakUploader : OnHeapAnalyzedListener {
@@ -134,7 +134,7 @@ class LeakUploader : OnHeapAnalyzedListener {
 }
 ```
 
-Set `analysisResultListener` on the LeakCanary config:
+Set [LeakCanary.config.onHeapAnalyzedListener](/api/leakcanary-android-core/leakcanary/-leak-canary/-config/on-heap-analyzed-listener/):
 
 ```kotlin
 class DebugExampleApplication : ExampleApplication() {
diff --git a/docs/shark.md b/docs/shark.md
@@ -7,20 +7,75 @@
 <img src="https://github.com/square/leakcanary/wiki/assets/shark.png" />
 </p>
 
-Shark is the heap analyzer that powers LeakCanary. It's a standalone heap analyzer Kotlin library that can run in Java and Android VMs at **high speed** with a **low memory footprint**. It can analyze both Android and Java VM hprof files.
+Shark is the heap analyzer that powers LeakCanary 2. It's a Kotlin standalone heap analysis library that runs at **high speed** with a **low memory footprint**.
 
-Shark is released as several distinct libraries:
+Shark is released in layers:
 
-* `Shark Hprof`: Read and write records in hprof files
-* `Shark Graph`: Navigate the heap object graph
-* `Shark`: Generate heap analysis reports
-* `Shark Android`: Generate Android tailored heap analysis reports
+1. **Shark Hprof**: Read and write records in hprof files.
+2. **Shark Graph**: Navigate the heap object graph.
+3. **Shark**: Generate heap analysis reports.
+4. **Shark Android**: Android heuristics to generate tailored heap analysis reports.
+5. **Shark CLI**: Analyze the heap of debuggable apps installed on an Android device connected to your desktop. The output is similar to the output of LeakCanary, except you don't have to add the LeakCanary dependency to your app.
+6. **LeakCanary**: Builds on top. It automatically watches destroyed activities and fragments, triggers a heap dump, runs Shark Android and then displays the result.
 
-Shark is also released as a CLI tool, `Shark CLI`.
+A few more things:
 
-## Example usage
+* Shark is built on top of Okio. Okio makes it easy to parse heap dumps efficiently.
+* Shark is a 100% Kotlin library, and Kotlin is essential to its design, because Shark relies heavily on sealed classes and sequences to save memory.
+* Shark has the unique ability to help narrow down the cause of memory leaks through platform specific [heuristics](fundamentals.md#heuristics-and-labels).
+* Shark is heavily tested (80% test coverage).
+* Shark can run in both Java and Android VMs, with no other dependency than Okio and Kotlin.
+* Shark can analyze both Java and Android VM hprof files.
 
-### Reading records in a hprof file with shark-hprof
+## Shark CLI
+
+The Shark Command Line Interface (CLI) enables you to analyze heaps directly from your computer. It can dump the heap of an app installed on a connected Android device, analyze it, and even strip a heap dump of any sensitive data (e.g. PII, passwords or encryption keys) which is useful when sharing a heap dump.
+
+Download it [here](https://github.com/square/leakcanary/releases/download/v2.0-beta-1/shark-cli-2.0-beta-1.zip)!
+
+Usage instructions:
+
+```
+$ ./bin/shark-cli
+
+Shark CLI
+
+                 ^`.                 .=""=.
+ ^_              \  \               / _  _ \
+ \ \             {   \             |  d  b  |
+ {  \           /     `~~~--__     \   /\   /
+ {   \___----~~'              `~~-_/'-=\/=-'\,
+  \                         /// a  `~.      \ \
+  / /~~~~-, ,__.    ,      ///  __,,,,)      \ |
+  \/      \/    `~~~;   ,---~~-_`/ \        / \/
+                   /   /            '.    .'
+                  '._.'             _|`~~`|_
+                                    /|\  /|\
+
+Commands: [analyze-process, dump-process, analyze-hprof, strip-hprof]
+
+analyze-process: Dumps the heap for the provided process name, pulls the hprof file and analyzes it.
+  USAGE: analyze-process PROCESS_PACKAGE_NAME
+
+dump-process: Dumps the heap for the provided process name and pulls the hprof file.
+  USAGE: dump-process PROCESS_PACKAGE_NAME
+
+analyze-hprof: Analyzes the provided hprof file.
+  USAGE: analyze-hprof HPROF_FILE_PATH
+
+strip-hprof: Replaces all primitive arrays from the provided hprof file with arrays of zeroes.
+  USAGE: strip-hprof HPROF_FILE_PATH
+```
+
+## Shark code examples
+
+### Reading records in a hprof file
+
+```groovy
+dependencies {
+  implementation 'com.squareup.leakcanary:shark-hprof:$sharkVersion'
+}
+```
 
 ```kotlin
 // Prints all class and field names
@@ -34,13 +89,19 @@ Hprof.open(heapDumpFile)
     }
 ```
 
-### Navigating the heap object graph with shark-graph
+### Navigating the heap object graph
+
+```groovy
+dependencies {
+  implementation 'com.squareup.leakcanary:shark-graph:$sharkVersion'
+}
+```
 
 ```kotlin
 // Prints all thread names
 Hprof.open(heapDumpFile)
     .use { hprof ->
-      val heapGraph = HeapGraph.indexHprof(hprof)
+      val heapGraph = HprofHeapGraph.indexHprof(hprof)
       val threadClass = heapGraph.findClassByName("java.lang.Thread")!!
       val threadNames: Sequence<String> = threadClass.instances.map { instance ->
         val nameField = instance["java.lang.Thread", "name"]!!
@@ -50,7 +111,13 @@ Hprof.open(heapDumpFile)
     }
 ```
 
-### Generating a heap analysis report with shark
+### Generating a heap analysis report
+
+```groovy
+dependencies {
+  implementation 'com.squareup.leakcanary:shark:$sharkVersion'
+}
+```
 
 ```kotlin
 val heapAnalyzer = HeapAnalyzer(AnalyzerProgressListener.NONE)
@@ -61,15 +128,21 @@ val analysis = heapAnalyzer.checkForLeaks(
         val field = instance["com.example.ThingWithLifecycle", "destroyed"]!!
         val destroyed = field.value.asBoolean!!
         if (destroyed) {
-          reportLeaking(reason = "ThingWithLifecycle.destroyed = true")
+          leakingReasons += "ThingWithLifecycle.destroyed = true"
         }
       }
     })
 )
 println(analysis)
 ```
 
-### Generating an Android heap analysis report with shark-android
+### Generating an Android heap analysis report
+
+```groovy
+dependencies {
+  implementation 'com.squareup.leakcanary:shark-android:$sharkVersion'
+}
+```
 
 
 ```kotlin
diff --git a/docs/upgrading-to-leakcanary-2.0.md b/docs/upgrading-to-leakcanary-2.0.md
@@ -72,7 +72,7 @@ val objectWatcher: ObjectWatcher = AppWatcher.objectWatcher
 
 ## Compile errors because RefWatcher is used in release code
 
-If you were using `RefWatcher` in non debug code, you now get a compile error because the no-op artifact is gone. `ObjectWatcher` now lives in the `object-watcher` artifact, which is suitable for production. You have two options:
+If you were using `RefWatcher` in non debug code, you now get a compile error because the no-op artifact is gone. [ObjectWatcher](/api/leakcanary-object-watcher/leakcanary/-object-watcher/) now lives in the `object-watcher` artifact, which is suitable for production. You have two options:
 
 ### Option 1: Add `object-watcher-android` to release builds.
 
@@ -82,7 +82,7 @@ dependencies {
 }
 ```
 
-* It will automatically keep weak references to destroyed activities, fragments, and any instance you pass to `ObjectWatcher`.
+* It will automatically keep weak references to destroyed activities, fragments, and any instance you pass to [AppWatcher.objectWatcher](/api/leakcanary-object-watcher-android/leakcanary/-app-watcher/object-watcher/).
 * It will not trigger heap dumps or anything else that LeakCanary does.
 * It's very little code and should have a no impact on your release app.
 * You can use it to count how many objects are retained, for example to add metadata to OutOfMemoryError crashes:
@@ -112,7 +112,7 @@ class RealObjectWatcher : MaybeObjectWatcher {
 }
 ```
 
-Use MaybeObjectWatcher.None in release code and RealObjectWatcher in debug code.
+Use `MaybeObjectWatcher.None` in release code and `RealObjectWatcher` in debug code.
 
 ## Configuring LeakCanary
 
@@ -131,7 +131,7 @@ public class DebugExampleApplication extends ExampleApplication {
 
 ### Now
 
-AppWatcher is in charge of detecting retained objects. Its configuration can be updated at any time by replacing `AppWatcher.config`:
+AppWatcher is in charge of detecting retained objects. Its configuration can be updated at any time by replacing [AppWatcher.config](/api/leakcanary-object-watcher-android/leakcanary/-app-watcher/config/):
 
 ```kotlin
 class DebugExampleApplication : ExampleApplication() {
@@ -143,7 +143,7 @@ class DebugExampleApplication : ExampleApplication() {
 }
 ```
 
-LeakCanary is in charge of taking heap dumps and analyzing them. Its configuration can be updated at any time by replacing `LeakCanary.config`:
+LeakCanary is in charge of taking heap dumps and analyzing them. Its configuration can be updated at any time by replacing [LeakCanary.config](/api/leakcanary-android-core/leakcanary/-leak-canary/config/):
 
 ```kotlin
 disableLeakCanaryButton.setOnClickListener {
diff --git a/shark-cli/src/main/java/shark/Main.kt b/shark-cli/src/main/java/shark/Main.kt
@@ -23,10 +23,22 @@ fun main(args: Array<String>) {
 fun printHelp() {
   val workingDirectory = File(System.getProperty("user.dir"))
 
+  // ASCII art is a remix of a shark from -David "TAZ" Baltazar- and chick from jgs.
   SharkLog.d(
       """
-    LeakCanary CLI
-    Running in directory $workingDirectory
+    Shark CLI, running in directory $workingDirectory
+
+                     ^`.                 .=""=.
+     ^_              \  \               / _  _ \
+     \ \             {   \             |  d  b  |
+     {  \           /     `~~~--__     \   /\   /
+     {   \___----~~'              `~~-_/'-=\/=-'\,
+      \                         /// a  `~.      \ \
+      / /~~~~-, ,__.    ,      ///  __,,,,)      \ |
+      \/      \/    `~~~;   ,---~~-_`/ \        / \/
+                       /   /            '.    .'
+                      '._.'             _|`~~`|_
+                                        /|\  /|\
 
     Commands: [analyze-process, dump-process, analyze-hprof, strip-hprof]
 
diff --git a/shark-hprof/src/main/java/shark/HprofPrimitiveArrayStripper.kt b/shark-hprof/src/main/java/shark/HprofPrimitiveArrayStripper.kt
