Merge "docs: gradle plugin revision update" into mnc-preview-docs
diff --git a/docs/html/about/dashboards/index.jd b/docs/html/about/dashboards/index.jd
index 2397dfe..e04940b 100644
--- a/docs/html/about/dashboards/index.jd
+++ b/docs/html/about/dashboards/index.jd
@@ -57,7 +57,7 @@
</div>
-<p style="clear:both"><em>Data collected during a 7-day period ending on June 1, 2015.
+<p style="clear:both"><em>Data collected during a 7-day period ending on August 3, 2015.
<br/>Any versions with less than 0.1% distribution are not shown.</em>
</p>
@@ -88,7 +88,7 @@
</div>
-<p style="clear:both"><em>Data collected during a 7-day period ending on June 1, 2015.
+<p style="clear:both"><em>Data collected during a 7-day period ending on August 3, 2015.
<br/>Any screen configurations with less than 0.1% distribution are not shown.</em></p>
@@ -108,7 +108,7 @@
<img alt="" style="float:right"
-src="//chart.googleapis.com/chart?chl=GL%202.0%7CGL%203.0%7CGL%203.1&chf=bg%2Cs%2C00000000&chd=t%3A63.0%2C35.0%2C2.0&chco=c4df9b%2C6fad0c&cht=p&chs=400x250">
+src="//chart.googleapis.com/chart?chl=GL%202.0%7CGL%203.0%7CGL%203.1&chf=bg%2Cs%2C00000000&chd=t%3A59.8%2C36.8%2C3.4&chco=c4df9b%2C6fad0c&cht=p&chs=400x250">
<p>To declare which version of OpenGL ES your application requires, you should use the {@code
android:glEsVersion} attribute of the <a
@@ -126,39 +126,64 @@
</tr>
<tr>
<td>2.0</td>
-<td>63.0%</td>
+<td>59.8%</td>
</tr>
<tr>
<td>3.0</td>
-<td>35.0%</td>
+<td>36.8%</td>
</tr>
<tr>
<td>3.1</td>
-<td>2.0%</td>
+<td>3.4%</td>
</tr>
</table>
-<p style="clear:both"><em>Data collected during a 7-day period ending on June 1, 2015</em></p>
-
-
-
-
-
-
-
-
+<p style="clear:both"><em>Data collected during a 7-day period ending on August 3, 2015</em></p>
<script>
+var SCREEN_DATA =
+[
+ {
+ "data": {
+ "Large": {
+ "hdpi": "0.6",
+ "ldpi": "0.3",
+ "mdpi": "4.9",
+ "tvdpi": "2.3",
+ "xhdpi": "0.6"
+ },
+ "Normal": {
+ "hdpi": "40.6",
+ "mdpi": "6.9",
+ "tvdpi": "0.1",
+ "xhdpi": "20.4",
+ "xxhdpi": "15.8"
+ },
+ "Small": {
+ "ldpi": "3.6"
+ },
+ "Xlarge": {
+ "hdpi": "0.3",
+ "mdpi": "3.0",
+ "xhdpi": "0.6"
+ }
+ },
+ "densitychart": "//chart.googleapis.com/chart?chs=400x250&cht=p&chco=c4df9b%2C6fad0c&chf=bg%2Cs%2C00000000&chd=t%3A3.9%2C14.8%2C2.4%2C41.5%2C21.6%2C15.8&chl=ldpi%7Cmdpi%7Ctvdpi%7Chdpi%7Cxhdpi%7Cxxhdpi",
+ "layoutchart": "//chart.googleapis.com/chart?chs=400x250&cht=p&chco=c4df9b%2C6fad0c&chf=bg%2Cs%2C00000000&chd=t%3A3.9%2C8.7%2C83.8%2C3.6&chl=Xlarge%7CLarge%7CNormal%7CSmall"
+ }
+];
+
+
var VERSION_DATA =
[
{
- "chart": "//chart.googleapis.com/chart?chco=c4df9b%2C6fad0c&cht=p&chs=500x250&chl=Froyo%7CGingerbread%7CIce%20Cream%20Sandwich%7CJelly%20Bean%7CKitKat%7CLollipop&chd=t%3A0.3%2C5.6%2C5.1%2C37.4%2C39.2%2C12.4&chf=bg%2Cs%2C00000000",
+ "chart": "//chart.googleapis.com/chart?chs=500x250&cht=p&chco=c4df9b%2C6fad0c&chf=bg%2Cs%2C00000000&chd=t%3A0.3%2C4.6%2C4.1%2C33.6%2C39.3%2C18.1&chl=Froyo%7CGingerbread%7CIce%20Cream%20Sandwich%7CJelly%20Bean%7CKitKat%7CLollipop",
"data": [
{
"api": 8,
@@ -168,82 +193,48 @@
{
"api": 10,
"name": "Gingerbread",
- "perc": "5.6"
+ "perc": "4.6"
},
{
"api": 15,
"name": "Ice Cream Sandwich",
- "perc": "5.1"
+ "perc": "4.1"
},
{
"api": 16,
"name": "Jelly Bean",
- "perc": "14.7"
+ "perc": "13.0"
},
{
"api": 17,
"name": "Jelly Bean",
- "perc": "17.5"
+ "perc": "15.9"
},
{
"api": 18,
"name": "Jelly Bean",
- "perc": "5.2"
+ "perc": "4.7"
},
{
"api": 19,
"name": "KitKat",
- "perc": "39.2"
+ "perc": "39.3"
},
{
"api": 21,
"name": "Lollipop",
- "perc": "11.6"
+ "perc": "15.5"
},
{
"api": 22,
"name": "Lollipop",
- "perc": "0.8"
+ "perc": "2.6"
}
]
}
];
-var SCREEN_DATA =
-[
- {
- "data": {
- "Large": {
- "hdpi": "0.6",
- "ldpi": "0.4",
- "mdpi": "4.8",
- "tvdpi": "2.2",
- "xhdpi": "0.6"
- },
- "Normal": {
- "hdpi": "39.9",
- "mdpi": "7.6",
- "tvdpi": "0.1",
- "xhdpi": "19.8",
- "xxhdpi": "15.9"
- },
- "Small": {
- "ldpi": "4.1"
- },
- "Xlarge": {
- "hdpi": "0.3",
- "mdpi": "3.1",
- "xhdpi": "0.6"
- }
- },
- "densitychart": "//chart.googleapis.com/chart?chco=c4df9b%2C6fad0c&cht=p&chs=400x250&chl=ldpi%7Cmdpi%7Ctvdpi%7Chdpi%7Cxhdpi%7Cxxhdpi&chd=t%3A4.5%2C15.5%2C2.3%2C40.8%2C21.0%2C15.9&chf=bg%2Cs%2C00000000",
- "layoutchart": "//chart.googleapis.com/chart?chco=c4df9b%2C6fad0c&cht=p&chs=400x250&chl=Xlarge%7CLarge%7CNormal%7CSmall&chd=t%3A4.0%2C8.6%2C83.3%2C4.1&chf=bg%2Cs%2C00000000"
- }
-];
-
-
-
var VERSION_NAMES =
[
{"api":0},{"api":1},{"api":2},{"api":3},
diff --git a/docs/html/tools/debugging/annotations.jd b/docs/html/tools/debugging/annotations.jd
index fe9f9cc..b0d5a22 100644
--- a/docs/html/tools/debugging/annotations.jd
+++ b/docs/html/tools/debugging/annotations.jd
@@ -7,7 +7,12 @@
<h2>In this document</h2>
<ol>
<li><a href="#adding-nullness">Adding Nullness Annotations</a></li>
- <li><a href="#res-annotations">Adding Resource Annotation</a></li>
+ <li><a href="#res-annotations">Adding Resource Annotations</a></li>
+ <li><a href="#thread-annotations">Adding Thread Annotations</a></li>
+ <li><a href="#value-constraint">Adding Value Constraint Annotations</a></li>
+ <li><a href="#permissions">Adding Permission Annotations</a></li>
+ <li><a href="#check-result">Adding CheckResult Annotations</a></li>
+ <li><a href="#call-super">Adding CallSuper Annotations</a></li>
<li><a href="#enum-annotations">Creating Enumerated Annotations</a></li>
</ol>
@@ -70,6 +75,10 @@
<dt>{@link android.support.annotation.AnyRes @AnyRes}</dt>
<dd>References any type of <a href="{@docRoot}reference/android/R.html"><code>R.</code></a>
resource. </dd>
+
+ <dt><code>@UiThread</code></dt>
+ <dd>Calls from a UI
+ <a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. </dd>
</dl>
<p>For a complete list of the supported annotations, either examine the contents of the
@@ -85,11 +94,14 @@
<p>To add annotations to your code, first add a dependency to the
{@link android.support.annotation Support-Annotations} library. In Android Studio,
-add the dependency to your <code>build.gradle</code> file. </p>
+add the dependency using the <strong>File > Project Structure > Dependencies</strong> menu
+option or your <code>build.gradle</code> file. The following example shows how to add the
+{@link android.support.annotation Support-Annotations} library dependency in the
+<code>build.gradle</code> file: </p>
<pre>
dependencies {
- compile 'com.android.support:support-annotations:22.0.0'
+ compile 'com.android.support:support-annotations:22.2.0'
}
</pre>
@@ -143,18 +155,20 @@
<h2 id="res-annotations">Adding Resource Annotations</h2>
-<p>Add {@link android.support.annotation.StringRes @StringRes} annotations to check that
-a resource parameter contains a
+<p>Validating resource types can be useful as Android references to resources, such as
+<a href="{@docRoot}guide/topics/resources/drawable-resource.html"><code>Drawables</code></a> and
+<a href="{@docRoot}reference/android/R.string.html"><code>R.string</code></a> resources, are
+passed as integers. Code that expects a parameter to reference a specific type of resource, for
+example <a href="{@docRoot}guide/topics/resources/drawable-resource.html"><code>Drawables</code></a>,
+can be passed the expected reference type of <code>int</code>, but actually reference a different
+type of resource, such as a <code>R.string</code></a> resource. </p>
+
+<p>For example, add {@link android.support.annotation.StringRes @StringRes} annotations to check
+that a resource parameter contains a
<a href="{@docRoot}reference/android/R.string.html"><code>R.string</code></a>
reference. During code inspection, the annotation generates a warning if a <code>R.string</code>
reference is not passed in the parameter.</p>
-<p>Validating resource types can be useful as Android references to
-<a href="{@docRoot}guide/topics/resources/drawable-resource.html"><code>Drawables</code></a> and
-<a href="{@docRoot}reference/android/R.string.html"><code>R.string</code></a> resources are both
-passed as integers. Code that expects a parameter to reference a <code>Drawable</code> can be passed
-the expected reference type of int, but actually reference a <code>R.string</code></a> resource. </p>
-
<p>This example attaches the {@link android.support.annotation.StringRes @StringRes}
annotation to the <code>resId</code> parameter to validate that it is really a string resource. </p>
@@ -168,11 +182,135 @@
<p>Annotations for the other resource types, such as
{@link android.support.annotation.DrawableRes @DrawableRes},
+{@link android.support.annotation.DimenRes @DimenRes},
{@link android.support.annotation.ColorRes @ColorRes}, and
{@link android.support.annotation.InterpolatorRes @InterpolatorRes} can be added using
the same annotation format and run during the code inspection. </p>
+
+
+<h2 id="thread-annotations">Adding Thread Annotations</h2>
+<p>Thread annotations check if a method is called from a specific type of
+<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. The following thread
+annotations are supported: </p>
+<ul>
+ <li><code>@UiThread</code> </li>
+ <li><code>@MainThread</code> </li>
+ <li><code>@WorkerThread</code> </li>
+ <li><code>@BinderThread</code>
+</ul>
+
+<p class="note"><strong>Note:</strong> The <code>@MainThread</code>
+and the <code>@UiThread</code> annotations are interchangeable so
+methods calls from either thread type are allowed for these annotations. </p>
+
+
+<p>If all methods in a class share the same threading requirement, you can add a single
+<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>
+annotation to the class to verify that all methods in the class are called from the same type of
+<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. </p>
+
+<p>A common use of the <a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>
+annotation is to validate method overrides in the
+<a href="{@docRoot}reference/android/os/AsyncTask.html">AsyncTask</a> class as this class performs
+background operations and publishes results only on the UI
+<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. </p>
+
+
+
+<h2 id="value-constraint">Adding Value Constraint Annotations</h2>
+<p>Use the <code>@IntRange</code>,
+<code>@FloatRange</code>, and
+<code>@Size</code> annotations to validate the values of passed
+parameters. </p>
+
+<p>The <code>@IntRange</code> annotation validates that the parameter
+value is within a specified range. The following example ensures that the <code>alpha</code>
+parameter contains an integer value from 0 to 255: </p>
+
+<pre>
+public void setAlpha(@IntRange(from=0,to=255) int alpha) { … }
+</pre>
+
+<p>The <code>@FloatRange</code> annotation checks that the parameter
+value is within a specified range of floating point values. The following example ensures that the
+<code>alpha</code> parameter contains a float value from 0.0 to 1.0: </p>
+
+<pre>
+public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}
+</pre>
+
+<p>The <code>@Size</code> annotation checks the size of a collection or
+array, as well as the length of a string. For example, use the <code>@Size(min=1)</code>
+annotation to check if a collection is not empty, and the <code>@Size(2)</code> annotation to
+validate that an array contains exactly two values. The following example ensures that the
+<code>location</code> array contains at least one element: </p>
+
+<pre>
+int[] location = new int[3];
+button.getLocationOnScreen(@Size(min=1) location);
+</pre>
+
+
+<h2 id="permissions">Adding Permission Annotations</h2>
+<p>Use the <code>@RequiresPermission</code> annotation to
+validate the permissions of the caller of a method. To check for a single permission from a
+list the valid permissions, use the <code>anyOf</code> attribute. To check for a set of
+permissions, use the <code>allOf</code> attribute. The following example annotates the
+<code>setWallpaper</code> method to ensure that the caller of the method has the
+<code>permission.SET_WALLPAPERS</code> permission. </p>
+
+<pre>
+@RequiresPermission(Manifest.permission.SET_WALLPAPER)
+public abstract void setWallpaper(Bitmap bitmap) throws IOException;
+</pre>
+
+<p>This example requires the caller of the
+<code>updateVisitedHistory</code> method to have both read and write bookmark history permissions. </p>
+
+<pre>
+@RequiresPermission(allOf = {
+ Manifest.permission.READ_HISTORY_BOOKMARKS,
+ Manifest.permission.WRITE_HISTORY_BOOKMARKS})
+public static final void updateVisitedHistory(ContentResolver cr, String url, boolean real) {
+ ...
+}
+</pre>
+
+
+<h2 id="check-result">Adding CheckResults Annotations</h2>
+<p>Use the <code>@CheckResults</code> annotation to
+validate that a method's result or return value is actually used. The following example annotates
+the <code>checkPermissions</code> method to ensure the return value of the method is actually
+referenced. It also names the
+<a href="{@docRoot}reference/android/content/ContextWrapper.html#enforcePermission">enforcePermission</a>
+method as a method to be suggested to the developer as a replacement. </p>
+
+
+
+<pre>
+@CheckResult(suggest="#enforcePermission(String,int,int,String)")
+public abstract int checkPermission(@NonNull String permission, int pid, int uid);
+</pre>
+
+{@link android.support.annotation.StringDef @StringDef}
+
+
+<h2 id="call-super">Adding CallSuper Annotations</h2>
+<p>Use the <code>@CallSuper</code> annotation to validate that an
+overriding method calls the super implementation of the method. The following example annotates
+the <code>onCreate</code> method to ensure that any overriding method implementations call
+<code>super.onCreate()</code>. </p>
+
+<pre>
+@CallSuper
+protected void onCreate(Bundle savedInstanceState) {
+}
+</pre>
+
+
+
<h2 id="enum-annotations">Creating Enumerated Annotations</h2>
<p>Use the {@link android.support.annotation.IntDef @IntDef} and
{@link android.support.annotation.StringDef @StringDef} annotations
diff --git a/docs/html/tools/studio/studio-features.jd b/docs/html/tools/studio/studio-features.jd
index 3d5b24c..44d6985 100644
--- a/docs/html/tools/studio/studio-features.jd
+++ b/docs/html/tools/studio/studio-features.jd
@@ -14,6 +14,7 @@
<li><a href="#project-settings">Android Studio and Project Settings</a></li>
<li><a href="#finger-print">Fingerprint Support</a></li>
<li><a href="#dev-services">Developer Services</a></li>
+ <li><a href="#private-res">Public and Private Resources</a></li>
<li><a href="#support-apis">Editor Support for the Latest Android APIs</a></li>
<li><a href="#test-module">Test APK Module</a></li>
</ol>
@@ -43,7 +44,8 @@
<h2 id="trans-editor">Translations Editor</h2>
<p>Multi-language support is enhanced with the Translations Editor plugin so you can easily add
a variety of locales to the app's translation file. With
-<a href="https://tools.ietf.org/html/bcp47">BCP 47</a> support, the editor combines language and
+<a class="external-link" href="https://tools.ietf.org/html/bcp47">BCP 47</a> support, the editor
+combines language and
region codes into a single selection for targeted localizations. Color codes indicate whether a
locale is complete or still missing string translations. </p>
@@ -167,6 +169,61 @@
+<h2 id="private-res">Public and Private Resources</h2>
+<p>By default, Android Studio treats all library resources as public: A public library resource is
+available to library clients for use outside the library, and appears in code completion suggestions
+and other resource references. Android Studio also, however, supports the use of private library
+resources. A private library resource can only be used within the source library, and does not
+appear in code completion lists and other resource references. </p>
+
+<p>You cannot explicitly declare a library resource as private. Instead, if you declare any library
+resources as public, Android Studio assumes all the other library resources are private. </p>
+
+<p>An app treats all Android library resources as public unless you explicitly declare at least one
+resource in the library as public. Declaring one public resource causes your app to treat all other,
+undeclared resources in the library as private. </p>
+
+<p class="note"><strong>Note:</strong> Declaring public and private resources requires the
+<a href="{@docRoot}tools/building/plugin-for-gradle.html">Android Plugin for Gradle</a> version
+1.3 or higher. </p>
+
+
+<p>To declare a resource as public and set other undeclared resources as private, add a
+<code><public></code> declaration with the resource name and type in the resource file.
+This example shows the public declaration for the <code>mylib_app_name</code> string resource. </p>
+
+<pre>
+<resources>
+ <public name="mylib_app_name" type="string"/>
+</resources>
+</pre>
+
+<p>For large numbers of declarations, we recommended that you place the public marker declarations
+in a separate file named <code>public.xml</code>. </p>
+
+<p>To help enforce private resource access, a <a href="{@docRoot}tools/help/lint.html">lint</a>
+warning appears when a client of a library references a private resource. Many Android libraries,
+such as the
+<a href="{@docRoot}tools/support-library/features.html#design">Design Support Library</a> and the
+<a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7 appcompat Library</a>,
+declare public resources to display only resources that developers can directly reference.
+</p>
+
+<p class="note"><strong>Note:</strong> If your app requires a private resource, copy the
+private resource from the library to the location in your app where it is needed. </p>
+
+<p>When the build system builds an Android Archive (AAR) file, it extracts the
+<code><public></code> resource declarations into a <code>public.txt</code> file, which is
+packaged inside the AAR file next to the <code>R.txt</code> file. The <code>public.txt</code> file
+contains a simple list of the declared public resources, describing their names and types. </p>
+
+<p>For a complete list of the available Android resource types, see
+<a href="http://developer.android.com/guide/topics/resources/available-resources.html">Resource
+Types</a></li> and
+<a href="http://developer.android.com/guide/topics/resources/more-resources.html">More Resource
+Types</a></li>. </p>
+
+
<h2 id="support-apis">Editor Support for the Latest Android APIs</h2>
<p>Android Studio supports the
@@ -277,4 +334,3 @@
app's <code>build.gradle</code> file. </p>
-
