Merge change 24559 into donut

* changes:
  docs only. add documentation to notify developers about variable camera specifications and add some more links

core/java/android/hardware/Camera.java

@@ -35,6 +35,23 @@ import android.os.Message;
  * frames for encoding for video.
  * <p>There is no default constructor for this class. Use {@link #open()} to
  * get a Camera object.</p>
+ *
+ * <p>In order to use the device camera, you must declare the 
+ * {@link android.Manifest.permission#CAMERA} permission in your Android 
+ * Manifest. Also be sure to include the
+ * <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature></a>
+ * manifest element in order to declare camera features used by your application. 
+ * For example, if you use the camera and auto-focus feature, your Manifest 
+ * should include the following:</p>
+ * <pre> &lt;uses-permission android:name="android.permission.CAMERA" />
+ * &lt;uses-feature android:name="android.hardware.camera" />
+ * &lt;uses-feature android:name="android.hardware.camera.autofocus" /></pre>
+ *
+ * <p class="caution"><strong>Caution:</strong> Different Android-powered devices
+ * may have different hardware specifications, such as megapixel ratings and
+ * auto-focus capabilities. In order for your application to be compatible with
+ * more devices, you should not make assumptions about the device camera 
+ * specifications.</p>
  */
 public class Camera {
     private static final String TAG = "Camera";
@@ -172,8 +189,9 @@ public class Camera {
         /**
          * The callback that delivers the preview frames.
          *
-         * @param data The contents of the preview frame in getPreviewFormat()
-         *             format.
+         * @param data The contents of the preview frame in the format defined
+         *  by {@link android.graphics.PixelFormat}, which can be queried 
+         *  with {@link android.hardware.Camera.Parameters#getPreviewFormat()}.
          * @param camera The Camera service object.
          */
         void onPreviewFrame(byte[] data, Camera camera);
@@ -296,6 +314,13 @@ public class Camera {
 
     /**
      * Handles the callback for the camera auto focus.
+     * <p>Devices that do not support auto-focus will receive a "fake" 
+     * callback to this interface. If your application needs auto-focus and 
+     * should not be installed on devices <em>without</em> auto-focus, you must
+     * declare that your app uses the
+     * {@code android.hardware.camera.autofocus} feature, in the 
+     * <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature></a>
+     * manifest element.</p>
      */
     public interface AutoFocusCallback
     {
@@ -312,6 +337,14 @@ public class Camera {
      * Starts auto-focus function and registers a callback function to
      * run when camera is focused. Only valid after startPreview() has
      * been called.
+     * <p>Devices that do not support auto-focus will trigger a "fake" 
+     * callback to the 
+     * {@link android.hardware.Camera.AutoFocusCallback}. 
+     * If your application should not be installed
+     * on devices without auto-focus, you must declare that your application 
+     * uses auto-focus with the 
+     * <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature></a>
+     * manifest element.</p>
      * 
      * @param cb the callback to run
      */
@@ -668,10 +701,15 @@ public class Camera {
         }
 
         /**
-         * Sets the image format for preview pictures.
+         * Sets the image format for preview pictures. 
+         * <p>If the image format is not set with this method, then the
+         * preview format will default to 
+         * {@link android.graphics.PixelFormat#YCbCr_420_SP}, which
+         * uses the NV21 encoding format.</p>
          * 
-         * @param pixel_format the desired preview picture format 
-         *                     (<var>PixelFormat.YCbCr_420_SP</var>,
+         * @param pixel_format the desired preview picture format, defined
+         *   by one of the {@link android.graphics.PixelFormat} constants.
+         *   (E.g., <var>PixelFormat.YCbCr_420_SP</var> (default),
          *                      <var>PixelFormat.RGB_565</var>, or
          *                      <var>PixelFormat.JPEG</var>)
          * @see android.graphics.PixelFormat
@@ -688,7 +726,8 @@ public class Camera {
         /**
          * Returns the image format for preview pictures.
          * 
-         * @return the PixelFormat int representing the preview picture format
+         * @return the {@link android.graphics.PixelFormat} int representing 
+         *         the preview picture format.
          */
         public int getPreviewFormat() {
             return pixelFormatForCameraFormat(get("preview-format"));

graphics/java/android/graphics/PixelFormat.java

@@ -52,6 +52,12 @@ public class PixelFormat
      * by the hardware.
      */
     public static final int YCbCr_422_SP= 0x10;
+
+    /** YCbCr format used for images, which uses the NV21 encoding format.   
+     *  This is the default format for camera preview images, when not
+     *  otherwise set with 
+     *  {@link android.hardware.Camera.Parameters#setPreviewFormat(int)}.
+     */
     public static final int YCbCr_420_SP= 0x11;
 
     /**