Merge change Iab5952e1 into eclair

* changes:
  docs: add "required" attribute to the <uses-feature> docs and add a note to the CAMERA permission stating that it enables the <uses-feature> for camera. This is an incrimental update for the 2.0.1 docs. More changes to come for the 2.1 docs to include more features

core/res/AndroidManifest.xml

@@ -403,7 +403,13 @@
         android:label="@string/permlab_recordAudio"
         android:description="@string/permdesc_recordAudio" />
 
-    <!-- Required to be able to access the camera device. -->
+    <!-- Required to be able to access the camera device.
+         <p>This will automatically enforce the <a
+         href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code
+         &lt;uses-feature&gt;}</a> manifest element for <em>all</em> camera features.
+         If you do not require all camera features or can properly operate if a camera
+         is not available, then you must modify your manifest as appropriate in order to
+         install on devices that don't support all camera features.</p> -->
     <permission android:name="android.permission.CAMERA"
         android:permissionGroup="android.permission-group.HARDWARE_CONTROLS"
         android:protectionLevel="dangerous"

docs/html/guide/topics/manifest/uses-feature-element.jd

@@ -7,17 +7,20 @@ page.title=<uses-feature>
 <dd>
 <pre class="stx">
 &lt;uses-feature android:<a href="#glEsVersion">glEsVersion</a>="<em>integer</em>"
-              android:<a href="#name">name</a>="<em>string</em>" /&gt;
+              android:<a href="#name">name</a>="<em>string</em>"
+              android:<a href="#required">required</a>=["true" | "false"] /&gt;
 </pre>
 </dd>
 
 <dt>contained in:</dt>
-<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
+<dd><code><a
+href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
 
 <dt>description:</dt>
 <dd>This element declares a specific feature used by the application.
 Android provides some features that may not be equally supported by all
-Android devices. In a manner similar to the <code><a href="uses-sdk-element.html">&lt;uses-sdk></a></code> 
+Android devices. In a manner similar to the <code><a
+href="uses-sdk-element.html">&lt;uses-sdk></a></code>
 element, this element allows an application to specify which device-variable
 features it uses. In this way, the application
 will not be installed on devices that do not offer the feature.</p>
@@ -27,14 +30,14 @@ If a device does not provide a camera with auto-focus, then it will not allow
 installation of the application.</p>
 
 <p>In order to maintain strict device compatibility, it's very important that you use
-this element to declare all features that your application uses. Failure to declare
+this element to declare all applicable features (listed below) that your application uses. Failure
-a feature may result your application being installed on a device
+to declare a feature may result in your application being installed on a device
 that does not support the feature and your application failing.</p>
 
 <p>For some features, there may exist a specfic attribute that allows you to define
 a version of the feature, such as the version of Open GL used (declared with
 <a href="#glEsVersion">{@code glEsVersion}</a>). Other features that either do or do not
-exist for a device, such as camera auto-focus, are declared using the
+exist for a device, such as a camera, are declared using the
 <a href="#name">{@code name}</a> attribute.</p>
 
 <p>Any software or hardware features that may vary among Android-powered
@@ -47,13 +50,12 @@ camera, then you should include the following in your {@code AndroidManifest.xml
 &lt;uses-feature android:name="android.hardware.camera" />
 </pre>
 
-<p>If you declare "android.hardware.camera", then your application is considered
+<p>If you declare {@code android.hardware.camera}, then your application is considered
-compatible with all devices that include a camera, regardless of whether auto-focus is
+compatible with all devices that include a camera. If your application also uses auto-focus
-available or not. If you also use the auto-focus features (available through the {@link
+features, then you also need to include a
-android.hardware.Camera Camera API}), then you need to include an additional
+{@code &lt;uses-feature>} element that declares the {@code android.hardware.camera.autofocus}
-{@code &lt;uses-feature>} element that declares the "android.hardware.camera.autofocus"
 feature. Also note that you must still request the {@link android.Manifest.permission#CAMERA
-CAMERA permission}. Requesting permission grants your application access to the
+CAMERA} permission. Requesting permission grants your application access to the
 appropriate hardware and software, while declaring the features used by
 your application ensures proper device compatibility.</p>
 
