Comments!

src/com/timsu/astrid/activities/EditPreferences.java

@@ -1,3 +1,22 @@
+/*
+ * ASTRID: Android's Simple Task Recording Dashboard
+ *
+ * Copyright (c) 2009 Tim Su
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
 package com.timsu.astrid.activities;
 
 import android.os.Bundle;
@@ -5,6 +24,12 @@ import android.preference.PreferenceActivity;
 
 import com.timsu.astrid.R;
 
+/**
+ * Displays the preference screen for users to edit their preferences
+ *
+ * @author timsu
+ *
+ */
 public class EditPreferences extends PreferenceActivity {
     @Override
     public void onCreate(Bundle savedInstanceState) {

src/com/timsu/astrid/activities/SubActivity.java

@@ -0,0 +1,138 @@
+/*
+ * ASTRID: Android's Simple Task Recording Dashboard
+ *
+ * Copyright (c) 2009 Tim Su
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+package com.timsu.astrid.activities;
+
+import android.app.Activity;
+import android.content.Intent;
+import android.content.res.Resources;
+import android.database.Cursor;
+import android.os.Bundle;
+import android.view.KeyEvent;
+import android.view.Menu;
+import android.view.MenuItem;
+import android.view.View;
+
+import com.timsu.astrid.activities.TaskList.ActivityCode;
+import com.timsu.astrid.data.tag.TagController;
+import com.timsu.astrid.data.task.TaskController;
+
+/**
+ * Interface for views that are displayed from the main view page.
+ *
+ * @author timsu
+ */
+abstract public class SubActivity {
+	private TaskList parent;
+	ActivityCode code;
+	private View view;
+
+	public SubActivity(TaskList parent, ActivityCode code, View view) {
+		this.parent = parent;
+		this.code = code;
+		this.view = view;
+		view.setTag(this);
+	}
+
+	// --- pass-through to activity listeners
+
+	/** Called when this subactivity is displayed to the user */
+	void onDisplay(Bundle variables) {
+		//
+	}
+
+	boolean onPrepareOptionsMenu(Menu menu) {
+		return false;
+	}
+
+	void onActivityResult(int requestCode, int resultCode, Intent data) {
+		//
+	}
+
+	boolean onMenuItemSelected(int featureId, MenuItem item) {
+		return false;
+	}
+
+
+	void onWindowFocusChanged(boolean hasFocus) {
+		//
+	}
+
+	boolean onKeyDown(int keyCode, KeyEvent event) {
+		return false;
+	}
+
+	// --- pass-through to activity methods
+
+	public Resources getResources() {
+		return parent.getResources();
+	}
+
+	public View findViewById(int id) {
+		return view.findViewById(id);
+	}
+
+	public void startManagingCursor(Cursor c) {
+		parent.startManagingCursor(c);
+	}
+
+	public void setTitle(CharSequence title) {
+		parent.setTitle(title);
+	}
+
+	public void closeActivity() {
+		parent.finish();
+	}
+
+	public void launchActivity(Intent intent, int requestCode) {
+		parent.startActivityForResult(intent, requestCode);
+	}
+
+	// --- helper methods
+
+	public Activity getParent() {
+		return parent;
+	}
+
+	public TaskController getTaskController() {
+		return parent.taskController;
+	}
+
+	public TagController getTagController() {
+		return parent.tagController;
+	}
+
+	public View.OnTouchListener getGestureListener() {
+		return parent.gestureListener;
+	}
+
+	public void switchToActivity(ActivityCode activity, Bundle state) {
+		parent.switchToActivity(activity, state);
+	}
+
+	// --- internal methods
+
+	protected ActivityCode getActivityCode() {
+		return code;
+	}
+
+	protected View getView() {
+		return view;
+	}
+}

src/com/timsu/astrid/activities/SyncPreferences.java

@@ -1,3 +1,22 @@
+/*
+ * ASTRID: Android's Simple Task Recording Dashboard
+ *
+ * Copyright (c) 2009 Tim Su
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
 package com.timsu.astrid.activities;
 
 import android.app.Dialog;
@@ -12,6 +31,13 @@ import com.timsu.astrid.sync.Synchronizer;
 import com.timsu.astrid.utilities.Constants;
 import com.timsu.astrid.utilities.DialogUtilities;
 
+/**
+ * Displays synchronization preferences and an action panel so users can
+ * initiate actions from the menu.
+ *
+ * @author timsu
+ *
+ */
 public class SyncPreferences extends PreferenceActivity {
 
     @Override

src/com/timsu/astrid/activities/TagListSubActivity.java

@@ -49,7 +49,6 @@ import android.widget.AdapterView.OnItemClickListener;
 
 import com.timsu.astrid.R;
 import com.timsu.astrid.activities.TaskList.ActivityCode;
-import com.timsu.astrid.activities.TaskList.SubActivity;
 import com.timsu.astrid.data.tag.TagIdentifier;
 import com.timsu.astrid.data.tag.TagModelForView;
 import com.timsu.astrid.data.task.TaskIdentifier;

src/com/timsu/astrid/activities/TaskEdit.java

@@ -77,6 +77,14 @@ import com.timsu.astrid.widget.TimeDurationControlSet;
 import com.timsu.astrid.widget.NumberPickerDialog.OnNumberPickedListener;
 import com.timsu.astrid.widget.TimeDurationControlSet.TimeDurationType;
 
+/**
+ * This activity is responsible for creating new tasks and editing existing
+ * ones. It saves a task when it is paused (screen rotated, back button
+ * pressed) as long as the task has a title.
+ *
+ * @author timsu
+ *
+ */
 public class TaskEdit extends TaskModificationTabbedActivity<TaskModelForEdit> {
 
     // bundle arguments
@@ -164,6 +172,7 @@ public class TaskEdit extends TaskModificationTabbedActivity<TaskModelForEdit> {
      * =============================================== model reading / saving
      * ====================================================================== */
 
+    /** Populate UI component values from the model */
     private void populateFields() {
         Resources r = getResources();
 
@@ -240,6 +249,7 @@ public class TaskEdit extends TaskModificationTabbedActivity<TaskModelForEdit> {
             setRepeatValue(0);
     }
 
+    /** Save task model from values in UI components */
     private void save() {
         // don't save if user accidentally created a new task
         if(name.getText().length() == 0)
@@ -249,7 +259,7 @@ public class TaskEdit extends TaskModificationTabbedActivity<TaskModelForEdit> {
         if((definiteDueDate.getDate() == null && model.getDefiniteDueDate() != null) ||
         		(preferredDueDate.getDate() == null && model.getPreferredDueDate() != null))
         	Notifications.deleteAlarm(this, model.getTaskIdentifier().getId());
-        
+
         model.setName(name.getText().toString());
         model.setEstimatedSeconds(estimatedDuration.getTimeDurationInSeconds());
         model.setElapsedSeconds(elapsedDuration.getTimeDurationInSeconds());
@@ -313,6 +323,7 @@ public class TaskEdit extends TaskModificationTabbedActivity<TaskModelForEdit> {
             tagController.addTag(model.getTaskIdentifier(), tagId);
     }
 
+    /** Helper method to save alerts for this task */
     private void saveAlerts() {
         alertController.removeAlerts(model.getTaskIdentifier());
 

src/com/timsu/astrid/activities/TaskList.java

@@ -1,11 +1,28 @@
+/*
+ * ASTRID: Android's Simple Task Recording Dashboard
+ *
+ * Copyright (c) 2009 Tim Su
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
 package com.timsu.astrid.activities;
 
 import java.util.Date;
 
 import android.app.Activity;
 import android.content.Intent;
-import android.content.res.Resources;
-import android.database.Cursor;
 import android.os.Bundle;
 import android.util.Log;
 import android.view.GestureDetector;
@@ -28,138 +45,40 @@ import com.timsu.astrid.utilities.Preferences;
 import com.timsu.astrid.utilities.StartupReceiver;
 
 /**
- * Main activity uses a ViewFlipper to flip between child views.
+ * TaskList is the main launched activity for Astrid. It uses a ViewFlipper
+ * to flip between child views, which in this case are the TaskListSubActivity
+ * and the TagListSubActivity.
  *
  * @author Tim Su (timsu@stanfordalumni.org)
  */
 public class TaskList extends Activity {
 
-    /**
+    /** Enum for the different pages that we can display */
-     * Interface for views that are displayed from the main view page
-     *
-     * @author timsu
-     */
-    abstract public static class SubActivity {
-    	private TaskList parent;
-    	private ActivityCode code;
-    	private View view;
-
-    	public SubActivity(TaskList parent, ActivityCode code, View view) {
-			this.parent = parent;
-			this.code = code;
-			this.view = view;
-			view.setTag(this);
-		}
-
-    	// --- pass-through to activity listeners
-
-    	/** Called when this subactivity is displayed to the user */
-    	void onDisplay(Bundle variables) {
-    		//
-    	}
-
-    	boolean onPrepareOptionsMenu(Menu menu) {
-    		return false;
-    	}
-
-    	void onActivityResult(int requestCode, int resultCode, Intent data) {
-    		//
-    	}
-
-    	boolean onMenuItemSelected(int featureId, MenuItem item) {
-    		return false;
-    	}
-
-
-    	void onWindowFocusChanged(boolean hasFocus) {
-    		//
-    	}
-
-    	boolean onKeyDown(int keyCode, KeyEvent event) {
-    		return false;
-    	}
-
-    	// --- pass-through to activity methods
-
-    	public Resources getResources() {
-    		return parent.getResources();
-    	}
-
-    	public View findViewById(int id) {
-    		return view.findViewById(id);
-    	}
-
-    	public void startManagingCursor(Cursor c) {
-    		parent.startManagingCursor(c);
-    	}
-
-    	public void setTitle(CharSequence title) {
-    		parent.setTitle(title);
-    	}
-
-    	public void closeActivity() {
-    		parent.finish();
-    	}
-
-    	public void launchActivity(Intent intent, int requestCode) {
-    		parent.startActivityForResult(intent, requestCode);
-    	}
-
-    	// --- helper methods
-
-    	public Activity getParent() {
-    		return parent;
-    	}
-
-    	public TaskController getTaskController() {
-    		return parent.taskController;
-    	}
-
-    	public TagController getTagController() {
-    		return parent.tagController;
-    	}
-
-    	public View.OnTouchListener getGestureListener() {
-    		return parent.gestureListener;
-    	}
-
-    	public void switchToActivity(ActivityCode activity, Bundle state) {
-    		parent.switchToActivity(activity, state);
-    	}
-
-    	// --- internal methods
-
-    	protected ActivityCode getActivityCode() {
-    		return code;
-    	}
-
-    	protected View getView() {
-			return view;
-		}
-    }
-
-    /* ======================================================================
-     * ======================================================= internal stuff
-     * ====================================================================== */
-
-
     public enum ActivityCode {
     	TASK_LIST,
     	TAG_LIST,
     	TASK_LIST_W_TAG
     };
 
+    /** Bundle Key: activity code id of current activity */
     private static final String LAST_ACTIVITY_TAG = "l";
+
+    /** Bundle Key: variables of current activity */
     private static final String LAST_BUNDLE_TAG = "b";
+
+    /** Bundle Key: variables to pass to the subactivity */
     public  static final String VARIABLES_TAG = "v";
 
+    /** Minimum distance a fling must cover to trigger motion */
     private static final int FLING_DIST_THRESHOLD = 100;
+
+    /** Minimum velocity a fling must have to trigger motion */
 	private static final int FLING_VEL_THRESHOLD = 300;
 
 	// view components
 	private ViewFlipper viewFlipper;
 	private GestureDetector gestureDetector;
-	private View.OnTouchListener gestureListener;
+	View.OnTouchListener gestureListener;
 	private SubActivity taskList;
 	private SubActivity tagList;
 	private SubActivity taskListWTag;
@@ -172,10 +91,12 @@ public class TaskList extends Activity {
     private Animation mOutAnimationBackward;
 
 	// data controllers
-	private TaskController taskController;
+	TaskController taskController;
-	private TagController tagController;
+	TagController tagController;
 
 	// static variables
+
+	/** If set, the application will close when this activity gets focus */
 	static boolean shouldCloseInstance = false;
 
     @Override
@@ -245,6 +166,7 @@ public class TaskList extends Activity {
         };
     }
 
+    /** Gesture detector switches between subactivities */
     private class AstridGestureDetector extends SimpleOnGestureListener {
         @Override
         public boolean onFling(MotionEvent e1, MotionEvent e2, float velocityX, float velocityY) {
@@ -292,7 +214,8 @@ public class TaskList extends Activity {
      * ==================================================== subactivity stuff
      * ====================================================================== */
 
-    private void switchToActivity(ActivityCode activity, Bundle variables) {
+    /** Switches to another activity, with appropriate animation */
+    void switchToActivity(ActivityCode activity, Bundle variables) {
     	closeOptionsMenu();
 
     	// and flip to them
@@ -352,6 +275,7 @@ public class TaskList extends Activity {
     	lastActivityBundle = variables;
     }
 
+    /** Helper method gets the currently visible subactivity */
     private SubActivity getCurrentSubActivity() {
     	return (SubActivity)viewFlipper.getCurrentView().getTag();
     }

src/com/timsu/astrid/activities/TaskListAdapter.java

@@ -190,6 +190,7 @@ public class TaskListAdapter extends ArrayAdapter<TaskModelForList> {
     // ----------------------------------------------------------------------
 
     @Override
+    /** Creates or reuses the view for a row in the list */
     public View getView(int position, View convertView, ViewGroup parent) {
         View view = convertView;
 
@@ -205,7 +206,7 @@ public class TaskListAdapter extends ArrayAdapter<TaskModelForList> {
     }
 
     /**
-     * Perform initial setup on the row, stuff is constant for every row
+     * Perform initial setup on the row. Called once for the whole list
      *
      * @param view
      */
@@ -216,7 +217,7 @@ public class TaskListAdapter extends ArrayAdapter<TaskModelForList> {
     }
 
     /**
-     * Setup the given view for the specified task
+     * Setup the given view for the specified task. Called every row
      *
      * @param view
      * @param task
@@ -632,6 +633,12 @@ public class TaskListAdapter extends ArrayAdapter<TaskModelForList> {
         });
     }
 
+    /** Helper method to set a task's progress and then adjust its appearance
+     *
+     * @param task
+     * @param view
+     * @param progress
+     */
     private void setTaskProgress(final TaskModelForList task, View view, int progress) {
         final ImageView timer = ((ImageView)view.findViewById(R.id.imageLeft));
         task.setProgressPercentage(progress);
@@ -663,6 +670,13 @@ public class TaskListAdapter extends ArrayAdapter<TaskModelForList> {
         }
     }
 
+    /** Helper method to adjust a tasks' apperance if the task is completed or
+     * uncompleted.
+     *
+     * @param task
+     * @param name
+     * @param progress
+     */
     private void setTaskAppearance(TaskModelForList task, TextView name, CheckBox progress) {
         Resources r = activity.getResources();
 

src/com/timsu/astrid/activities/TaskListNotify.java

@@ -1,26 +1,52 @@
+/*
+ * ASTRID: Android's Simple Task Recording Dashboard
+ *
+ * Copyright (c) 2009 Tim Su
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
 package com.timsu.astrid.activities;
 
 import android.app.Activity;
 import android.content.Intent;
 import android.os.Bundle;
 
+/**
+ * This activity is launched when a user opens up a notification from the
+ * tray. It launches the appropriate activity based on the passed in parametes.
+ *
+ * @author timsu
+ *
+ */
 public class TaskListNotify extends Activity {
 
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
 
-        Intent intent = new Intent(this, TaskList.class);
+        launchTaskList(getIntent());
-        intent.putExtra(TaskList.VARIABLES_TAG, getIntent().getExtras());
-        startActivity(intent);
-
-        finish();
     }
 
     @Override
     protected void onNewIntent(Intent intent) {
         super.onNewIntent(intent);
 
+        launchTaskList(intent);
+    }
+
+    private void launchTaskList(Intent intent) {
         Intent taskListIntent = new Intent(this, TaskList.class);
         taskListIntent.putExtra(TaskList.VARIABLES_TAG, intent.getExtras());
         startActivity(taskListIntent);

src/com/timsu/astrid/activities/TaskListSubActivity.java

@@ -49,7 +49,6 @@ import android.widget.ListView;
 
 import com.timsu.astrid.R;
 import com.timsu.astrid.activities.TaskList.ActivityCode;
-import com.timsu.astrid.activities.TaskList.SubActivity;
 import com.timsu.astrid.activities.TaskListAdapter.TaskListAdapterHooks;
 import com.timsu.astrid.data.tag.TagController;
 import com.timsu.astrid.data.tag.TagIdentifier;
@@ -68,7 +67,7 @@ import com.timsu.astrid.widget.NNumberPickerDialog.OnNNumberPickedListener;
 
 /**
  * Primary view for the Astrid Application. Lists all of the tasks in the
- * system, and allows users to edit them.
+ * system, and allows users to interact with them.
  *
  * @author Tim Su (timsu@stanfordalumni.org)
  *