resolved conflicts for merge of 9bc4039a to gingerbread

Change-Id: I6f9262fb293a67cbc04e5756205ae56e28c299ec

1 files changed, 315 insertions, 147 deletions

diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index 1100886..19e578f 100644
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -32,23 +32,79 @@ import android.os.Looper;
 import android.os.Message;
 
 /**
- * The Camera class is used to connect/disconnect with the camera service,
- * set capture settings, start/stop preview, snap a picture, and retrieve
- * frames for encoding for video.
- * <p>There is no default constructor for this class. Use {@link #open()} to
- * get a Camera object.</p>
+ * The Camera class is used to set image capture settings, start/stop preview,
+ * snap pictures, and retrieve frames for encoding for video.  This class is a
+ * client for the Camera service, which manages the actual camera hardware.
  *
- * <p>In order to use the device camera, you must declare the
+ * <p>To access 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.
+ * manifest element 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>To take pictures with this class, use the following steps:</p>
+ *
+ * <ol>
+ * <li>Obtain an instance of Camera from {@link #open(int)}.
+ *
+ * <li>Get existing (default) settings with {@link #getParameters()}.
+ *
+ * <li>If necessary, modify the returned {@link Camera.Parameters} object and call
+ * {@link #setParameters(Camera.Parameters)}.
+ *
+ * <li>If desired, call {@link #setDisplayOrientation(int)}.
+ *
+ * <li><b>Important</b>: Pass a fully initialized {@link SurfaceHolder} to
+ * {@link #setPreviewDisplay(SurfaceHolder)}.  Without a surface, the camera
+ * will be unable to start the preview.
+ *
+ * <li><b>Important</b>: Call {@link #startPreview()} to start updating the
+ * preview surface.  Preview must be started before you can take a picture.
+ *
+ * <li>When you want, call {@link #takePicture(Camera.ShutterCallback,
+ * Camera.PictureCallback, Camera.PictureCallback, Camera.PictureCallback)} to
+ * capture a photo.  Wait for the callbacks to provide the actual image data.
+ *
+ * <li>After taking a picture, preview display will have stopped.  To take more
+ * photos, call {@link #startPreview()} again first.
+ *
+ * <li>Call {@link #stopPreview()} to stop updating the preview surface.
+ *
+ * <li><b>Important:</b> Call {@link #release()} to release the camera for
+ * use by other applications.  Applications should release the camera
+ * immediately in {@link android.app.Activity#onPause()} (and re-{@link #open()}
+ * it in {@link android.app.Activity#onResume()}).
+ * </ol>
+ *
+ * <p>To quickly switch to video recording mode, use these steps:</p>
+ *
+ * <ol>
+ * <li>Obtain and initialize a Camera and start preview as described above.
+ *
+ * <li>Call {@link #unlock()} to allow the media process to access the camera.
+ *
+ * <li>Pass the camera to {@link android.media.MediaRecorder#setCamera(Camera)}.
+ * See {@link android.media.MediaRecorder} information about video recording.
+ *
+ * <li>When finished recording, call {@link #reconnect()} to re-acquire
+ * and re-lock the camera.
+ *
+ * <li>If desired, restart preview and take more photos or videos.
+ *
+ * <li>Call {@link #stopPreview()} and {@link #release()} as described above.
+ * </ol>
+ *
+ * <p>This class is not thread-safe, and is meant for use from one event thread.
+ * Most long-running operations (preview, focus, photo capture, etc) happen
+ * asynchronously and invoke callbacks as necessary.  Callbacks will be invoked
+ * on the event thread {@link #open(int)} was called from.  This class's methods
+ * must never be called from multiple threads at once.</p>
+ *
  * <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
@@ -84,12 +140,12 @@ public class Camera {
     private boolean mWithBuffer;
 
     /**
-     * Returns the number of Cameras available.
+     * Returns the number of physical cameras available on this device.
      */
     public native static int getNumberOfCameras();
 
     /**
-     * Returns the information about the camera.
+     * Returns the information about a particular camera.
      * If {@link #getNumberOfCameras()} returns N, the valid id is 0 to N-1.
      */
     public native static void getCameraInfo(int cameraId, CameraInfo cameraInfo);
