Android: Update Android Studio docs

Includes documentation for recent changes for native editing, fast by
default, and channel support.

Bug: 620034
Change-Id: Ie6570a4c032853a4bfdfd3443091ea7f698e8e99
Reviewed-on: https://chromium-review.googlesource.com/1054333
Commit-Queue: Peter Wen <wnwen@chromium.org>
Reviewed-by: Eric Stevenson <estevenson@chromium.org>
Reviewed-by: agrieve <agrieve@chromium.org>
Cr-Commit-Position: refs/heads/master@{#557653}

docs/android_studio.md

@@ -8,7 +8,7 @@ Make sure you have followed
 [android build instructions](android_build_instructions.md) already.
 
 ```shell
-build/android/gradle/generate_gradle.py --output-directory out/Debug [--canary]  # Use --canary for Android Studio 3.1 canary
+build/android/gradle/generate_gradle.py --output-directory out/Debug
 ```
 
 This creates a project at `out/Debug/gradle`. To create elsewhere:
@@ -39,53 +39,72 @@ To import the project:
 
 If you're asked to use Studio's Android SDK:
 
-* No. (Always use the SDK configured by generate_gradle.py)
+* No. (Always use your project's SDK configured by generate_gradle.py)
 
 If you're asked to use Studio's Gradle wrapper:
 
 * Yes.
 
 You need to re-run `generate_gradle.py` whenever `BUILD.gn` files change.
 
+Pass `--canary` or `--beta` to avoid the "A newer version of gradle is
+available" notification.
+
 * After regenerating, Android Studio should prompt you to "Sync". If it
-  doesn't, use:
+  doesn't, try some of the following options:
+    * File -> "Sync Project with Gradle Files"
     * Button with two arrows on the right side of the top strip.
     * Help -> Find Action -> "Sync Project with Gradle Files"
     * After `gn clean` you may need to restart Android Studio.
+    * File -> "Invalidate Caches / Restart..."
 
 ## How It Works
 
-By default, only a single module is generated. If more than one apk target is
-specified, then an `_all` module is generated. Otherwise a single apk module is
-generated. Since instrumentation tests are combined with their `apk_under_test`
-target, they count as one module together.
+By default, only an `_all` module containing all java apk targets is generated.
+If just one apk target is explicitly specified, then a single apk module is
+generated.
 
 To see more detailed structure of gn targets, the `--split-projects` flag can
 be used. This will generate one module for every gn target in the dependency
-graph.
+graph. This can be very slow when used with `--all` by default.
 
 ### Excluded Files
 
 Gradle supports source directories but not source files. However, files in
 Chromium are used amongst multiple targets. To accommodate this, the script
 detects such targets and creates exclude patterns to exclude files not in the
-current target. The editor does not respect these exclude patterns, so a `_all`
-pseudo module is added which includes directories from all targets. This allows
-imports and refactorings to be searched across all targets.
+current target. The editor does not respect these exclude patterns, so the
+`_all` pseudo module is added which includes directories from all targets. This
+allows imports and refactoring to be across all targets.
 
 ### Extracting .srcjars
 
 Most generated .java files in GN are stored as `.srcjars`. Android Studio does
-not support them, and so the generator script builds and extracts them all to
+not support them. It is very slow to build all these generated files and they
+rarely change. The generator script does not do anything with them by default.
+If `--full` is passed then the generator script builds and extracts them all to
 `extracted-srcjars/` subdirectories for each target that contains them. This is
 the reason that the `_all` pseudo module may contain multiple copies of
 generated files.
 
 *** note
-** TLDR:** Always re-generate project files when `.srcjars` change (this
-includes `R.java`).
+** TLDR:** Re-generate project files with `--full` when generated files change (
+includes `R.java`) and to remove some red underlines in java files.
 ***
 
+### Native Files
+
+A new experimental option is now available to enable editing native C/C++ files
+with Android Studio. Pass in any number of `--native-target [target name]` flags
+in order to try it out. This will require `cmake` and `ndk` packages for your
+android SDK. This [crbug](https://crbug.com/840542) tracks adding those to our
+`android_tools` repository. For the interim accepting Android Studio's prompts
+should work. Example below.
+
+```shell
+build/android/gradle/generate_gradle.py --native-target //chrome/android:monochrome
+```
+
 ## Android Studio Tips
 
 * Using the Java debugger is documented at [android_debugging_instructions.md#android-studio](android_debugging_instructions.md#android-studio).
@@ -108,6 +127,8 @@ includes `R.java`).
     * Help -> Find Action -> "Show quick documentation on mouse move"
 * Turn on line numbers:
     * Help -> Find Action -> "Show line numbers"
+* Turn off indent notification:
+    * Help -> Find Action -> "Show notifications about detected indents"
 * Format changed files (Useful for changes made by running code inspection):
     * Set up version control
         * File -> Settings -> Version Control
@@ -146,23 +167,23 @@ resources, native libraries, etc.
     * Add the line `org.gradle.daemon=true` to `~/.gradle/gradle.properties`,
       creating it if necessary.
 
-## Status (as of Nov 1, 2017)
+## Status (as of May 10, 2018)
 
 ### What works
 
-* Android Studio v3.0 and v3.1 canary with `--canary` flag.
-* Java editing and gradle compile (mostly).
+* Android Studio v3.0-v3.2.
+* Java editing.
+* Native code editing (experimental).
 * Instrumentation tests included as androidTest.
 * Symlinks to existing .so files in jniLibs (doesn't generate them).
 * Editing resource xml files
-* Layout editor (somewhat :P).
+* Layout editor (limited functionality).
 * Java debugging (see
 [here](/docs/android_debugging_instructions.md#Android-Studio)).
-* Import resolution and refactoring across all modules.
+* Import resolution and refactoring across java files.
 * Correct lint and AndroidManifest when only one target is specified.
 
 ### What doesn't work (yet) ([crbug](https://bugs.chromium.org/p/chromium/issues/detail?id=620034))
 
 * Gradle being aware of assets.
-* Native code editing.
 * Having the "Make Project" button work correctly.