DOC CHANGE: Bug 3396898 add attribute uses-library

Change-Id: I21810676050abed04c0c69b61c05d8d7228f434d

diff --git a/docs/html/guide/topics/manifest/uses-library-element.jd b/docs/html/guide/topics/manifest/uses-library-element.jd
index f1b5e70..1d38c1a 100644 (file)
--- a/docs/html/guide/topics/manifest/uses-library-element.jd
+++ b/docs/html/guide/topics/manifest/uses-library-element.jd
@@ -3,34 +3,101 @@ page.title=<uses-library>
 
 <dl class="xml">
 <dt>syntax:</dt>
-<dd><pre>&lt;uses-library android:<a href="#nm">name</a>="<i>string</i>" /&gt;</pre></dd>
-
+<dd>
+<pre class="stx">
+&lt;uses-library android:<a href="#nm">name</a>="<var>string</var>"
+              android:<a href="#rq">required</a>=["true" | "false"] /&gt;
+</pre>
+</dd>
 <dt>contained in:</dt>
-<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
-
+<dd>
+    <code>
+        <a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a>
+    </code>
+</dd>
 <dt>description:</dt>
-<dd>Specifies a shared library that the application must be linked against. 
-This element tells the system to include the library's code in the class 
-loader for the package.
-
-<p>
-All of the {@code android} packages (such as {@link android.app}, 
-{@link android.content}, {@link android.view}, and {@link android.widget}) 
-are in the default library that all applications are automatically linked 
-against.  However, some packages (such as {@code maps} and {@code awt} are 
-in separate libraries that are not automatically linked.  Consult the 
-documentation for the packages you're using to determine which library 
-contains the package code.
-</p></dd>
-
+<dd>
+    Specifies a shared library that the application must be linked against.
+    This element tells the system to include the library's code in the class
+    loader for the package.
+    <p>
+        All of the {@code android} packages (such as {@link android.app},
+        {@link android.content}, {@link android.view}, and {@link android.widget})
+        are in the default library that all applications are automatically linked
+        against.  However, some packages (such as {@code maps}) are
+        in separate libraries that are not automatically linked.  Consult the
+        documentation for the packages you're using to determine which library
+        contains the package code.
+    </p>
+    <p>
+        This element also affects the installation of the application on a particular device and
+        the availability of the application in Android Market:
+    </p>
+    <dl>
+        <dt><em>Installation</em></dt>
+        <dd>
+            If this element is present and its {@code android:required} attribute is set to
+            {@code true}, the {@link android.content.pm.PackageManager} framework won't let the user
+            install the application unless the library is present on the user's device.
+        </dd>
+        <dt><em>Market</em></dt>
+        <dd>
+            Android Market filters applications based on the libraries installed on the
+            user's device. For more information about filtering, see the topic
+            <a href="{@docRoot}/guide/appendix/market-filters.html">Market Filters</a>.
+        </dd>
+    </dl>
+    <p>
+        The {@code android:required} attribute is described in detail in the following section.
+    </p>
+</dd>
 <dt>attributes:</dt>
-<dd><dl class="attr">
-<dt><a name="nm"></a>{@code android:name}</dt>
-<dd>The name of the library.</dd>
-</dl></dd>
-
+<dd>
+    <dl class="attr">
+        <dt><a name="nm"></a>{@code android:name}</dt>
+        <dd>
+            The name of the library. The name is provided by the
+            documentation for the package you are using. An example of this is
+            &quot;<code>android.test.runner</code>&quot;, a package that contains Android test
+            classes.
+        </dd>
+        <dt><a name="rq"></a>{@code android:required}</dt>
+        <dd>
+            Boolean value that indicates whether the application requires the
+            library specified by {@code android:name}:
+            <ul>
+                <li>
+                    <code>&quot;true&quot;</code>: The application does not function without this
+                    library. The system will not allow the application on a device that does not
+                    have the library.
+                </li>
+                <li>
+                    <code>&quot;false&quot;</code>: The application can use the
+                    library if present, but is designed to function without it if necessary.
+                    The system will allow the application to be installed, even if the library is
+                    not present. If you use <code>&quot;false&quot;</code>, you are responsible for
+                    checking at runtime that the library is available.
+                    <p>
+                        To check for a library, you can use reflection to determine
+                        if a particular class is available.
+                    </p>
+                </li>
+            </ul>
+            <p>
+                The default is <code>&quot;true&quot;</code>.
+            </p>
+            <p>Introduced in: API Level 7.</p>
+        </dd>
+    </dl>
+</dd>
 <!-- ##api level indication## -->
 <dt>introduced in:</dt>
 <dd>API Level 1</dd>
 
-</dl>
+<dt>see also:</dt>
+<dd>
+  <ul>
+    <li>{@link android.content.pm.PackageManager}</li>
+  </ul>
+</dd>
+</dl>
\ No newline at end of file