@@ -123,9 +179,30 @@ public class Camera {
     };
 
     /**
-     * Returns a new Camera object.
-     * If {@link #getNumberOfCameras()} returns N, the valid id is 0 to N-1.
-     * The id 0 is the default camera.
+     * Creates a new Camera object to access a particular hardware camera.
+     *
+     * <p>You must call {@link #release()} when you are done using the camera,
+     * otherwise it will remain locked and be unavailable to other applications.
+     *
+     * <p>Your application should only have one Camera object active at a time
+     * for a particular hardware camera.
+     *
+     * <p>Callbacks from other methods are delivered to the event loop of the
+     * thread which called open().  If this thread has no event loop, then
+     * callbacks are delivered to the main application event loop.  If there
+     * is no main application event loop, callbacks are not delivered.
+     *
+     * <p class="caution"><b>Caution:</b> On some devices, this method may
+     * take a long time to complete.  It is best to call this method from a
+     * worker thread (possibly using {@link android.os.AsyncTask}) to avoid
+     * blocking the main application UI thread.
+     *
+     * @param cameraId the hardware camera to access, between 0 and
+     *     {@link #getNumberOfCameras()}-1.  Use {@link #CAMERA_ID_DEFAULT}
+     *     to access the default camera.
+     * @return a new Camera object, connected, locked and ready for use.
+     * @throws RuntimeException if connection to the camera service fails (for
+     *     example, if the camera is in use by another process).
      */
     public static Camera open(int cameraId) {
         return new Camera(cameraId);
@@ -137,7 +214,8 @@ public class Camera {
     public static int CAMERA_ID_DEFAULT = 0;
 
     /**
-     * Returns a new Camera object. This returns the default camera.
+     * Equivalent to Camera.open(Camera.CAMERA_ID_DEFAULT).
+     * Creates a new Camera object to access the default camera.
      */
     public static Camera open() {
         return new Camera(CAMERA_ID_DEFAULT);
@@ -173,56 +251,83 @@ public class Camera {
 
     /**
      * Disconnects and releases the Camera object resources.
-     * <p>It is recommended that you call this as soon as you're done with the
-     * Camera object.</p>
+     *
+     * <p>You must call this as soon as you're done with the Camera object.</p>
      */
     public final void release() {
         native_release();
     }
 
     /**
-     * Reconnect to the camera after passing it to MediaRecorder. To save
-     * setup/teardown time, a client of Camera can pass an initialized Camera
-     * object to a MediaRecorder to use for video recording. Once the
-     * MediaRecorder is done with the Camera, this method can be used to
-     * re-establish a connection with the camera hardware. NOTE: The Camera
-     * object must first be unlocked by the process that owns it before it
-     * can be connected to another process.
+     * Unlocks the camera to allow another process to access it.
+     * Normally, the camera is locked to the process with an active Camera
+     * object until {@link #release()} is called.  To allow rapid handoff
+     * between processes, you can call this method to release the camera
+     * temporarily for another process to use; once the other process is done
+     * you can call {@link #reconnect()} to reclaim the camera.
+     *
+     * <p>This must be done before calling
+     * {@link android.media.MediaRecorder#setCamera(Camera)}.
      *
-     * @throws IOException if the method fails.
+     * <p>If you are not recording video, you probably do not need this method.
+     *
+     * @throws RuntimeException if the camera cannot be unlocked.
      */
-    public native final void reconnect() throws IOException;
+    public native final void unlock();
 
     /**
-     * Lock the camera to prevent other processes from accessing it. To save
-     * setup/teardown time, a client of Camera can pass an initialized Camera
-     * object to another process. This method is used to re-lock the Camera
-     * object prevent other processes from accessing it. By default, the
-     * Camera object is locked. Locking it again from the same process will
-     * have no effect. Attempting to lock it from another process if it has
-     * not been unlocked will fail.
+     * Re-locks the camera to prevent other processes from accessing it.
+     * Camera objects are locked by default unless {@link #unlock()} is
+     * called.  Normally {@link #reconnect()} is used instead.
      *
-     * @throws RuntimeException if the method fails.
+     * <p>If you are not recording video, you probably do not need this method.
+     *
+     * @throws RuntimeException if the camera cannot be re-locked (for
+     *     example, if the camera is still in use by another process).
      */
     public native final void lock();
 
     /**
-     * Unlock the camera to allow another process to access it. To save
-     * setup/teardown time, a client of Camera can pass an initialized Camera
-     * object to another process. This method is used to unlock the Camera
-     * object before handing off the Camera object to the other process.
+     * Reconnects to the camera service after another process used it.
+     * After {@link #unlock()} is called, another process may use the
+     * camera; when the process is done, you must reconnect to the camera,
+     * which will re-acquire the lock and allow you to continue using the
+     * camera.
      *
-     * @throws RuntimeException if the method fails.
+     * <p>This must be done after {@link android.media.MediaRecorder} is
+     * done recording if {@link android.media.MediaRecorder#setCamera(Camera)}
+     * was used.
+     *
+     * <p>If you are not recording video, you probably do not need this method.
+     *
+     * @throws IOException if a connection cannot be re-established (for
+     *     example, if the camera is still in use by another process).
      */
-    public native final void unlock();
+    public native final void reconnect() throws IOException;
 
     /**
-     * Sets the SurfaceHolder to be used for a picture preview. If the surface
-     * changed since the last call, the screen will blank. Nothing happens
-     * if the same surface is re-set.
+     * Sets the {@link Surface} to be used for live preview.
+     * A surface is necessary for preview, and preview is necessary to take
+     * pictures.  The same surface can be re-set without harm.
+     *
+     * <p>The {@link SurfaceHolder} must already contain a surface when this
+     * method is called.  If you are using {@link android.view.SurfaceView},
+     * you will need to register a {@link SurfaceHolder.Callback} with
+     * {@link SurfaceHolder#addCallback(SurfaceHolder.Callback)} and wait for
+     * {@link SurfaceHolder.Callback#surfaceCreated(SurfaceHolder)} before
+     * calling setPreviewDisplay() or starting preview.
+     *
+     * <p>This method must be called before {@link #startPreview()}.  The
+     * one exception is that if the preview surface is not set (or set to null)
+     * before startPreview() is called, then this method may be called once
+     * with a non-null parameter to set the preview surface.  (This allows
+     * camera setup and surface creation to happen in parallel, saving time.)
+     * The preview surface may not otherwise change while preview is running.
      *
-     * @param holder the SurfaceHolder upon which to place the picture preview
-     * @throws IOException if the method fails.
+     * @param holder containing the Surface on which to place the preview,
+     *     or null to remove the preview surface
+     * @throws IOException if the method fails (for example, if the surface
+     *     is unavailable or unsuitable).
      */
     public final void setPreviewDisplay(SurfaceHolder holder) throws IOException {
         if (holder != null) {
@@ -235,31 +340,47 @@ public class Camera {
     private native final void setPreviewDisplay(Surface surface);
 
     /**
-     * Used to get a copy of each preview frame.
+     * Callback interface used to deliver copies of preview frames as
+     * they are displayed.
+     *
+     * @see #setPreviewCallback(Camera.PreviewCallback)
+     * @see #setOneShotPreviewCallback(Camera.PreviewCallback)
+     * @see #setPreviewCallbackWithBuffer(Camera.PreviewCallback)
+     * @see #startPreview()
      */
     public interface PreviewCallback
     {
         /**
-         * The callback that delivers the preview frames.
+         * Called as preview frames are displayed.  This callback is invoked
+         * on the event thread {@link #open(int)} was called from.
          *
-         * @param data The contents of the preview frame in the format defined
+         * @param data the contents of the preview frame in the format defined
          *  by {@link android.graphics.ImageFormat}, which can be queried
          *  with {@link android.hardware.Camera.Parameters#getPreviewFormat()}.
          *  If {@link android.hardware.Camera.Parameters#setPreviewFormat(int)}
          *             is never called, the default will be the YCbCr_420_SP
          *             (NV21) format.
-         * @param camera The Camera service object.
+         * @param camera the Camera service object.
          */
         void onPreviewFrame(byte[] data, Camera camera);
     };
 
     /**
-     * Start drawing preview frames to the surface.
+     * Starts capturing and drawing preview frames to the screen.
+     * Preview will not actually start until a surface is supplied with
+     * {@link #setPreviewDisplay(SurfaceHolder)}.
+     *
+     * <p>If {@link #setPreviewCallback(Camera.PreviewCallback)},
+     * {@link #setOneShotPreviewCallback(Camera.PreviewCallback)}, or
+     * {@link #setPreviewCallbackWithBuffer(Camera.PreviewCallback)} were
+     * called, {@link Camera.PreviewCallback#onPreviewFrame(byte[], Camera)}
+     * will be called when preview data becomes available.
      */
     public native final void startPreview();
 
     /**
-     * Stop drawing preview frames to the surface.
+     * Stops capturing and drawing preview frames to the surface, and
+     * resets the camera for a future call to {@link #startPreview()}.
      */
     public native final void stopPreview();
 
@@ -272,11 +393,13 @@ public class Camera {
     public native final boolean previewEnabled();
 
     /**
-     * Can be called at any time to instruct the camera to use a callback for
-     * each preview frame in addition to displaying it.
+     * Installs a callback to be invoked for every preview frame in addition
+     * to displaying them on the screen.  The callback will be repeatedly called
+     * for as long as preview is active.  This method can be called at any time,
+     * even while preview is live.  Any other preview callbacks are overridden.
      *
-     * @param cb A callback object that receives a copy of each preview frame.
-     *           Pass null to stop receiving callbacks at any time.
+     * @param cb a callback object that receives a copy of each preview frame,
+     *     or null to stop receiving callbacks.
      */
     public final void setPreviewCallback(PreviewCallback cb) {
         mPreviewCallback = cb;
@@ -288,10 +411,13 @@ public class Camera {
     }
 
     /**
-     * Installs a callback to retrieve a single preview frame, after which the
-     * callback is cleared.
+     * Installs a callback to be invoked for the next preview frame in addition
+     * to displaying it on the screen.  After one invocation, the callback is
+     * cleared. This method can be called any time, even when preview is live.
+     * Any other preview callbacks are overridden.
      *
-     * @param cb A callback object that receives a copy of the preview frame.
+     * @param cb a callback object that receives a copy of the next preview frame,
+     *     or null to stop receiving callbacks.
      */
     public final void setOneShotPreviewCallback(PreviewCallback cb) {
         mPreviewCallback = cb;
@@ -303,17 +429,24 @@ public class Camera {
     private native final void setHasPreviewCallback(boolean installed, boolean manualBuffer);
 
     /**
-     * Installs a callback which will get called as long as there are buffers in the
-     * preview buffer queue, which minimizes dynamic allocation of preview buffers.
+     * Installs a callback to be invoked for every preview frame, using buffers
+     * supplied with {@link #addCallbackBuffer(byte[])}, in addition to
+     * displaying them on the screen.  The callback will be repeatedly called
+     * for as long as preview is active and buffers are available.
+     * Any other preview callbacks are overridden.
      *
-     * Apps must call addCallbackBuffer to explicitly register the buffers to use, or no callbacks
-     * will be received. addCallbackBuffer may be safely called before or after
-     * a call to setPreviewCallbackWithBuffer with a non-null callback parameter.
+     * <p>The purpose of this method is to improve preview efficiency and frame
+     * rate by allowing preview frame memory reuse.  You must call
+     * {@link #addCallbackBuffer(byte[])} at some point -- before or after
+     * calling this method -- or no callbacks will received.
      *
-     * The buffer queue will be cleared upon any calls to setOneShotPreviewCallback,
-     * setPreviewCallback, or to this method with a null callback parameter.
+     * The buffer queue will be cleared if this method is called with a null
+     * callback, {@link #setPreviewCallback(Camera.PreviewCallback)} is called,
+     * or {@link #setOneShotPreviewCallback(Camera.PreviewCallback)} is called.
      *
-     * @param cb A callback object that receives a copy of the preview frame.  A null value will clear the queue.
+     * @param cb a callback object that receives a copy of the preview frame,
+     *     or null to stop receiving callbacks and clear the buffer queue.
+     * @see #addCallbackBuffer(byte[])
      */
     public final void setPreviewCallbackWithBuffer(PreviewCallback cb) {
         mPreviewCallback = cb;
@@ -325,21 +458,27 @@ public class Camera {
     /**
      * Adds a pre-allocated buffer to the preview callback buffer queue.
      * Applications can add one or more buffers to the queue. When a preview
-     * frame arrives and there is still available buffer, buffer will be filled
-     * and it is removed from the queue. Then preview callback is invoked with
-     * the buffer. If a frame arrives and there is no buffer left, the frame is
-     * discarded. Applications should add the buffers back when they finish the
-     * processing.
+     * frame arrives and there is still at least one available buffer, the
+     * buffer will be used and removed from the queue. Then preview callback is
+     * invoked with the buffer. If a frame arrives and there is no buffer left,
+     * the frame is discarded. Applications should add buffers back when they
+     * finish processing the data in them.
      *
-     * The image format of the callback buffer can be read from {@link
-     * android.hardware.Camera.Parameters#getPreviewFormat()}. bitsPerPixel can
-     * be read from {@link android.graphics.ImageFormat#getBitsPerPixel(int)}.
-     * Preview width and height can be determined from getPreviewSize.
+     * <p>The size of the buffer is determined by multiplying the preview
+     * image width, height, and bytes per pixel.  The width and height can be
+     * read from {@link Camera.Parameters#getPreviewSize()}.  Bytes per pixel
+     * can be computed from
+     * {@link android.graphics.ImageFormat#getBitsPerPixel(int)} / 8,
+     * using the image format from {@link Camera.Parameters#getPreviewFormat()}.
      *
-     * Alternatively, a buffer from a previous callback may be passed in or used
-     * to determine the size of new preview frame buffers.
+     * <p>This method is only necessary when
+     * {@link #setPreviewCallbackWithBuffer(PreviewCallback)} is used.  When
+     * {@link #setPreviewCallback(PreviewCallback)} or
+     * {@link #setOneShotPreviewCallback(PreviewCallback)} are used, buffers
+     * are automatically allocated.
      *
-     * @param callbackBuffer The buffer to register. Size should be width * height * bitsPerPixel / 8.
+     * @param callbackBuffer the buffer to add to the queue.
+     *     The size should be width * height * bits_per_pixel / 8.
      * @see #setPreviewCallbackWithBuffer(PreviewCallback)
      */
     public native final void addCallbackBuffer(byte[] callbackBuffer);
@@ -438,7 +577,8 @@ public class Camera {
     }
 
     /**
-     * Handles the callback for the camera auto focus.
+     * Callback interface used to notify on completion of 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
@@ -446,13 +586,15 @@ public class Camera {
      * {@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>
+     *
+     * @see #autoFocus(AutoFocusCallback)
      */
     public interface AutoFocusCallback
     {
         /**
-         * Callback for the camera auto focus. If the camera does not support
-         * auto-focus and autoFocus is called, onAutoFocus will be called
-         * immediately with success.
+         * Called when the camera auto focus completes.  If the camera does not
+         * support auto-focus and autoFocus is called, onAutoFocus will be
+         * called immediately with success.
          *
          * @param success true if focus was successful, false if otherwise
          * @param camera  the Camera service object
@@ -461,23 +603,28 @@ 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.
-     * Applications should call {@link
-     * android.hardware.Camera.Parameters#getFocusMode()} to determine if this
-     * method should be called. If the camera does not support auto-focus, it is
-     * a no-op and {@link AutoFocusCallback#onAutoFocus(boolean, Camera)}
+     * Starts camera auto-focus and registers a callback function to run when
+     * the camera is focused.  This method is only valid when preview is active
+     * (between {@link #startPreview()} and before {@link #stopPreview()}).
+     *
+     * <p>Callers should check
+     * {@link android.hardware.Camera.Parameters#getFocusMode()} to determine if
+     * this method should be called. If the camera does not support auto-focus,
+     * it is a no-op and {@link AutoFocusCallback#onAutoFocus(boolean, Camera)}
      * callback will be called immediately.
+     *
      * <p>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>
+     *
      * <p>If the current flash mode is not
      * {@link android.hardware.Camera.Parameters#FLASH_MODE_OFF}, flash may be
-     * fired during auto-focus depending on the driver.<p>
+     * fired during auto-focus, depending on the driver and camera hardware.<p>
      *
      * @param cb the callback to run
+     * @see #cancelAutoFocus()
      */
     public final void autoFocus(AutoFocusCallback cb)
     {
@@ -487,10 +634,12 @@ public class Camera {
     private native final void native_autoFocus();
 
     /**
-     * Cancels auto-focus function. If the auto-focus is still in progress,
-     * this function will cancel it. Whether the auto-focus is in progress
-     * or not, this function will return the focus position to the default.
+     * Cancels any auto-focus function in progress.
+     * Whether or not auto-focus is currently in progress,
+     * this function will return the focus position to the default.
      * If the camera does not support auto-focus, this is a no-op.
+     *
+     * @see #autoFocus(Camera.AutoFocusCallback)
      */
     public final void cancelAutoFocus()
     {
@@ -500,23 +649,32 @@ public class Camera {
     private native final void native_cancelAutoFocus();
 
     /**
-     * An interface which contains a callback for the shutter closing after taking a picture.
+     * Callback interface used to signal the moment of actual image capture.
+     *
+     * @see #takePicture(ShutterCallback, PictureCallback, PictureCallback, PictureCallback)
      */
     public interface ShutterCallback
     {
         /**
-         * Can be used to play a shutter sound as soon as the image has been captured, but before
-         * the data is available.
+         * Called as near as possible to the moment when a photo is captured
+         * from the sensor.  This is a good opportunity to play a shutter sound
+         * or give other feedback of camera operation.  This may be some time
+         * after the photo was triggered, but some time before the actual data
+         * is available.
          */
         void onShutter();
     }
 
     /**
-     * Handles the callback for when a picture is taken.
+     * Callback interface used to supply image data from a photo capture.
+     *
+     * @see #takePicture(ShutterCallback, PictureCallback, PictureCallback, PictureCallback)
      */
     public interface PictureCallback {
         /**
-         * Callback for when a picture is taken.
+         * Called when image data is available after a picture is taken.
+         * The format of the data depends on the context of the callback
+         * and {@link Camera.Parameters} settings.
          *
          * @param data   a byte array of the picture data
          * @param camera the Camera service object
@@ -525,24 +683,9 @@ public class Camera {
     };
 
     /**
-     * Triggers an asynchronous image capture. The camera service will initiate
-     * a series of callbacks to the application as the image capture progresses.
-     * The shutter callback occurs after the image is captured. This can be used
-     * to trigger a sound to let the user know that image has been captured. The
-     * raw callback occurs when the raw image data is available (NOTE: the data
-     * may be null if the hardware does not have enough memory to make a copy).
-     * The jpeg callback occurs when the compressed image is available. If the
-     * application does not need a particular callback, a null can be passed
-     * instead of a callback method.
+     * Equivalent to takePicture(shutter, raw, null, jpeg).
      *
-     * This method is only valid after {@link #startPreview()} has been called.
-     * This method will stop the preview. Applications should not call {@link
-     * #stopPreview()} before this. After jpeg callback is received,
-     * applications can call {@link #startPreview()} to restart the preview.
-     *
-     * @param shutter   callback after the image is captured, may be null
-     * @param raw       callback with raw image data, may be null
-     * @param jpeg      callback with jpeg image data, may be null
+     * @see #takePicture(ShutterCallback, PictureCallback, PictureCallback, PictureCallback)
      */
     public final void takePicture(ShutterCallback shutter, PictureCallback raw,
             PictureCallback jpeg) {
@@ -563,15 +706,18 @@ public class Camera {
      * application does not need a particular callback, a null can be passed
      * instead of a callback method.
      *
-     * This method is only valid after {@link #startPreview()} has been called.
-     * This method will stop the preview. Applications should not call {@link
-     * #stopPreview()} before this. After jpeg callback is received,
-     * applications can call {@link #startPreview()} to restart the preview.
+     * <p>This method is only valid when preview is active (after
+     * {@link #startPreview()}).  Preview will be stopped after the image is
+     * taken; callers must call {@link #startPreview()} again if they want to
+     * re-start preview or take more pictures.
+     *
+     * <p>After calling this method, you must not call {@link #startPreview()}
+     * or take another picture until the JPEG callback has returned.
      *
-     * @param shutter   callback after the image is captured, may be null
-     * @param raw       callback with raw image data, may be null
+     * @param shutter   the callback for image capture moment, or null
+     * @param raw       the callback for raw (uncompressed) image data, or null
      * @param postview  callback with postview image data, may be null
-     * @param jpeg      callback with jpeg image data, may be null
+     * @param jpeg      the callback for JPEG image data, or null
      */
     public final void takePicture(ShutterCallback shutter, PictureCallback raw,
             PictureCallback postview, PictureCallback jpeg) {
@@ -583,26 +729,29 @@ public class Camera {
     }
 
     /**
-     * Zooms to the requested value smoothly. Driver will notify {@link
+     * Zooms to the requested value smoothly. The driver will notify {@link
      * OnZoomChangeListener} of the zoom value and whether zoom is stopped at
      * the time. For example, suppose the current zoom is 0 and startSmoothZoom
-     * is called with value 3. Method onZoomChange will be called three times
-     * with zoom value 1, 2, and 3. The applications can call {@link
-     * #stopSmoothZoom} to stop the zoom earlier. The applications should not
-     * call startSmoothZoom again or change the zoom value before zoom stops. If
-     * the passing zoom value equals to the current zoom value, no zoom callback
-     * will be generated. This method is supported if {@link
-     * android.hardware.Camera.Parameters#isSmoothZoomSupported} is true.
+     * is called with value 3. The
+     * {@link Camera.OnZoomChangeListener#onZoomChange(int, boolean, Camera)}
+     * method will be called three times with zoom values 1, 2, and 3.
+     * Applications can call {@link #stopSmoothZoom} to stop the zoom earlier.
+     * Applications should not call startSmoothZoom again or change the zoom
+     * value before zoom stops. If the supplied zoom value equals to the current
+     * zoom value, no zoom callback will be generated. This method is supported
+     * if {@link android.hardware.Camera.Parameters#isSmoothZoomSupported}
+     * returns true.
      *
      * @param value zoom value. The valid range is 0 to {@link
      *              android.hardware.Camera.Parameters#getMaxZoom}.
      * @throws IllegalArgumentException if the zoom value is invalid.
      * @throws RuntimeException if the method fails.
+     * @see #setZoomChangeListener(OnZoomChangeListener)
      */
     public native final void startSmoothZoom(int value);
 
     /**
-     * Stops the smooth zoom. The applications should wait for the {@link
+     * Stops the smooth zoom. Applications should wait for the {@link
      * OnZoomChangeListener} to know when the zoom is actually stopped. This
      * method is supported if {@link
      * android.hardware.Camera.Parameters#isSmoothZoomSupported} is true.
@@ -649,20 +798,21 @@ public class Camera {
     public native final void setDisplayOrientation(int degrees);
 
     /**
-     * Interface for a callback to be invoked when zoom value changes.
+     * Callback interface for zoom changes during a smooth zoom operation.
+     *
+     * @see #setZoomChangeListener(OnZoomChangeListener)
+     * @see #startSmoothZoom(int)
      */
     public interface OnZoomChangeListener
     {
         /**
-         * Called when the zoom value has changed.
+         * Called when the zoom value has changed during a smooth zoom.
          *
          * @param zoomValue the current zoom value. In smooth zoom mode, camera
          *                  calls this for every new zoom value.
          * @param stopped whether smooth zoom is stopped. If the value is true,
          *                this is the last zoom update for the application.
-         *
          * @param camera  the Camera service object
-         * @see #startSmoothZoom(int)
          */
         void onZoomChange(int zoomValue, boolean stopped, Camera camera);
     };
@@ -679,15 +829,25 @@ public class Camera {
         mZoomListener = listener;
     }
 
-    // These match the enum in include/ui/Camera.h
-    /** Unspecified camerar error.  @see #ErrorCallback */
+    // Error codes match the enum in include/ui/Camera.h
+
+    /**
+     * Unspecified camera error.
+     * @see Camera.ErrorCallback
+     */
     public static final int CAMERA_ERROR_UNKNOWN = 1;
-    /** Media server died. In this case, the application must release the
-     * Camera object and instantiate a new one. @see #ErrorCallback */
+
+    /**
+     * Media server died. In this case, the application must release the
+     * Camera object and instantiate a new one.
+     * @see Camera.ErrorCallback
+     */
     public static final int CAMERA_ERROR_SERVER_DIED = 100;
 
     /**
-     * Handles the camera error callback.
+     * Callback interface for camera error notification.
+     *
+     * @see #setErrorCallback(ErrorCallback)
      */
     public interface ErrorCallback
     {
@@ -705,7 +865,7 @@ public class Camera {
 
     /**
      * Registers a callback to be invoked when an error occurs.
-     * @param cb the callback to run
+     * @param cb The callback to run
      */
     public final void setErrorCallback(ErrorCallback cb)
     {
@@ -716,16 +876,21 @@ public class Camera {
     private native final String native_getParameters();
 
     /**
-     * Sets the Parameters for pictures from this Camera service.
+     * Changes the settings for this Camera service.
      *
      * @param params the Parameters to use for this Camera service
+     * @see #getParameters()
      */
     public void setParameters(Parameters params) {
         native_setParameters(params.flatten());
     }
 
     /**
-     * Returns the picture Parameters for this Camera service.
+     * Returns the current settings for this Camera service.
+     * If modifications are made to the returned Parameters, they must be passed
+     * to {@link #setParameters(Camera.Parameters)} to take effect.
+     *
+     * @see #setParameters(Camera.Parameters)
      */
     public Parameters getParameters() {
         Parameters p = new Parameters();
@@ -735,7 +900,7 @@ public class Camera {
     }
 
     /**
-     * Handles the picture size (dimensions).
+     * Image size (width and height dimensions).
      */
     public class Size {
         /**
@@ -774,18 +939,21 @@ public class Camera {
     };
 
     /**
-     * Handles the parameters for pictures created by a Camera service.
+     * Camera service settings.
      *
      * <p>To make camera parameters take effect, applications have to call
-     * Camera.setParameters. For example, after setWhiteBalance is called, white
-     * balance is not changed until Camera.setParameters() is called.
+     * {@link Camera#setParameters(Camera.Parameters)}. For example, after
+     * {@link Camera.Parameters#setWhiteBalance} is called, white balance is not
+     * actually changed until {@link Camera#setParameters(Camera.Parameters)}
+     * is called with the changed parameters object.
      *
      * <p>Different devices may have different camera capabilities, such as
      * picture size or flash modes. The application should query the camera
      * capabilities before setting parameters. For example, the application
-     * should call getSupportedColorEffects before calling setEffect. If the
-     * camera does not support color effects, getSupportedColorEffects will
-     * return null.
+     * should call {@link Camera.Parameters#getSupportedColorEffects()} before
+     * calling {@link Camera.Parameters#setColorEffect(String)}. If the
+     * camera does not support color effects,
+     * {@link Camera.Parameters#getSupportedColorEffects()} will return null.
      */
     public class Parameters {
         // Parameter keys to communicate with the camera driver.