am 38137d7a: Merge "docs: lots of additions to the resources docs new drawable resources add <merge> and <include> to layout resource update drawable class descriptioons to point to resources guide add ID resource type" into froyo

Merge commit '38137d7a27b037611c70a9d900aa53b4c15563bf' into gingerbread

* commit '38137d7a27b037611c70a9d900aa53b4c15563bf':
  docs: lots of additions to the resources docs

core/java/android/view/View.java

@@ -7900,7 +7900,9 @@ public class View implements Drawable.Callback, KeyEvent.Callback, Accessibility
      * without resorting to another data structure.
      *
      * The specified key should be an id declared in the resources of the
-     * application to ensure it is unique. Keys identified as belonging to
+     * application to ensure it is unique (see the <a
+     * href={@docRoot}guide/topics/resources/more-resources.html#Id">ID resource type</a>).
+     * Keys identified as belonging to
      * the Android framework or not associated with any package will cause
      * an {@link IllegalArgumentException} to be thrown.
      *

docs/html/guide/topics/resources/available-resources.jd

@@ -18,23 +18,6 @@ of application resource that you can provide in your resources directory ({@code
 
 <p>Here's a brief summary of each resource type:</p>
 
-<div class="sidebox-wrapper">
-<div class="sidebox">
-<h2>{@code R.id} Is Not a Resource</h2>
-
-<p>You will often use an {@code R.id} integer to handle {@link android.view.View} objects in
-your UI. Although the {@code id} is a subclass of the {@code R} class, it is not considered a
-"resource" because it is not a reference to an externalized application resource. The {@code id}
-is simply a unique identifier that allows you to handle elements in your UI by instantiating
-objects with {@link android.app.Activity#findViewById(int) findViewById()}.</p>
-
-<p>For information about using {@code R.id} with your UI, see <a
-href="{@docRoot}guide/topics/ui/declaring-layout.html#attributes">Declaring Layout</a>.</p>
-
-</div>
-</div>
-
-
 <dl>
   <dt><a href="{@docRoot}guide/topics/resources/animation-resource.html">Animation Resources</a></dt>
     <dd>Define pre-determined animations.<br/>

docs/html/guide/topics/resources/layout-resource.jd

@@ -35,12 +35,12 @@ In XML: <code>@[<em>package</em>:]layout/<em>filename</em></code>
 <pre class="stx">
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;<a href="#viewgroup-element"><em>ViewGroup</em></a> xmlns:android="http://schemas.android.com/apk/res/android"
-    android:id="@+id/<em>name</em>"
+    android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"
     android:layout_height=["<em>dimension</em>" | "fill_parent" | "wrap_content"]
     android:layout_width=["<em>dimension</em>" | "fill_parent" | "wrap_content"]
     [<em>ViewGroup-specific attributes</em>] &gt;
     &lt;<a href="#view-element"><em>View</em></a>
-        android:id="@+id/<em>name</em>"
+        android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"
         android:layout_height=["<em>dimension</em>" | "fill_parent" | "wrap_content"]
         android:layout_width=["<em>dimension</em>" | "fill_parent" | "wrap_content"]
         [<em>View-specific attributes</em>] &gt;
@@ -49,10 +49,12 @@ In XML: <code>@[<em>package</em>:]layout/<em>filename</em></code>
     &lt;<a href="#viewgroup-element"><em>ViewGroup</em></a> &gt;
         &lt;<a href="#view-element"><em>View</em></a> /&gt;
     &lt;/<em>ViewGroup</em>&gt;
+    &lt;<a href="#include-element">include</a> layout="@layout/<i>layout_resource</i>"/&gt;
 &lt;/<em>ViewGroup</em>&gt;
 </pre>
 <p class="note"><strong>Note:</strong> The root element can be either a
-{@link android.view.ViewGroup} or a {@link android.view.View}, but there must be only
+{@link android.view.ViewGroup}, a {@link android.view.View}, or a <a
+href="#merge-element">{@code &lt;merge&gt;}</a> element, but there must be only
 one root element and it must contain the {@code xmlns:android} attribute with the {@code android}
 namespace as shown.</p>
 </dd>
@@ -74,10 +76,9 @@ namespace as shown.</p>
       <p class="caps">attributes:</p>
       <dl class="atn-list">
         <dt><code>android:id</code></dt>
-        <dd><em>Resource name</em>. A unique resource name for the element, which you can
+        <dd><em>Resource ID</em>. A unique resource name for the element, which you can
-use to obtain a reference to the {@link android.view.ViewGroup} from your application.
+use to obtain a reference to the {@link android.view.ViewGroup} from your application. See more
-          The value takes the form: <code>"@+id/<em>name</em>"</code>. See more about the
+about the <a href="#idvalue">value for {@code android:id}</a> below.
-          <a href="#idvalue">value for {@code android:id}</a> below.
         </dd>
         <dt><code>android:layout_height</code></dt>
         <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the group, as a
@@ -107,10 +108,9 @@ attributes</a>).</p>
       <p class="caps">attributes:</p>
       <dl class="atn-list">
         <dt><code>android:id</code></dt>
-        <dd><em>Resource name</em>. A unique resource name for the element, which you can use to
+        <dd><em>Resource ID</em>. A unique resource name for the element, which you can use to
-          obtain a reference to the {@link android.view.View} from your application.
+          obtain a reference to the {@link android.view.View} from your application. See more about
-          The value takes the form: <code>"@+id/<em>name</em>"</code>. See more about the
+the <a href="#idvalue">value for {@code android:id}</a> below.
-          <a href="#idvalue">value for {@code android:id}</a> below.
         </dd>
         <dt><code>android:layout_height</code></dt>
         <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the element, as
@@ -137,20 +137,71 @@ or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> bel
     which gives it's parent initial focus on the screen. You can have only one of these
     elements per file.</dd>
 
+  <dt id="include-element"><code>&lt;include&gt;</code></dt>
+    <dd>Includes a layout file into this layout.
+      <p class="caps">attributes:</p>
+      <dl class="atn-list">
+        <dt><code>layout</code></dt>
+        <dd><em>Layout resource</em>. <strong>Required</strong>. Reference to a layout
+resource.</dd>
+        <dt><code>android:id</code></dt>
+        <dd><em>Resource ID</em>. Overrides the ID given to the root view in the included layout.
+        </dd>
+        <dt><code>android:layout_height</code></dt>
+        <dd><em>Dimension or keyword</em>. Overrides the height given to the root view in the
+included layout.
+        </dd>
+        <dt><code>android:layout_width</code></dt>
+        <dd><em>Dimension or keyword</em>. Overrides the width given to the root view in the
+included layout.
+        </dd>
       </dl>
+      <p>You can include any other layout attributes in the <code>&lt;include&gt;</code> that are
+supported by the root element in the included layout and they will override those defined in the
+root element.</p>
+
+    <p>Another way to include a layout is to use {@link android.view.ViewStub}. It is a lightweight
+View that consumes no layout space until you explicitly inflate it, at which point, it includes a
+layout file defined by its {@code android:layout} attribute. For more information about using {@link
+android.view.ViewStub}, read <a href="{@docRoot}resources/articles/layout-tricks-stubs.html">Layout
+Tricks: ViewStubs</a>.</p>
+    </dd>
+
+  <dt id="merge-element"><code>&lt;merge&gt;</code></dt>
+    <dd>An alternative root element that is not drawn in the layout hierarchy. Using this as the
+root element is useful when you know that this layout will be placed into a layout
+that already contains the appropriate parent View to contain the children of the
+<code>&lt;merge&gt;</code> element. This is particularly useful when you plan to include this layout
+in another layout file using <a href="#include-element"><code>&lt;include&gt;</code></a> and
+this layout doesn't require a different {@link android.view.ViewGroup} container. For more
+information about merging layouts, read <a
+href="{@docRoot}resources/articles/layout-tricks-merging.html">Layout
+Tricks: Merging</a>.</dd>
+
+  </dl>
+
+
 
 <h4 id="idvalue">Value for <code>android:id</code></h4>
 
-<p>For the ID value, you should use this syntax form: <code>"@+id/<em>name</em>"</code>. The plus symbol,
+<p>For the ID value, you should usually use this syntax form: <code>"@+id/<em>name</em>"</code>. The
-{@code +}, indicates that this is a new resource ID and the aapt tool will create
+plus symbol, {@code +}, indicates that this is a new resource ID and the <code>aapt</code> tool will
-a new resource number to the {@code R.java} class, if it doesn't already exist. For example:</p>
+create a new resource integer in the {@code R.java} class, if it doesn't already exist. For
+example:</p>
 <pre>
 &lt;TextView android:id="@+id/nameTextbox"/>
 </pre>
-<p>You can then refer to it this way in Java:</p>
+<p>The <code>nameTextbox</code> name is now a resource ID attached to this element. You can then
+refer to the {@link android.widget.TextView} to which the ID is associated in Java:</p>
 <pre>
 findViewById(R.id.nameTextbox);
 </pre>
+<p>This code returns the {@link android.widget.TextView} object.</p>
+
+<p>However, if you have already defined an <a
+href="{@docRoot}guide/topics/resources/drawable-resource.html#Id">ID resource</a> (and it is not
+already used), then you can apply that ID to a {@link android.view.View} element by excluding the
+plus symbol in the <code>android:id</code> value.</p>
 
 <h4 id="layoutvalues">Value for <code>android:layout_height</code> and
 <code>android:layout_width</code>:</h4>

docs/html/guide/topics/resources/menu-resource.jd

@@ -35,7 +35,7 @@ In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code>
 <pre>
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;<a href="#menu-element">menu</a> xmlns:android="http://schemas.android.com/apk/res/android">
-    &lt;<a href="#item-element">item</a> android:id="@+id/<em>id_name</em>"
+    &lt;<a href="#item-element">item</a> android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"
           android:menuCategory=["container" | "system" | "secondary" | "alternative"]
           android:orderInCategory="<em>integer</em>"
           android:title="<em>string</em>"
@@ -46,7 +46,7 @@ In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code>
           android:checkable=["true" | "false"]
           android:visible=["visible" | "invisible" | "gone"]
           android:enabled=["enabled" | "disabled"] /&gt;
-    &lt;<a href="#group-element">group</a> android:id="<em>resource ID</em>"
+    &lt;<a href="#group-element">group</a> android:id="@[+][<em>package</em>:]id/<em>resource name</em>"
            android:menuCategory=["container" | "system" | "secondary" | "alternative"]
            android:orderInCategory="<em>integer</em>"
            android:checkableBehavior=["none" | "all" | "single"]
@@ -84,8 +84,8 @@ child of a <code>&lt;menu&gt;</code> element.
       <p class="caps">attributes:</p>
       <dl class="atn-list">
         <dt><code>android:id</code></dt>
-        <dd><em>Resource name</em>. A unique resource name. The value takes the form:
+        <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form:
-<code>"@+id/<em>name</em>"</code>.</dd>
+<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new ID.</dd>
         <dt><code>android:menuCategory</code></dt>
           <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*}
           constants, which define the group's priority. Valid values:
@@ -124,8 +124,8 @@ on the data that is currently displayed.</td></tr>
       <p class="caps">attributes:</p>
       <dl class="atn-list">
         <dt><code>android:id</code></dt>
-        <dd><em>Resource name</em>. A unique resource name. The value takes the form:
+        <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form:
-<code>"@+id/<em>name</em>"</code>.</dd>
+<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new ID.</dd>
         <dt><code>android:menuCategory</code></dt>
           <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*}
           constants, which define the item's priority. Valid values:

docs/html/guide/topics/resources/more-resources.jd

@@ -12,6 +12,9 @@ parent.link=available-resources.html
     <dd>XML resource that carries a color value (a hexadecimal color).</dd>
   <dt><a href="#Dimension">Dimension</a></dt>
     <dd>XML resource that carries a dimension value (with a unit of measure).</dd>
+  <dt><a href="#Id">ID</a></dt>
+    <dd>XML resource that provides a unique identifier for application resources and
+components.</dd>
   <dt><a href="#Integer">Integer</a></dt>
     <dd>XML resource that carries an integer value.</dd>
   <dt><a href="#IntegerArray">Integer Array</a></dt>
@@ -111,8 +114,8 @@ boolean screenIsSmall = res.{@link android.content.res.Resources#getBoolean(int)
 <h2 id="Color">Color</h2>
 
 <p>A color value defined in XML.
-The color is specified with an RGB value and alpha channel. A color resource can be used
+The color is specified with an RGB value and alpha channel. You can use color resource
-any place that expects a hexadecimal color value.</p>
+any place that accepts a hexadecimal color value.</p>
 
 <p>The value always begins with a pound (#) character and then followed by the
 Alpha-Red-Green-Blue information in one of the following formats:</p>
@@ -318,6 +321,118 @@ float fontSize = res.{@link android.content.res.Resources#getDimension(int) getD
 
 
 
+<h2 id="Id">ID</h2>
+
+<p>A unique resource ID defined in XML. Using the name you provide in the {@code &lt;item&gt;}
+element, the Android developer tools create a unique integer in your project's {@code
+R.java} class, which you can use as an
+identifier for an application resources (for example, a {@link android.view.View} in your UI layout)
+or a unique integer for use in your application code (for example, as an ID for a dialog or a
+result code).</p>
+
+<p class="note"><strong>Note:</strong> An ID is a simple resource that is referenced
+using the value provided in the {@code name} attribute (not the name of the XML file). As
+such, you can combine ID resources with other simple resources in the one XML file,
+under one {@code &lt;resources&gt;} element. Also, remember that an ID resources does not reference
+an actual resource item; it is simply a unique ID that you can attach to other resources or use
+as a unique integer in your application.</p>
+
+<dl class="xml">
+
+<dt>file location:</dt>
+<dd><code>res/values/<em>filename.xml</em></code><br/>
+The filename is arbitrary.</dd>
+
+<dt>resource reference:</dt>
+<dd>
+In Java: <code>R.id.<em>name</em></code><br/>
+In XML: <code>@[<em>package</em>:]id/<em>name</em></code>
+</dd>
+
+<dt>syntax:</dt>
+<dd>
+<pre class="stx">
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;<a href="#id-resources-element">resources</a>&gt;
+    &lt;<a href="#id-item-element">item</a>
+        type="id"
+        name="<em>id_name</em>" /&gt;
+&lt;/resources&gt;
+</pre>
+</dd>
+
+<dt>elements:</dt>
+<dd>
+<dl class="tag-list">
+
+  <dt id="integer-resources-element"><code>&lt;resources&gt;</code></dt>
+    <dd><strong>Required.</strong> This must be the root node.
+      <p>No attributes.</p>
+    </dd>
+  <dt id="integer-element"><code>&lt;integer&gt;</code></dt>
+    <dd>Defines a unique ID. Takes no value, only attributes.
+      <p class="caps">attributes:</p>
+      <dl class="atn-list">
+        <dt><code>type</code></dt>
+        <dd>Must be "id".</dd>
+        <dt><code>name</code></dt>
+        <dd><em>String</em>. A unique name for the ID.</dd>
+      </dl>
+    </dd>
+
+</dl>
+</dd> <!-- end  elements and attributes -->
+
+<dt>example:</dt>
+<dd>
+  <p>XML file saved at <code>res/values/ids.xml</code>:</p>
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;item type="id" name="button_ok" /&gt;
+    &lt;item type="id" name="dialog_exit" /&gt;
+&lt;/resources>
+</pre>
+
+    <p>Then, this layout snippet uses the "button_ok" ID for a Button widget:</p>
+<pre>
+&lt;Button android:id="<b>@id/button_ok</b>"
+    style="@style/button_style" /&gt;
+</pre>
+
+    <p>Notice that the {@code android:id} value does not include the plus sign in the ID reference,
+because the ID already exists, as defined in the {@code ids.xml} example above. (When you specify an
+ID to an XML resource using the plus sign&mdash;in the format {@code
+android:id="@+id/name"}&mdash;it means that the "name" ID does not exist and should be created.)</p>
+
+  <p>As another example, the following code snippet uses the "dialog_exit" ID as a unique identifier
+for a dialog:</p>
+<pre>
+{@link android.app.Activity#showDialog(int) showDialog}(<b>R.id.dialog_exit</b>);
+</pre>
+  <p>In the same application, the "dialog_exit" ID is compared when creating a dialog:</p>
+<pre>
+protected Dialog {@link android.app.Activity#onCreateDialog(int)}(int id) {
+    Dialog dialog;
+    switch(id) {
+    case <b>R.id.dialog_exit</b>:
+        ...
+        break;
+    default:
+        dialog = null;
+    }
+    return dialog;
+}
+</pre>
+</dd> <!-- end example -->
+
+
+</dl>
+
+
+
+
+
 <h2 id="Integer">Integer</h2>
 
 <p>An integer defined in XML.</p>
@@ -347,7 +462,7 @@ In XML: <code>@[<em>package</em>:]integer/<em>integer_name</em></code>
 &lt;<a href="#integer-resources-element">resources</a>>
     &lt;<a href="#integer-element">integer</a>
         name="<em>integer_name</em>"
-        &gt;<em>integer</em>&lt;/dimen&gt;
+        &gt;<em>integer</em>&lt;/integer&gt;
 &lt;/resources&gt;
 </pre>
 </dd>
@@ -379,8 +494,8 @@ In XML: <code>@[<em>package</em>:]integer/<em>integer_name</em></code>
 <pre>
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;resources>
-    &lt;integer name="max_speed">75&lt;/dimen>
+    &lt;integer name="max_speed">75&lt;/integer>
-    &lt;integer name="min_speed">5&lt;/dimen>
+    &lt;integer name="min_speed">5&lt;/integer>
 &lt;/resources>
 </pre>
     <p>This application code retrieves an integer:</p>

graphics/java/android/graphics/drawable/AnimationDrawable.java

@@ -64,6 +64,8 @@ import android.util.AttributeSet;
  * // Start the animation (looped playback by default).
  * frameAnimation.start()
  * </pre>
+ * <p>For more information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/animation-resource.html">Animation Resources</a>.</p>
  *
  * @attr ref android.R.styleable#AnimationDrawable_visible
  * @attr ref android.R.styleable#AnimationDrawable_variablePadding

graphics/java/android/graphics/drawable/BitmapDrawable.java

@@ -40,7 +40,9 @@ import java.io.IOException;
  * A Drawable that wraps a bitmap and can be tiled, stretched, or aligned. You can create a
  * BitmapDrawable from a file path, an input stream, through XML inflation, or from
  * a {@link android.graphics.Bitmap} object.
- * <p>It can be defined in an XML file with the <code>&lt;bitmap></code> element.</p>
+ * <p>It can be defined in an XML file with the <code>&lt;bitmap></code> element.  For more
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
  * <p>
  * Also see the {@link android.graphics.Bitmap} class, which handles the management and 
  * transformation of raw bitmap graphics, and should be used when drawing to a 

graphics/java/android/graphics/drawable/ClipDrawable.java

@@ -32,9 +32,14 @@ import java.io.IOException;
  * level value.  You can control how much the child Drawable gets clipped in width
  * and height based on the level, as well as a gravity to control where it is
  * placed in its overall container.  Most often used to implement things like
- * progress bars.
+ * progress bars, by increasing the drawable's level with {@link
+ * android.graphics.drawable.Drawable#setLevel(int) setLevel()}.
+ * <p class="note"><strong>Note:</strong> The drawable is clipped completely and not visible when
+ * the level is 0 and fully revealed when the level is 10,000.</p>
  *
- * <p>It can be defined in an XML file with the <code>&lt;clip></code> element.</p>
+ * <p>It can be defined in an XML file with the <code>&lt;clip></code> element.  For more
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
  *
  * @attr ref android.R.styleable#ClipDrawable_clipOrientation
  * @attr ref android.R.styleable#ClipDrawable_gravity

graphics/java/android/graphics/drawable/Drawable.java

@@ -93,8 +93,8 @@ import android.util.TypedValue;
  *     whose overall size is modified based on the current level.
  * </ul>
  * <p>For information and examples of creating drawable resources (XML or bitmap files that
- * can be loaded in code), see <a href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources
+ * can be loaded in code), see <a
- * and Internationalization</a>.
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.
  */
 public abstract class Drawable {
     private static final Rect ZERO_BOUNDS_RECT = new Rect();
@@ -709,8 +709,7 @@ public abstract class Drawable {
     /**
      * Create a drawable from an XML document. For more information on how to
      * create resources in XML, see
-     * <a href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources and
+     * <a href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.
-     * Internationalization</a>.
      */
     public static Drawable createFromXml(Resources r, XmlPullParser parser)
             throws XmlPullParserException, IOException {

graphics/java/android/graphics/drawable/GradientDrawable.java

@@ -42,7 +42,9 @@ import java.io.IOException;
 /**
  * A Drawable with a color gradient for buttons, backgrounds, etc. 
  *
- * <p>It can be defined in an XML file with the <code>&lt;shape></code> element.</p>
+ * <p>It can be defined in an XML file with the <code>&lt;shape></code> element. For more
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
  *
  * @attr ref android.R.styleable#GradientDrawable_visible
  * @attr ref android.R.styleable#GradientDrawable_shape

graphics/java/android/graphics/drawable/InsetDrawable.java

@@ -32,7 +32,9 @@ import java.io.IOException;
  * This is used when a View needs a background that is smaller than
  * the View's actual bounds.
  *
- * <p>It can be defined in an XML file with the <code>&lt;inset></code> element.</p>
+ * <p>It can be defined in an XML file with the <code>&lt;inset></code> element. For more
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
  *
  * @attr ref android.R.styleable#InsetDrawable_visible
  * @attr ref android.R.styleable#InsetDrawable_drawable

graphics/java/android/graphics/drawable/LayerDrawable.java

@@ -32,8 +32,9 @@ import java.io.IOException;
  * order, so the element with the largest index will be drawn on top.
  * <p>
  * It can be defined in an XML file with the <code>&lt;layer-list></code> element.
- * Each Drawable in the layer is defined in a nested <code>&lt;item></code>.
+ * Each Drawable in the layer is defined in a nested <code>&lt;item></code>. For more
- * </p>
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
  *
  * @attr ref android.R.styleable#LayerDrawableItem_left
  * @attr ref android.R.styleable#LayerDrawableItem_top

graphics/java/android/graphics/drawable/LevelListDrawable.java

@@ -47,7 +47,10 @@ import android.util.AttributeSet;
  * <p>With this XML saved into the res/drawable/ folder of the project, it can be referenced as
  * the drawable for an {@link android.widget.ImageView}. The default image is the first in the list.
  * It can then be changed to one of the other levels with
- * {@link android.widget.ImageView#setImageLevel(int)}.</p>
+ * {@link android.widget.ImageView#setImageLevel(int)}. For more
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
+ *
  * @attr ref android.R.styleable#LevelListDrawableItem_minLevel
  * @attr ref android.R.styleable#LevelListDrawableItem_maxLevel
  * @attr ref android.R.styleable#LevelListDrawableItem_drawable

graphics/java/android/graphics/drawable/RotateDrawable.java

@@ -35,7 +35,9 @@ import java.io.IOException;
  * value. The start and end angles of rotation can be controlled to map any
  * circular arc to the level values range.</p>
  *
- * <p>It can be defined in an XML file with the <code>&lt;rotate></code> element.</p>
+ * <p>It can be defined in an XML file with the <code>&lt;rotate></code> element. For more
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/animation-resource.html">Animation Resources</a>.</p>
  *
  * @attr ref android.R.styleable#RotateDrawable_visible
  * @attr ref android.R.styleable#RotateDrawable_fromDegrees

graphics/java/android/graphics/drawable/ScaleDrawable.java

@@ -34,7 +34,9 @@ import java.io.IOException;
  * placed in its overall container.  Most often used to implement things like
  * progress bars.
  *
- * <p>It can be defined in an XML file with the <code>&lt;scale></code> element.</p>
+ * <p>It can be defined in an XML file with the <code>&lt;scale></code> element. For more
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
  *
  * @attr ref android.R.styleable#ScaleDrawable_scaleWidth
  * @attr ref android.R.styleable#ScaleDrawable_scaleHeight

graphics/java/android/graphics/drawable/ShapeDrawable.java

@@ -34,6 +34,10 @@ import java.io.IOException;
  * the ShapeDrawable will default to a 
  * {@link android.graphics.drawable.shapes.RectShape}.
  *
+ * <p>It can be defined in an XML file with the <code>&lt;shape></code> element. For more
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
+ *
  * @attr ref android.R.styleable#ShapeDrawablePadding_left
  * @attr ref android.R.styleable#ShapeDrawablePadding_top
  * @attr ref android.R.styleable#ShapeDrawablePadding_right

graphics/java/android/graphics/drawable/StateListDrawable.java

@@ -31,7 +31,9 @@ import android.util.StateSet;
  * ID value.
  * <p/>
  * <p>It can be defined in an XML file with the <code>&lt;selector></code> element.
- * Each state Drawable is defined in a nested <code>&lt;item></code> element.</p>
+ * Each state Drawable is defined in a nested <code>&lt;item></code> element. For more
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
  *
  * @attr ref android.R.styleable#StateListDrawable_visible
  * @attr ref android.R.styleable#StateListDrawable_variablePadding

graphics/java/android/graphics/drawable/TransitionDrawable.java

@@ -26,8 +26,10 @@ import android.os.SystemClock;
  * display just the first layer, call {@link #resetTransition()}.
  * <p>
  * It can be defined in an XML file with the <code>&lt;transition></code> element.
- * Each Drawable in the transition is defined in a nested <code>&lt;item></code>.
+ * Each Drawable in the transition is defined in a nested <code>&lt;item></code>. For more
- * </p>
+ * information, see the guide to <a
+ * href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
+ *
  * @attr ref android.R.styleable#LayerDrawableItem_left
  * @attr ref android.R.styleable#LayerDrawableItem_top
  * @attr ref android.R.styleable#LayerDrawableItem_right
@@ -212,7 +214,7 @@ public class TransitionDrawable extends LayerDrawable implements Drawable.Callba
      * Enables or disables the cross fade of the drawables. When cross fade
      * is disabled, the first drawable is always drawn opaque. With cross
      * fade enabled, the first drawable is drawn with the opposite alpha of
-     * the second drawable.
+     * the second drawable. Cross fade is disabled by default.
      *
      * @param enabled True to enable cross fading, false otherwise.
      */