Clean up and add comments for classes.

15 files changed, 92 insertions, 21 deletions

diff --git a/src/com/android/camera/BitmapManager.java b/src/com/android/camera/BitmapManager.java
index 3ae6b93..41c2c92 100644
--- a/src/com/android/camera/BitmapManager.java
+++ b/src/com/android/camera/BitmapManager.java
@@ -110,7 +110,8 @@ public class BitmapManager {
         getOrCreateThreadStatus(t).mState = State.ALLOW;
     }
 
-    public synchronized void cancelThreadDecoding(Thread t, ContentResolver cr) {
+    public synchronized void cancelThreadDecoding(Thread t,
+            ContentResolver cr) {
         ThreadStatus status = getOrCreateThreadStatus(t);
         status.mState = State.CANCEL;
         if (status.mOptions != null) {
@@ -120,8 +121,9 @@ public class BitmapManager {
         // Wake up threads in waiting list
         notifyAll();
 
-        // Since our cancel request can arrive MediaProvider earlier than getThumbnail request,
-        // we use mThumbRequesting flag to make sure our request does cancel the request.
+        // Since our cancel request can arrive MediaProvider earlier than
+        // getThumbnail request, we use mThumbRequesting flag to make sure our
+        // request does cancel the request.
         try {
             synchronized (status) {
                 while (status.mThumbRequesting) {
diff --git a/src/com/android/camera/Camera.java b/src/com/android/camera/Camera.java
index 835bb89..c266507 100644
--- a/src/com/android/camera/Camera.java
+++ b/src/com/android/camera/Camera.java
@@ -1674,9 +1674,9 @@ public class Camera extends NoSearchActivity implements View.OnClickListener,
                 mParameters.setSceneMode(sceneMode);
                 mCameraDevice.setParameters(mParameters);
 
-                // Setting scene mode will change the settings of flash mode, white
-                // balance, and focus mode. So read back here, so that we know
-                // what're the settings
+                // Setting scene mode will change the settings of flash mode,
+                // white balance, and focus mode. Here we read back the
+                // parameters, so we can know those settings.
                 mParameters = mCameraDevice.getParameters();
             }
         } else {
diff --git a/src/com/android/camera/CameraButtonIntentReceiver.java b/src/com/android/camera/CameraButtonIntentReceiver.java
index 4153104..be05baf 100644
--- a/src/com/android/camera/CameraButtonIntentReceiver.java
+++ b/src/com/android/camera/CameraButtonIntentReceiver.java
@@ -20,6 +20,15 @@ import android.content.BroadcastReceiver;
 import android.content.Context;
 import android.content.Intent;
 
+/**
+ * This class is used when the camera button is long-pressed.
+ *
+ * It is declared in 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
+ * activity.
+ */
 public class CameraButtonIntentReceiver extends BroadcastReceiver {
 
     @Override
diff --git a/src/com/android/camera/CameraHardwareException.java b/src/com/android/camera/CameraHardwareException.java
index a975cbd..d1e4387 100644
--- a/src/com/android/camera/CameraHardwareException.java
+++ b/src/com/android/camera/CameraHardwareException.java
@@ -16,8 +16,11 @@
 
 package com.android.camera;
 
+/**
+ * This class represents the condition that we cannot open the camera hardware
+ * successfully. For example, another process is using the camera.
+ */
 public class CameraHardwareException extends Exception {
-    private static final long serialVersionUID = -4453804913829319918L;
 
     public CameraHardwareException() {
     }
diff --git a/src/com/android/camera/CameraSettings.java b/src/com/android/camera/CameraSettings.java
index e7d7d0e..a5ec590 100644
--- a/src/com/android/camera/CameraSettings.java
+++ b/src/com/android/camera/CameraSettings.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.app.Activity;
diff --git a/src/com/android/camera/IconIndicator.java b/src/com/android/camera/IconIndicator.java
index c3f0392..e3e16e2 100644
--- a/src/com/android/camera/IconIndicator.java
+++ b/src/com/android/camera/IconIndicator.java
@@ -23,6 +23,11 @@ import android.graphics.drawable.Drawable;
 import android.util.AttributeSet;
 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).
+ */
 public class IconIndicator extends ImageView {
 
     private Drawable[] mIcons;
diff --git a/src/com/android/camera/ImageManager.java b/src/com/android/camera/ImageManager.java
index 304a35b..9d06fe9 100644
--- a/src/com/android/camera/ImageManager.java
+++ b/src/com/android/camera/ImageManager.java
@@ -231,8 +231,8 @@ public class ImageManager {
     public static Uri addImage(ContentResolver cr, String title, long dateTaken,
             Location location, String directory, String filename,
             Bitmap source, byte[] jpegData, int[] degree) {
-        // We should store image data earlier than insert it to ContentProvider, otherwise
-        // we may not be able to generate thumbnail in time.
+        // We should store image data earlier than insert it to ContentProvider,
+        // otherwise we may not be able to generate thumbnail in time.
         OutputStream outputStream = null;
         String filePath = directory + "/" + filename;
         try {
diff --git a/src/com/android/camera/MenuHelper.java b/src/com/android/camera/MenuHelper.java
index 0d949b2..b877391 100644
--- a/src/com/android/camera/MenuHelper.java
+++ b/src/com/android/camera/MenuHelper.java
@@ -342,11 +342,13 @@ public class MenuHelper {
     }
 
     /**
-     * Returns a human-readable string describing the white balance value. Returns empty
-     * string if there is no white balance value or it is not recognized.
+     * Returns a human-readable string describing the white balance value.
+     * Returns empty string if there is no white balance value or it is not
+     * recognized.
      */
     private static String getWhiteBalanceString(ExifInterface exif) {
-        int whitebalance = exif.getAttributeInt(ExifInterface.TAG_WHITE_BALANCE, -1);
+        int whitebalance = exif.getAttributeInt(
+                ExifInterface.TAG_WHITE_BALANCE, -1);
         if (whitebalance == -1) return "";
 
         switch (whitebalance) {
diff --git a/src/com/android/camera/MonitoredActivity.java b/src/com/android/camera/MonitoredActivity.java
index 68708e4..74097ae 100644
--- a/src/com/android/camera/MonitoredActivity.java
+++ b/src/com/android/camera/MonitoredActivity.java
@@ -20,7 +20,16 @@ import android.os.Bundle;
 
 import java.util.ArrayList;
 
-public class MonitoredActivity extends NoSearchActivity {
+/**
+ * This class monitors the life cycle events for an activity.
+ *
+ * To use it, make the activity inherit from MonitoredActivity. You also need
+ * to register a LifeCycleListener using addLifeCycleListener().
+ *
+ * There is a convenience class LifeCycleAdapter which lets you implement only
+ * methods for the events you are interested.
+ */
+class MonitoredActivity extends NoSearchActivity {
 
     private final ArrayList<LifeCycleListener> mListeners =
             new ArrayList<LifeCycleListener>();
diff --git a/src/com/android/camera/NoSearchActivity.java b/src/com/android/camera/NoSearchActivity.java
index f859ce9..1e1e2d2 100644
--- a/src/com/android/camera/NoSearchActivity.java
+++ b/src/com/android/camera/NoSearchActivity.java
@@ -18,6 +18,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}.
+ */
 public class NoSearchActivity extends Activity {
     @Override
     public boolean onSearchRequested() {
diff --git a/src/com/android/camera/ReverseGeocoderTask.java b/src/com/android/camera/ReverseGeocoderTask.java
index 97f5978..808cf28 100644
--- a/src/com/android/camera/ReverseGeocoderTask.java
+++ b/src/com/android/camera/ReverseGeocoderTask.java
@@ -24,7 +24,13 @@ import android.util.Log;
 import java.io.IOException;
 import java.util.List;
 
-// Reverse geocoding may take a long time to return so we put it in AsyncTask.
+/**
+ * This class does reverse geocoding. The input is latitude and longitude,
+ * and the output is a descriptive string for the specified location.
+ *
+ * Because it may take a long time to return, we put it in an AsyncTask. The
+ * result is passed to a callback.
+ */
 public class ReverseGeocoderTask extends AsyncTask<Void, Void, String> {
     private static final String TAG = "ReverseGeocoder";
 
@@ -49,8 +55,7 @@ public class ReverseGeocoderTask extends AsyncTask<Void, Void, String> {
     protected String doInBackground(Void... params) {
         String value = MenuHelper.EMPTY_STRING;
         try {
-            List<Address> address =
-                    mGeocoder.getFromLocation(mLat, mLng, 1);
+            List<Address> address = mGeocoder.getFromLocation(mLat, mLng, 1);
             StringBuilder sb = new StringBuilder();
             for (Address addr : address) {
                 int index = addr.getMaxAddressLineIndex();
@@ -72,4 +77,3 @@ public class ReverseGeocoderTask extends AsyncTask<Void, Void, String> {
         mCallback.onComplete(location);
     }
 }
-
diff --git a/src/com/android/camera/ReviewImage.java b/src/com/android/camera/ReviewImage.java
index 473ecb4..ee3ff38 100644
--- a/src/com/android/camera/ReviewImage.java
+++ b/src/com/android/camera/ReviewImage.java
@@ -47,7 +47,8 @@ import com.android.camera.gallery.VideoObject;
 // 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.
-public class ReviewImage extends NoSearchActivity implements View.OnClickListener {
+public class ReviewImage extends NoSearchActivity
+        implements View.OnClickListener {
     private static final String STATE_URI = "uri";
     private static final String TAG = "ReviewImage";
     private static final double ASPECT_RATIO = 4.0 / 3.0;
@@ -372,7 +373,8 @@ public class ReviewImage extends NoSearchActivity implements View.OnClickListene
         Uri uri = mAllImages.getImageAt(mCurrentPosition).fullSizeImageUri();
         MenuHelper.enableShareMenuItem(menu, MenuHelper.isWhiteListUri(uri));
 
-        MenuHelper.enableShowOnMapMenuItem(menu, MenuHelper.hasLatLngData(image));
+        MenuHelper.enableShowOnMapMenuItem(menu,
+                MenuHelper.hasLatLngData(image));
 
         return true;
     }
diff --git a/src/com/android/camera/RotateBitmap.java b/src/com/android/camera/RotateBitmap.java
index 67ca3c3..380980b 100644
--- a/src/com/android/camera/RotateBitmap.java
+++ b/src/com/android/camera/RotateBitmap.java
@@ -19,6 +19,15 @@ package com.android.camera;
 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)
+ *
+ * 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
+ * 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 Bitmap mBitmap;
diff --git a/src/com/android/camera/Switcher.java b/src/com/android/camera/Switcher.java
index cb0d4f1..9c901e3 100644
--- a/src/com/android/camera/Switcher.java
+++ b/src/com/android/camera/Switcher.java
@@ -25,6 +25,10 @@ import android.view.View;
 import android.view.animation.AnimationUtils;
 import android.widget.ImageView;
 
+/**
+ * This is the switcher widget which switchs between the Camera and
+ * the VideoCamera activities.
+ */
 public class Switcher extends ImageView implements View.OnTouchListener {
 
     @SuppressWarnings("unused")
diff --git a/src/com/android/camera/VideoCamera.java b/src/com/android/camera/VideoCamera.java
index 713c76a..d7a3ca0 100644
--- a/src/com/android/camera/VideoCamera.java
+++ b/src/com/android/camera/VideoCamera.java
@@ -79,7 +79,8 @@ import java.util.HashMap;
 /**
  * The Camcorder activity.
  */
-public class VideoCamera extends NoSearchActivity implements View.OnClickListener,
+public class VideoCamera extends NoSearchActivity
+        implements View.OnClickListener,
         ShutterButton.OnShutterButtonListener, SurfaceHolder.Callback,
         MediaRecorder.OnErrorListener, MediaRecorder.OnInfoListener,
         Switcher.OnSwitchListener, OnSharedPreferenceChangeListener,
@@ -1266,7 +1267,8 @@ public class VideoCamera extends NoSearchActivity implements View.OnClickListene
     }
 
     private void acquireVideoThumb() {
-        Bitmap videoFrame = ThumbnailUtil.createVideoThumbnail(mCurrentVideoFilename);
+        Bitmap videoFrame = ThumbnailUtil.createVideoThumbnail(
+                mCurrentVideoFilename);
         mThumbController.setData(mCurrentVideoUri, videoFrame);
     }