Clean up and add comments for classes.

22 files changed, 121 insertions, 76 deletions

diff --git a/src/com/android/camera/BitmapManager.java b/src/com/android/camera/BitmapManager.java
index 41c2c92..7846d87 100644
--- a/src/com/android/camera/BitmapManager.java
+++ b/src/com/android/camera/BitmapManager.java
@@ -27,13 +27,16 @@ import java.io.FileDescriptor;
 import java.util.WeakHashMap;
 
 /**
- * This class provides several utilities to cancel bitmap decoding.
+ * Provides utilities to decode bitmap, get thumbnail, and cancel the
+ * operations.
  *
- * The function decodeFileDescriptor() is used to decode a bitmap. During
- * decoding if another thread wants to cancel it, it calls the function
- * cancelThreadDecoding() specifying the Thread which is in decoding.
+ * <p>The function {@link #decodeFileDescriptor(FileDescriptor,
+ * BitmapFactory.Options)} is used to decode a bitmap. During decoding another
+ * thread can cancel it using the function {@link #cancelThreadDecoding(Thread,
+ * ContentResolver)} specifying the {@code Thread} which is in decoding.
  *
- * cancelThreadDecoding() is sticky until allowThreadDecoding() is called.
+ * <p>{@code cancelThreadDecoding(Thread,ContentResolver)} is sticky until
+ * {@code allowThreadDecoding(Thread) } is called.
  */
 public class BitmapManager {
     private static final String TAG = "BitmapManager";
@@ -77,10 +80,10 @@ public class BitmapManager {
         return status;
     }
 
-    /**
-     * The following three methods are used to keep track of
-     * BitmapFaction.Options used for decoding and cancelling.
-     */
+    //
+    // The following two methods are used to keep track of
+    // BitmapFaction.Options used for decoding and cancelling.
+    //
     private synchronized void setDecodingOptions(Thread t,
             BitmapFactory.Options options) {
         getOrCreateThreadStatus(t).mOptions = options;
@@ -91,10 +94,6 @@ public class BitmapManager {
         status.mOptions = null;
     }
 
-    /**
-     * The following three methods are used to keep track of which thread
-     * is being disabled for bitmap decoding.
-     */
     public synchronized boolean canThreadDecoding(Thread t) {
         ThreadStatus status = mThreadStatus.get(t);
         if (status == null) {
@@ -137,6 +136,12 @@ public class BitmapManager {
         }
     }
 
+    /**
+     * Gets the thumbnail of the given ID of the original image.
+     *
+     * <p> This method wraps around @{code getThumbnail} in {@code
+     * android.provider.MediaStore}. It provides the ability to cancel it.
+     */
     public Bitmap getThumbnail(ContentResolver cr, long origId, int kind,
             BitmapFactory.Options options, boolean isVideo) {
         Thread t = Thread.currentThread();
diff --git a/src/com/android/camera/Camera.java b/src/com/android/camera/Camera.java
index c266507..135dc64 100644
--- a/src/com/android/camera/Camera.java
+++ b/src/com/android/camera/Camera.java
@@ -79,9 +79,7 @@ import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 
-/**
- * Activity of the Camera which used to see preview and take pictures.
- */
+/** The Camera activity which can preview and take pictures. */
 public class Camera extends NoSearchActivity implements View.OnClickListener,
         ShutterButton.OnShutterButtonListener, SurfaceHolder.Callback,
         Switcher.OnSwitchListener, OnScreenSettings.OnVisibilityChangedListener,
@@ -830,7 +828,7 @@ public class Camera extends NoSearchActivity implements View.OnClickListener,
         }
     }
 
-    public boolean saveDataToFile(String filePath, byte[] data) {
+    private boolean saveDataToFile(String filePath, byte[] data) {
         FileOutputStream f = null;
         try {
             f = new FileOutputStream(filePath);
@@ -1029,7 +1027,7 @@ public class Camera extends NoSearchActivity implements View.OnClickListener,
         }
 
         // Limit to 50k pixels so we can return it in the intent.
-        Bitmap bitmap = Util.makeBitmap(data, 50*1024);
+        Bitmap bitmap = Util.makeBitmap(data, 50 * 1024);
         bitmap = Util.rotate(bitmap, degree);
         return bitmap;
     }
diff --git a/src/com/android/camera/CameraButtonIntentReceiver.java b/src/com/android/camera/CameraButtonIntentReceiver.java
index be05baf..38f9241 100644
--- a/src/com/android/camera/CameraButtonIntentReceiver.java
+++ b/src/com/android/camera/CameraButtonIntentReceiver.java
@@ -21,9 +21,10 @@ import android.content.Context;
 import android.content.Intent;
 
 /**
- * This class is used when the camera button is long-pressed.
+ * {@code CameraButtonIntentReceiver} is invoked when the camera button is
+ * long-pressed.
  *
- * It is declared in AndroidManifest.xml to receive the
+ * It is declared in {@code AndroidManifest.xml} to receive the
  * {@code android.intent.action.CAMERA_BUTTON} intent.
  *
  * After making sure we can use the camera hardware, it starts the Camera
diff --git a/src/com/android/camera/CameraHolder.java b/src/com/android/camera/CameraHolder.java
index 7fd2b4e..18abd15 100644
--- a/src/com/android/camera/CameraHolder.java
+++ b/src/com/android/camera/CameraHolder.java
@@ -28,17 +28,19 @@ import android.util.Log;
 
 import java.io.IOException;
 
-//
-// CameraHolder is used to hold an android.hardware.Camera instance.
-//
-// The open() and release() calls are similar to the ones in
-// android.hardware.Camera. The difference is if keep() is called before
-// release(), CameraHolder will try to hold the android.hardware.Camera
-// instance for a while, so if open() call called soon after, we can avoid
-// the cost of open() in android.hardware.Camera.
-//
-// This is used in switching between Camera and VideoCamera activities.
-//
+/**
+ * The class is used to hold an {@code android.hardware.Camera} instance.
+ *
+ * <p>The {@code open()} and {@code release()} calls are similar to the ones
+ * in {@code android.hardware.Camera}. The difference is if {@code keep()} is
+ * called before {@code release()}, CameraHolder will try to hold the {@code
+ * android.hardware.Camera} instance for a while, so if {@code open()} is
+ * called soon after, we can avoid the cost of {@code open()} in {@code
+ * android.hardware.Camera}.
+ *
+ * <p>This is used in switching between {@code Camera} and {@code VideoCamera}
+ * activities.
+ */
 public class CameraHolder {
     private static final String TAG = "CameraHolder";
     private android.hardware.Camera mCameraDevice;
diff --git a/src/com/android/camera/CameraSettings.java b/src/com/android/camera/CameraSettings.java
index a5ec590..810f5d4 100644
--- a/src/com/android/camera/CameraSettings.java
+++ b/src/com/android/camera/CameraSettings.java
@@ -33,6 +33,9 @@ import android.util.Log;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ *  Provides utilities and keys for Camera settings.
+ */
 public class CameraSettings {
     private static final int FIRST_REQUEST_CODE = 100;
     private static final int NOT_FOUND = -1;
diff --git a/src/com/android/camera/EvenlySpacedLayout.java b/src/com/android/camera/EvenlySpacedLayout.java
index d994fe4..ec0f495 100644
--- a/src/com/android/camera/EvenlySpacedLayout.java
+++ b/src/com/android/camera/EvenlySpacedLayout.java
@@ -22,10 +22,11 @@ import android.util.AttributeSet;
 import android.view.View;
 import android.view.ViewGroup;
 
-//
-// This is a layout which makes the children even spaced.
-// Currently it does not consider the padding parameters.
-//
+/**
+ * A layout which makes the children evenly spaced (horizontally or vertically).
+ *
+ * <p>Currently it does not consider the padding parameters.
+ */
 public class EvenlySpacedLayout extends ViewGroup {
     private boolean mHorizontal;
 
diff --git a/src/com/android/camera/IconIndicator.java b/src/com/android/camera/IconIndicator.java
index e3e16e2..cfb0a26 100644
--- a/src/com/android/camera/IconIndicator.java
+++ b/src/com/android/camera/IconIndicator.java
@@ -25,8 +25,8 @@ import android.widget.ImageView;
 
 /**
  * This class draws an icon which changes according to the mode. For example,
- * The flash icon can have on, off, and auto mode. The user calls
- * {@code setMode} to change the mode (and the icon).
+ * The flash icon can have on, off, and auto modes. The user can use
+ * {@link #setMode(String)} to change the mode (and the icon).
  */
 public class IconIndicator extends ImageView {
 
diff --git a/src/com/android/camera/IconListPreference.java b/src/com/android/camera/IconListPreference.java
index 314b7a9..9e8109e 100644
--- a/src/com/android/camera/IconListPreference.java
+++ b/src/com/android/camera/IconListPreference.java
@@ -23,6 +23,7 @@ import android.graphics.drawable.Drawable;
 import android.preference.ListPreference;
 import android.util.AttributeSet;
 
+/** A {@code ListPreference} where each entry has a corresponding icon. */
 public class IconListPreference extends ListPreference {
     private Drawable mIcons[];
     private Resources mResources;
diff --git a/src/com/android/camera/ImageManager.java b/src/com/android/camera/ImageManager.java
index 9d06fe9..5486dec 100644
--- a/src/com/android/camera/ImageManager.java
+++ b/src/com/android/camera/ImageManager.java
@@ -51,7 +51,7 @@ import java.util.ArrayList;
 import java.util.Iterator;
 
 /**
- * ImageManager is used to retrieve and store images
+ * {@code ImageManager} is used to retrieve and store images
  * in the media content provider.
  */
 public class ImageManager {
@@ -64,8 +64,10 @@ public class ImageManager {
     private static final Uri VIDEO_STORAGE_URI =
             Uri.parse("content://media/external/video/media");
 
-    // ImageListParam specifies all the parameters we need to create an image
-    // list (we also need a ContentResolver).
+    /**
+     * {@code ImageListParam} specifies all the parameters we need to create an
+     * image list (we also need a ContentResolver).
+     */
     public static class ImageListParam implements Parcelable {
         public DataLocation mLocation;
         public int mInclusion;
diff --git a/src/com/android/camera/MenuHelper.java b/src/com/android/camera/MenuHelper.java
index b877391..6d30a3d 100644
--- a/src/com/android/camera/MenuHelper.java
+++ b/src/com/android/camera/MenuHelper.java
@@ -109,6 +109,7 @@ public class MenuHelper {
         public void run(MenuCallback r);
     }
 
+    /** A callback to be invoked when a menu item is clicked. */
     public interface MenuCallback {
         public void run(Uri uri, IImage image);
     }
diff --git a/src/com/android/camera/NoSearchActivity.java b/src/com/android/camera/NoSearchActivity.java
index 1e1e2d2..6e8657a 100644
--- a/src/com/android/camera/NoSearchActivity.java
+++ b/src/com/android/camera/NoSearchActivity.java
@@ -19,8 +19,10 @@ package com.android.camera;
 import android.app.Activity;
 
 /**
- * This class disables the search key function. To use it, just inherit from
- * {@code NoSearchActivity} instead of {@code Activity}.
+ * An activity which disables the search key function.
+ *
+ * <p> To use it, just inherit from {@code NoSearchActivity} instead of
+ * {@code Activity}.
  */
 public class NoSearchActivity extends Activity {
     @Override
diff --git a/src/com/android/camera/OnScreenHint.java b/src/com/android/camera/OnScreenHint.java
index 9918428..03056fa 100644
--- a/src/com/android/camera/OnScreenHint.java
+++ b/src/com/android/camera/OnScreenHint.java
@@ -35,7 +35,7 @@ import android.widget.TextView;
  * application.
  * <p>
  * The easiest way to use this class is to call one of the static methods that
- * constructs everything you need and returns a new OnScreenHint object.
+ * constructs everything you need and returns a new {@code OnScreenHint} object.
  */
 public class OnScreenHint {
     static final String TAG = "OnScreenHint";
diff --git a/src/com/android/camera/OnScreenSettings.java b/src/com/android/camera/OnScreenSettings.java
index 36be499..1547d03 100644
--- a/src/com/android/camera/OnScreenSettings.java
+++ b/src/com/android/camera/OnScreenSettings.java
@@ -1,3 +1,19 @@
+/*
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.android.camera;
 
 import android.content.Context;
@@ -29,13 +45,20 @@ import android.widget.AdapterView.OnItemClickListener;
 import java.util.ArrayList;
 import java.util.HashMap;
 
-// Please reference to {@link android.widget.ZoomButtonsController} for detail
-// information about adding window to WindowManager.
+/**
+ * The on-screen setting menu.
+ *
+ * <p>Please reference to {@code android.widget.ZoomButtonsController} for
+ * detail information about adding window to WindowManager.
+ */
 public class OnScreenSettings {
     @SuppressWarnings("unused")
     private static final String TAG = "OnScreenSettings";
     private static final int MSG_POST_SET_VISIBLE = 1;
 
+    /**
+     * A callback to be invoked when the on-screen menu's visibility changes.
+     */
     public interface OnVisibilityChangedListener {
         public void onVisibilityChanged(boolean visibility);
     }
@@ -398,7 +421,7 @@ public class OnScreenSettings {
                 if (mIconPreference != null) {
                     icon.setVisibility(View.VISIBLE);
                     icon.setImageDrawable(
-                            mIconPreference.getIcons()[position-1]);
+                            mIconPreference.getIcons()[position - 1]);
                 } else {
                     icon.setVisibility(View.GONE);
                 }
diff --git a/src/com/android/camera/PreviewFrameLayout.java b/src/com/android/camera/PreviewFrameLayout.java
index 7ef9206..b153052 100644
--- a/src/com/android/camera/PreviewFrameLayout.java
+++ b/src/com/android/camera/PreviewFrameLayout.java
@@ -25,9 +25,14 @@ import android.view.ViewGroup;
 import android.widget.ImageView;
 import android.widget.FrameLayout;
 
+/**
+ * A layout which handles the preview aspect ratio and the position of
+ * the gripper.
+ */
 public class PreviewFrameLayout extends ViewGroup {
     private static final int MIN_HORIZONTAL_MARGIN = 10; // 10dp
 
+    /** A callback to be invoked when the preview frame's size changes. */
     public interface OnSizeChangedListener {
         public void onSizeChanged();
     }
diff --git a/src/com/android/camera/ReverseGeocoderTask.java b/src/com/android/camera/ReverseGeocoderTask.java
index 808cf28..f4e7c71 100644
--- a/src/com/android/camera/ReverseGeocoderTask.java
+++ b/src/com/android/camera/ReverseGeocoderTask.java
@@ -25,15 +25,18 @@ import java.io.IOException;
 import java.util.List;
 
 /**
- * This class does reverse geocoding. The input is latitude and longitude,
- * and the output is a descriptive string for the specified location.
+ * A asynchronous task which does reverse geocoding.
  *
- * Because it may take a long time to return, we put it in an AsyncTask. The
- * result is passed to a callback.
+ * <p>Because it may take a long time to return, we put it in an AsyncTask.
+ * The input is latitude and longitude, and the output is a descriptive string
+ * for the specified location. The result is passed to a callback.
  */
 public class ReverseGeocoderTask extends AsyncTask<Void, Void, String> {
     private static final String TAG = "ReverseGeocoder";
 
+    /**
+     * A callback to be invoked when the reverse geocoding task is done.
+     */
     public static interface Callback {
         public void onComplete(String location);
     }
diff --git a/src/com/android/camera/ReviewImage.java b/src/com/android/camera/ReviewImage.java
index ee3ff38..73c3096 100644
--- a/src/com/android/camera/ReviewImage.java
+++ b/src/com/android/camera/ReviewImage.java
@@ -42,11 +42,13 @@ import com.android.camera.gallery.IImage;
 import com.android.camera.gallery.IImageList;
 import com.android.camera.gallery.VideoObject;
 
-// This activity can display a whole picture and navigate them in a specific
-// gallery. It has two modes: normal mode and slide show mode. In normal mode
-// the user view one image at a time, and can click "previous" and "next"
-// button to see the previous or next image. In slide show mode it shows one
-// image after another, with some transition effect.
+/**
+ * An activity displays a full picture and can navigate in a specific image
+ * list.
+ *
+ * <p>The user view one image at a time, and can click "previous" and "next"
+ * button to see the previous or next image.
+ */
 public class ReviewImage extends NoSearchActivity
         implements View.OnClickListener {
     private static final String STATE_URI = "uri";
diff --git a/src/com/android/camera/RotateBitmap.java b/src/com/android/camera/RotateBitmap.java
index 380980b..635ec08 100644
--- a/src/com/android/camera/RotateBitmap.java
+++ b/src/com/android/camera/RotateBitmap.java
@@ -20,16 +20,16 @@ import android.graphics.Bitmap;
 import android.graphics.Matrix;
 
 /**
- * This class represents a bitmap with a rotation. (The rotation can only be
- * 0, 90, 180, 270 degrees)
+ * This class represents a bitmap with a rotation (The rotation can only be
+ * 0, 90, 180, 270 degrees).
  *
  * Because it takes twice the memory to do the rotation (the original bitmap
- * and the new bitmap). We do not actually rotate the bitmap. We pass the
+ * and the new bitmap), we do not actually rotate the bitmap. We pass the
  * rotation along with the bitmap in the program and only apply the rotation
  * when we are actually drawing the bitmap.
  */
 public class RotateBitmap {
-    public static final String TAG = "RotateBitmap";
+    private static final String TAG = "RotateBitmap";
     private Bitmap mBitmap;
     private int mRotation;
 
diff --git a/src/com/android/camera/ShutterButton.java b/src/com/android/camera/ShutterButton.java
index 1fb9258..e1499a6 100644
--- a/src/com/android/camera/ShutterButton.java
+++ b/src/com/android/camera/ShutterButton.java
@@ -22,13 +22,12 @@ import android.widget.ImageView;
 
 /**
  * A button designed to be used for the on-screen shutter button.
- * It's currently an ImageView that can call a delegate when the pressed state
- * changes.
+ * It's currently an {@code ImageView} that can call a delegate when the
+ * pressed state changes.
  */
 public class ShutterButton extends ImageView {
     /**
-     * Interface definition for a callback to be invoked when a ModeButton's
-     * pressed state changes.
+     * A callback to be invoked when a ShutterButton's pressed state changes.
      */
     public interface OnShutterButtonListener {
         /**
diff --git a/src/com/android/camera/Switcher.java b/src/com/android/camera/Switcher.java
index 9c901e3..0813633 100644
--- a/src/com/android/camera/Switcher.java
+++ b/src/com/android/camera/Switcher.java
@@ -26,14 +26,15 @@ import android.view.animation.AnimationUtils;
 import android.widget.ImageView;
 
 /**
- * This is the switcher widget which switchs between the Camera and
- * the VideoCamera activities.
+ * A widget which switchs between the {@code Camera} and the {@code VideoCamera}
+ * activities.
  */
 public class Switcher extends ImageView implements View.OnTouchListener {
 
     @SuppressWarnings("unused")
     private static final String TAG = "Switcher";
 
+    /** A callback to be called when the user wants to switch activity. */
     public interface OnSwitchListener {
         // Returns true if the listener agrees that the switch can be changed.
         public boolean onSwitchChanged(Switcher source, boolean onOff);
@@ -144,7 +145,7 @@ public class Switcher extends ImageView implements View.OnTouchListener {
             final int available = getHeight() - mPaddingTop - mPaddingBottom
                     - drawableHeight;
             long time = AnimationUtils.currentAnimationTimeMillis();
-            int deltaTime = (int)(time - mAnimationStartTime);
+            int deltaTime = (int) (time - mAnimationStartTime);
             mPosition = mAnimationStartPosition +
                     ANIMATION_SPEED * (mSwitch ? deltaTime : -deltaTime) / 1000;
             if (mPosition < 0) mPosition = 0;
diff --git a/src/com/android/camera/ThumbnailController.java b/src/com/android/camera/ThumbnailController.java
index 2ae8e20..858fa22 100644
--- a/src/com/android/camera/ThumbnailController.java
+++ b/src/com/android/camera/ThumbnailController.java
@@ -39,17 +39,10 @@ import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.io.IOException;
 
-/** A controller shows thumbnail picture on a button. The thumbnail picture
+/**
+ * A controller shows thumbnail picture on a button. The thumbnail picture
  * corresponds to a URI of the original picture/video. The thumbnail bitmap
  * and the URI can be saved to a file (and later loaded from it).
- * <pre>
- *    public ThumbnailController(ImageView button)
- *    public void setData(Uri uri, Bitmap original)
- *    public void updateDisplayIfNeeded()
- *    public Uri getUri()
- *    public boolean storeData(String filePath)
- *    public boolean loadData(String filePath)
- * </pre>
  */
 public class ThumbnailController {
 
diff --git a/src/com/android/camera/VideoCamera.java b/src/com/android/camera/VideoCamera.java
index d7a3ca0..9e41a59 100644
--- a/src/com/android/camera/VideoCamera.java
+++ b/src/com/android/camera/VideoCamera.java
@@ -223,7 +223,6 @@ public class VideoCamera extends NoSearchActivity
                 ress.getString(R.string.cannot_connect_camera));
     }
 
-    /** Called with the activity is first created. */
     @Override
     public void onCreate(Bundle icicle) {
         super.onCreate(icicle);
diff --git a/src/com/android/camera/gallery/LruCache.java b/src/com/android/camera/gallery/LruCache.java
index 2e15ee5..d4ff417 100644
--- a/src/com/android/camera/gallery/LruCache.java
+++ b/src/com/android/camera/gallery/LruCache.java
@@ -22,6 +22,10 @@ import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+/**
+ * An LRU cache which stores recently inserted entries and all entries ever
+ * inserted which still has a strong reference elsewhere.
+ */
 public class LruCache<K, V> {
 
     private final HashMap<K, V> mLruMap;