@@ -75,50 +77,69 @@ instance of this element.</p>
 <dt>attributes:</dt>
 
 <dd>
-<dl class="attr"><dt><a name="glEsVersion"></a>{@code android:glEsVersion}</dt>
+<dl class="attr">
+  <dt><a name="glEsVersion"></a>{@code android:glEsVersion}</dt>
   <dd>The GLES version needed by the application.
      The higher 16 bits represent the major number and the lower 16 bits
      represent the minor number. For example, for GL 1.2 referring to
      0x00000102, the actual value should be set as 0x00010002.
   </dd>
-</dl>
-</dd>
 
-<dd>
+  <dt><a name="name"></a>{@code android:name}</dt>
-<dl class="attr"><dt><a name="name"></a>{@code android:name}</dt>
   <dd>The name of a feature required by the application. 
   The value must be one of the following accepted strings:
-  
+
-  <table> 
+  <table>
     <tr> 
        <th>Feature</th>
        <th>Value</th> 
        <th>Description</th> 
-    </tr><tr> 
+    </tr><tr>
-       <td rowspan="3">Camera</td>
+       <td rowspan="2">Camera</td>
        <td>"{@code android.hardware.camera}"</td> 
        <td>The application requires a camera.</td> 
-    </tr><tr> 
+    </tr><tr>
-       <td>"{@code android.hardware.camera.autofocus}"</td> 
-       <td>The application requires a camera with auto-focus capability.
-       As a prerequisite, "{@code android.hardware.camera}" must also be declared
-       with a separate {@code &lt;uses-feature>} element.
-       </td>
-     <tr>
        <td colspan="2">
          <strong>Note:</strong> Any application that requests the 
-         {@link android.Manifest.permission#CAMERA CAMERA permission} but does <em>not</em>
+         {@link android.Manifest.permission#CAMERA} permission but does <em>not</em>
          declare any camera features with the {@code &lt;uses-feature>} element will be assumed
-         to use all camera features (such as auto-focus). Thus, the application will not
+         to use all camera features (auto-focus and flash). Thus, the application will not
-         be compatible with devices that do not support all features. Please use 
+         be compatible with devices that do not support all camera features. Please use
-         {@code &lt;uses-feature>} to declare only the camera features that your 
+         {@code &lt;uses-feature>} to declare only the camera features that your
-         application needs.
+         application does need. For instance, if you requests the
+         {@link android.Manifest.permission#CAMERA} permission, but does not need auto-focus or
+          flash, then declare only the {@code android.hardware.camera} feature&mdash;the camera
+          features that you do not request will no longer be assumed as required.
        </td>
-     </tr>
+    </tr><tr>
+      <td>Camera auto-focus</td>
+      <td>"{@code android.hardware.camera.autofocus}"</td>
+      <td>The application requires a camera with auto-focus capability.
+       As a prerequisite, "{@code android.hardware.camera}" must also be declared
+       with a separate {@code &lt;uses-feature>} element.
+      </td>
     </tr>
   </table>
-  
   </dd>
+
+  <dt><a name="required"></a>{@code android:required}</dt>  <!-- added in api level 5 -->
+  <dd>Indicates whether the feature is required by the application. This is
+    "true" by default. <strong>You should not use this attribute for most cases.</strong>
+    </p>
+
+    <p>The only situation in which you should set this attribute "false" is when your application
+    requests the {@link android.Manifest.permission#CAMERA} permission, but will degrade gracefully
+    and perform without failure if the device does not have a camera. In this situation, you must
+    declare the "{@code android.hardware.camera}" feature and set the {@code required} attribute
+    "false". This is necessary because the {@link android.Manifest.permission#CAMERA} permission
+    will automatically turn on the requirement for all camera features. So if your application uses
+    this permission but is still compatible with devices without a camera, then you must set this
+    attribute "false" for "{@code android.hardware.camera}" or else it will not install on devices
+    without a camera. Note that, while the permission will enable the requirement for <em>all</em>
+    camera features, you only need to off the requirement for the basic camera feature.</p>
+
+  </dd>
+
 </dl>
 </dd>