diff options
Diffstat (limited to 'docs/html/tools')
| -rw-r--r-- | docs/html/tools/debugging/annotations.jd | 160 | ||||
| -rw-r--r-- | docs/html/tools/studio/studio-features.jd | 60 |
2 files changed, 207 insertions, 13 deletions
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 @@ page.title=Improving Code Inspection with Annotations <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 @@ values in your code, for example:</p> <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 @@ development tools.</p> <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 @@ inferring nullability in Android Studio, see <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 @@ import android.support.annotation.StringRes; <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 @@ page.tags=studio, features <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 @@ and <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 @@ detail about starting the services, refer to each service's specific activation +<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 @@ properties for the project path and target build type variant. </p> app's <code>build.gradle</code> file. </p> - |