1 files changed, 33 insertions, 19 deletions
diff --git a/docs/html/resources/tutorials/views/hello-relativelayout.jd b/docs/html/resources/tutorials/views/hello-relativelayout.jd
index 1b91537..adc1179 100644
--- a/docs/html/resources/tutorials/views/hello-relativelayout.jd
+++ b/docs/html/resources/tutorials/views/hello-relativelayout.jd
@@ -1,33 +1,38 @@
-page.title=Hello, RelativeLayout
+page.title=Relative Layout
 parent.title=Hello, Views
 parent.link=index.html
 @jd:body
 
-<p>A {@link android.widget.RelativeLayout} is a ViewGroup that allows you to layout child elements
-in positions relative to the parent or siblings elements.</p>
+<p>{@link android.widget.RelativeLayout} is a {@link android.view.ViewGroup} that displays
+child {@link android.view.View} elements in relative positions. The position of a {@link
+android.view.View} can be specified as relative to sibling elements (such as to the left-of or below
+a given element) or in positions relative to the {@link android.widget.RelativeLayout} area (such as
+aligned to the bottom, left of center).</p>
+
+<p>A {@link android.widget.RelativeLayout} is a very powerful utility for designing a user
+interface because it can eliminate nested {@link android.view.ViewGroup}s. If you find
+yourself using several nested {@link android.widget.LinearLayout} groups, you may be able to
+replace them with a single {@link android.widget.RelativeLayout}.</p>
 
 <ol>
-  <li>Start a new project/Activity called HelloRelativeLayout.</li>
-  <li>Open the layout file. Make it like so:
+  <li>Start a new project named <em>HelloRelativeLayout</em>.</li>
+  <li>Open the <code>res/layout/main.xml</code> file and insert the following:
 <pre>
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
     android:layout_width="fill_parent"
     android:layout_height="fill_parent">
-
     &lt;TextView
         android:id="@+id/label"
         android:layout_width="fill_parent"
         android:layout_height="wrap_content"
         android:text="Type here:"/>
-
     &lt;EditText
         android:id="@+id/entry"
         android:layout_width="fill_parent"
         android:layout_height="wrap_content"
         android:background="@android:drawable/editbox_background"
         android:layout_below="@id/label"/>
-
     &lt;Button
         android:id="@+id/ok"
         android:layout_width="wrap_content"
@@ -36,39 +41,48 @@ in positions relative to the parent or siblings elements.</p>
         android:layout_alignParentRight="true"
         android:layout_marginLeft="10dip"
         android:text="OK" />
-
     &lt;Button
         android:layout_width="wrap_content"
         android:layout_height="wrap_content"
         android:layout_toLeftOf="@id/ok"
         android:layout_alignTop="@id/ok"
         android:text="Cancel" />
-
 &lt;/RelativeLayout>
 </pre>
-<p>Pay attention to each of the additional <code>layout_*</code> attributes (besides the 
-usual width and height, which are required for all elements). When using relative layout,
-we use attributes like <code>layout_below</code> and <code>layout_toLeftOf</code> to describe
-how we'd like to position each View. Naturally, these are different relative positions, and the
-value of the attribute is the id of the element we want the position relative to.</p>
+<p>Notice each of the <code>android:layout_*</code> attributes, such as <code>layout_below</code>,
+<code>layout_alignParentRight</code>, and <code>layout_toLeftOf</code>. When using a {@link
+android.widget.RelativeLayout}, you can use these attributes to describe
+how you want to position each {@link android.view.View}. Each one of these attributes define a
+different kind
+of relative position. Some attributes use the resource ID of a sibling {@link android.view.View}
+to define its own relative position. For example, the last {@link android.widget.Button} is
+defined to lie to the left-of and aligned-with-the-top-of the {@link android.view.View}
+identified by the ID <code>ok</code> (which is the previous {@link android.widget.Button}).</p>
+<p>All of the available layout attributes are defined in {@link
+android.widget.RelativeLayout.LayoutParams}.</p>
 </li>
-<li>Make sure your Activity loads this layout in the <code>onCreate()</code> method:</p>
+<li>Make sure you load this layout in the
+{@link android.app.Activity#onCreate(Bundle) onCreate()} method:</p>
 <pre>
 public void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.main);
 }
 </pre>
-<p><code>R.layout.main</code> refers to the <code>main.xml</code> layout file.</p>
+<p>The {@link android.app.Activity#setContentView(int)} method loads the
+layout file for the {@link android.app.Activity}, specified by the resource
+ID &mdash; <code>R.layout.main</code> refers to the <code>res/layout/main.xml</code> layout
+file.</p>
 </li>
-<li>Run it.</li>
+<li>Run the application.</li>
 </ol>
-<p>You should see the following:</p>
+<p>You should see the following layout:</p>
 <img src="images/hello-relativelayout.png" width="150px" />
 
 <h3>Resources</h3>
 <ul>
   <li>{@link android.widget.RelativeLayout}</li>
+  <li>{@link android.widget.RelativeLayout.LayoutParams}</li>
   <li>{@link android.widget.TextView}</li>
   <li>{@link android.widget.EditText}</li>
   <li>{@link android.widget.Button}</li>