完成开源软件质量分析出版

# Conflicts:
#	src/notes/ui/NotesPreferenceActivity.java

src/notes/MainActivity.java

@@ -0,0 +1,25 @@
+package net.micode.notes;
+
+import android.os.Bundle;
+
+import androidx.activity.EdgeToEdge;
+import androidx.appcompat.app.AppCompatActivity;
+import androidx.core.graphics.Insets;
+import androidx.core.view.ViewCompat;
+import androidx.core.view.WindowInsetsCompat;
+
+public class MainActivity extends AppCompatActivity {
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        EdgeToEdge.enable(this);
+        setContentView(R.layout.activity_main);
+        ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main), (v, insets) -> {
+            Insets systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars());
+            v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom);
+            return insets;
+        });
+    }
+}
+

src/notes/data/Contact.java

@@ -25,10 +25,17 @@ import android.util.Log;
 
 import java.util.HashMap;
 
+/**
+ * 联系人信息获取类，通过联系人电话获取姓名
+ **/
+
 public class Contact {
+    // 用于存储已查询过的电话号码和对应的联系人姓名
     private static HashMap<String, String> sContactCache;
+    // 用于标识日志输出来源
     private static final String TAG = "Contact";
 
+    // 查询条件字符串，用于通过电话号码从数据库中查询联系人信息
     private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER
     + ",?) AND " + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'"
     + " AND " + Data.RAW_CONTACT_ID + " IN "
@@ -36,38 +43,52 @@ public class Contact {
             + " FROM phone_lookup"
             + " WHERE min_match = '+')";
 
+    /**
+     * 根据电话号码获取联系人姓名
+     * @param context 应用上下文
+     * @param phoneNumber 电话号码
+     * @return 联系人姓名，如果未找到则返回null
+     */
     public static String getContact(Context context, String phoneNumber) {
-        if(sContactCache == null) {
+        if( sContactCache == null) {
             sContactCache = new HashMap<String, String>();
         }
 
+        // 先从缓存中查找，如果存在则直接返回，避免重复查询数据库
         if(sContactCache.containsKey(phoneNumber)) {
             return sContactCache.get(phoneNumber);
         }
-
+        // 如果缓存中不存在，则执行数据库查询
         String selection = CALLER_ID_SELECTION.replace("+",
                 PhoneNumberUtils.toCallerIDMinMatch(phoneNumber));
+        // 执行查询操作，返回一个游标对象
         Cursor cursor = context.getContentResolver().query(
-                Data.CONTENT_URI,
+                Data.CONTENT_URI,                     // 查询的URI
-                new String [] { Phone.DISPLAY_NAME },
+                new String [] { Phone.DISPLAY_NAME }, // 返回的列名：联系人显示名称
-                selection,
+                selection,                            // 查询条件
-                new String[] { phoneNumber },
+                new String[] { phoneNumber },         // 查询参数
-                null);
+                null);                                // 排序方式
 
+        // 处理查询结果
         if (cursor != null && cursor.moveToFirst()) {
             try {
+                // 获取查询结果中的联系人姓名
                 String name = cursor.getString(0);
+                // 将结果存入缓存，供下次查询使用
                 sContactCache.put(phoneNumber, name);
                 return name;
             } catch (IndexOutOfBoundsException e) {
+                // 处理索引越界异常，记录错误日志
                 Log.e(TAG, " Cursor get string error " + e.toString());
                 return null;
             } finally {
+                // 确保游标被正确关闭，释放资源
                 cursor.close();
             }
         } else {
+            // 未查询到匹配的联系人，记录调试日志
             Log.d(TAG, "No contact matched with number:" + phoneNumber);
             return null;
         }
     }
-}
+}

src/notes/data/Notes.java

@@ -17,50 +17,142 @@
 package net.micode.notes.data;
 
 import android.net.Uri;
+
+/**
+ * 小米便签数据层核心定义类，包含所有常量、URI、数据库列定义和内部类
+ * 该类是整个应用数据层的基础，被其他模块广泛引用
+ */
 public class Notes {
+    /**
+     * ContentProvider的权限名称，用于构建URI
+     */
     public static final String AUTHORITY = "micode_notes";
+    
+    /**
+     * 日志标签，用于标识该类的日志输出
+     */
     public static final String TAG = "Notes";
+    
+    /**
+     * 笔记类型：普通笔记
+     */
     public static final int TYPE_NOTE     = 0;
+    
+    /**
+     * 笔记类型：文件夹
+     */
     public static final int TYPE_FOLDER   = 1;
+    
+    /**
+     * 笔记类型：系统文件夹（如根目录、临时文件夹等）
+     */
     public static final int TYPE_SYSTEM   = 2;
 
     /**
-     * Following IDs are system folders' identifiers
+     * 系统文件夹ID定义
-     * {@link Notes#ID_ROOT_FOLDER } is default folder
+     */
-     * {@link Notes#ID_TEMPARAY_FOLDER } is for notes belonging no folder
+    
-     * {@link Notes#ID_CALL_RECORD_FOLDER} is to store call records
+    /**
+     * 根文件夹ID，默认文件夹
      */
     public static final int ID_ROOT_FOLDER = 0;
+    
+    /**
+     * 临时文件夹ID，用于存放无归属的笔记
+     */
     public static final int ID_TEMPARAY_FOLDER = -1;
+    
+    /**
+     * 通话记录文件夹ID，用于存储通话记录笔记
+     */
     public static final int ID_CALL_RECORD_FOLDER = -2;
+    
+    /**
+     * 回收站文件夹ID，用于存放已删除的笔记
+     */
     public static final int ID_TRASH_FOLER = -3;
 
+    /**
+     * Intent额外参数定义，用于组件间传递数据
+     */
+    
+    /**
+     * 提醒日期参数
+     */
     public static final String INTENT_EXTRA_ALERT_DATE = "net.micode.notes.alert_date";
+    
+    /**
+     * 背景颜色ID参数
+     */
     public static final String INTENT_EXTRA_BACKGROUND_ID = "net.micode.notes.background_color_id";
+    
+    /**
+     * 小部件ID参数
+     */
     public static final String INTENT_EXTRA_WIDGET_ID = "net.micode.notes.widget_id";
+    
+    /**
+     * 小部件类型参数
+     */
     public static final String INTENT_EXTRA_WIDGET_TYPE = "net.micode.notes.widget_type";
+    
+    /**
+     * 文件夹ID参数
+     */
     public static final String INTENT_EXTRA_FOLDER_ID = "net.micode.notes.folder_id";
+    
+    /**
+     * 通话日期参数
+     */
     public static final String INTENT_EXTRA_CALL_DATE = "net.micode.notes.call_date";
 
+    /**
+     * 小部件类型定义
+     */
+    
+    /**
+     * 无效小部件类型
+     */
     public static final int TYPE_WIDGET_INVALIDE      = -1;
+    
+    /**
+     * 2x大小的小部件
+     */
     public static final int TYPE_WIDGET_2X            = 0;
+    
+    /**
+     * 4x大小的小部件
+     */
     public static final int TYPE_WIDGET_4X            = 1;
 
+    /**
+     * 数据类型常量类，定义了不同类型笔记的MIME类型
+     */
     public static class DataConstants {
+        /**
+         * 普通文本笔记的MIME类型
+         */
         public static final String NOTE = TextNote.CONTENT_ITEM_TYPE;
+        
+        /**
+         * 通话记录笔记的MIME类型
+         */
         public static final String CALL_NOTE = CallNote.CONTENT_ITEM_TYPE;
     }
 
     /**
-     * Uri to query all notes and folders
+     * 用于查询所有笔记和文件夹的Uri
      */
     public static final Uri CONTENT_NOTE_URI = Uri.parse("content://" + AUTHORITY + "/note");
 
     /**
-     * Uri to query data
+     * 用于查询数据的Uri
      */
     public static final Uri CONTENT_DATA_URI = Uri.parse("content://" + AUTHORITY + "/data");
 
+    /**
+     * 笔记表列名定义接口
+     */
     public interface NoteColumns {
         /**
          * The unique ID for a row
@@ -167,6 +259,9 @@ public class Notes {
         public static final String VERSION = "version";
     }
 
+    /**
+     * 数据表列名定义接口
+     */
     public interface DataColumns {
         /**
          * The unique ID for a row
@@ -241,6 +336,9 @@ public class Notes {
         public static final String DATA5 = "data5";
     }
 
+    /**
+     * 文本笔记类，实现了DataColumns接口
+     */
     public static final class TextNote implements DataColumns {
         /**
          * Mode to indicate the text in check list mode or not
@@ -256,7 +354,10 @@ public class Notes {
 
         public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/text_note");
     }
-
+    
+    /**
+     * 通话记录笔记类，实现了DataColumns接口
+     */
     public static final class CallNote implements DataColumns {
         /**
          * Call date for this record

src/notes/data/NotesDatabaseHelper.java

@@ -27,19 +27,44 @@ import net.micode.notes.data.Notes.DataConstants;
 import net.micode.notes.data.Notes.NoteColumns;
 
 
+/**
+ * 数据库帮助类，负责数据库的创建、升级和管理
+ * 单例模式实现，提供了创建表、管理触发器和系统文件夹的功能
+ */
 public class NotesDatabaseHelper extends SQLiteOpenHelper {
+    /**
+     * 数据库名称
+     */
     private static final String DB_NAME = "note.db";
 
+    /**
+     * 数据库版本号
+     */
     private static final int DB_VERSION = 4;
 
+    /**
+     * 数据库表名定义接口
+     */
     public interface TABLE {
+        /**
+         * 笔记表名
+         */
         public static final String NOTE = "note";
 
+        /**
+         * 数据表名
+         */
         public static final String DATA = "data";
     }
 
+    /**
+     * 日志标签
+     */
     private static final String TAG = "NotesDatabaseHelper";
 
+    /**
+     * 单例实例
+     */
     private static NotesDatabaseHelper mInstance;
 
     private static final String CREATE_NOTE_TABLE_SQL =
@@ -206,18 +231,34 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         "  WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
         " END";
 
+    /**
+     * 私有构造函数，防止外部实例化
+     * @param context 上下文
+     */
     public NotesDatabaseHelper(Context context) {
         super(context, DB_NAME, null, DB_VERSION);
     }
 
+    /**
+     * 创建笔记表
+     * @param db 数据库实例
+     */
     public void createNoteTable(SQLiteDatabase db) {
+        // 执行创建表SQL
         db.execSQL(CREATE_NOTE_TABLE_SQL);
+        // 重新创建笔记表相关触发器
         reCreateNoteTableTriggers(db);
+        // 创建系统文件夹
         createSystemFolder(db);
         Log.d(TAG, "note table has been created");
     }
 
+    /**
+     * 重新创建笔记表相关触发器
+     * @param db 数据库实例
+     */
     private void reCreateNoteTableTriggers(SQLiteDatabase db) {
+        // 删除旧触发器（如果存在）
         db.execSQL("DROP TRIGGER IF EXISTS increase_folder_count_on_update");
         db.execSQL("DROP TRIGGER IF EXISTS decrease_folder_count_on_update");
         db.execSQL("DROP TRIGGER IF EXISTS decrease_folder_count_on_delete");
@@ -226,6 +267,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.execSQL("DROP TRIGGER IF EXISTS folder_delete_notes_on_delete");
         db.execSQL("DROP TRIGGER IF EXISTS folder_move_notes_on_trash");
 
+        // 创建新触发器
         db.execSQL(NOTE_INCREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER);
         db.execSQL(NOTE_DECREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER);
         db.execSQL(NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER);
@@ -235,6 +277,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.execSQL(FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER);
     }
 
+    /**
+     * 创建系统文件夹
+     * @param db 数据库实例
+     */
     private void createSystemFolder(SQLiteDatabase db) {
         ContentValues values = new ContentValues();
 
@@ -270,13 +316,24 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.insert(TABLE.NOTE, null, values);
     }
 
+    /**
+     * 创建数据表
+     * @param db 数据库实例
+     */
     public void createDataTable(SQLiteDatabase db) {
+        // 执行创建表SQL
         db.execSQL(CREATE_DATA_TABLE_SQL);
+        // 重新创建数据表相关触发器
         reCreateDataTableTriggers(db);
+        // 创建note_id索引
         db.execSQL(CREATE_DATA_NOTE_ID_INDEX_SQL);
         Log.d(TAG, "data table has been created");
     }
 
+    /**
+     * 重新创建数据表相关触发器
+     * @param db 数据库实例
+     */
     private void reCreateDataTableTriggers(SQLiteDatabase db) {
         db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_insert");
         db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_update");
@@ -287,6 +344,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER);
     }
 
+    /**
+     * 获取单例实例
+     * @param context 上下文
+     * @return 数据库帮助类实例
+     */
     static synchronized NotesDatabaseHelper getInstance(Context context) {
         if (mInstance == null) {
             mInstance = new NotesDatabaseHelper(context);
@@ -294,12 +356,24 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         return mInstance;
     }
 
+    /**
+     * 创建数据库
+     * @param db 数据库实例
+     */
     @Override
     public void onCreate(SQLiteDatabase db) {
+        // 创建笔记表
         createNoteTable(db);
+        // 创建数据表
         createDataTable(db);
     }
 
+    /**
+     * 升级数据库
+     * @param db 数据库实例
+     * @param oldVersion 旧版本号
+     * @param newVersion 新版本号
+     */
     @Override
     public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
         boolean reCreateTriggers = false;
@@ -333,6 +407,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         }
     }
 
+    /**
+     * 升级到版本2
+     * @param db 数据库实例
+     */
     private void upgradeToV2(SQLiteDatabase db) {
         db.execSQL("DROP TABLE IF EXISTS " + TABLE.NOTE);
         db.execSQL("DROP TABLE IF EXISTS " + TABLE.DATA);
@@ -340,6 +418,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         createDataTable(db);
     }
 
+    /**
+     * 升级到版本3
+     * @param db 数据库实例
+     */
     private void upgradeToV3(SQLiteDatabase db) {
         // drop unused triggers
         db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_insert");
@@ -355,6 +437,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.insert(TABLE.NOTE, null, values);
     }
 
+    /**
+     * 升级到版本4
+     * @param db 数据库实例
+     */
     private void upgradeToV4(SQLiteDatabase db) {
         db.execSQL("ALTER TABLE " + TABLE.NOTE + " ADD COLUMN " + NoteColumns.VERSION
                 + " INTEGER NOT NULL DEFAULT 0");

src/notes/data/NotesProvider.java

@@ -35,35 +35,74 @@ import net.micode.notes.data.Notes.NoteColumns;
 import net.micode.notes.data.NotesDatabaseHelper.TABLE;
 
 
+/**
+ * 笔记内容提供者，实现了ContentProvider接口
+ * 提供对笔记和数据的CRUD操作，使用UriMatcher处理不同的URI请求
+ * 是应用与数据库之间的桥梁，被其他模块通过ContentResolver调用
+ */
 public class NotesProvider extends ContentProvider {
+    /**
+     * Uri匹配器，用于匹配不同的URI请求
+     */
     private static final UriMatcher mMatcher;
 
+    /**
+     * 数据库帮助类实例
+     */
     private NotesDatabaseHelper mHelper;
 
+    /**
+     * 日志标签
+     */
     private static final String TAG = "NotesProvider";
 
+    /**
+     * URI类型：所有笔记
+     */
     private static final int URI_NOTE            = 1;
+    
+    /**
+     * URI类型：单条笔记
+     */
     private static final int URI_NOTE_ITEM       = 2;
+    
+    /**
+     * URI类型：所有数据
+     */
     private static final int URI_DATA            = 3;
+    
+    /**
+     * URI类型：单条数据
+     */
     private static final int URI_DATA_ITEM       = 4;
 
+    /**
+     * URI类型：搜索
+     */
     private static final int URI_SEARCH          = 5;
+    
+    /**
+     * URI类型：搜索建议
+     */
     private static final int URI_SEARCH_SUGGEST  = 6;
 
+    /**
+     * 静态初始化块，初始化UriMatcher
+     */
     static {
         mMatcher = new UriMatcher(UriMatcher.NO_MATCH);
-        mMatcher.addURI(Notes.AUTHORITY, "note", URI_NOTE);
+        // 添加URI匹配规则
-        mMatcher.addURI(Notes.AUTHORITY, "note/#", URI_NOTE_ITEM);
+        mMatcher.addURI(Notes.AUTHORITY, "note", URI_NOTE);           // content://micode_notes/note
-        mMatcher.addURI(Notes.AUTHORITY, "data", URI_DATA);
+        mMatcher.addURI(Notes.AUTHORITY, "note/#", URI_NOTE_ITEM);    // content://micode_notes/note/1
-        mMatcher.addURI(Notes.AUTHORITY, "data/#", URI_DATA_ITEM);
+        mMatcher.addURI(Notes.AUTHORITY, "data", URI_DATA);           // content://micode_notes/data
-        mMatcher.addURI(Notes.AUTHORITY, "search", URI_SEARCH);
+        mMatcher.addURI(Notes.AUTHORITY, "data/#", URI_DATA_ITEM);    // content://micode_notes/data/1
-        mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY, URI_SEARCH_SUGGEST);
+        mMatcher.addURI(Notes.AUTHORITY, "search", URI_SEARCH);       // content://micode_notes/search
-        mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY + "/*", URI_SEARCH_SUGGEST);
+        mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY, URI_SEARCH_SUGGEST); // 搜索建议
+        mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY + "/*", URI_SEARCH_SUGGEST); // 带参数的搜索建议
     }
 
     /**
-     * x'0A' represents the '\n' character in sqlite. For title and content in the search result,
+     * 搜索结果投影定义：替换换行符并修剪空白，确保搜索结果显示完整信息
-     * we will trim '\n' and white space in order to show more information.
      */
     private static final String NOTES_SEARCH_PROJECTION = NoteColumns.ID + ","
         + NoteColumns.ID + " AS " + SearchManager.SUGGEST_COLUMN_INTENT_EXTRA_DATA + ","
@@ -73,18 +112,35 @@ public class NotesProvider extends ContentProvider {
         + "'" + Intent.ACTION_VIEW + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_ACTION + ","
         + "'" + Notes.TextNote.CONTENT_TYPE + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA;
 
+    /**
+     * 笔记内容搜索查询语句
+     */
     private static String NOTES_SNIPPET_SEARCH_QUERY = "SELECT " + NOTES_SEARCH_PROJECTION
         + " FROM " + TABLE.NOTE
         + " WHERE " + NoteColumns.SNIPPET + " LIKE ?"
         + " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER
         + " AND " + NoteColumns.TYPE + "=" + Notes.TYPE_NOTE;
 
+    /**
+     * 初始化ContentProvider
+     * @return 是否初始化成功
+     */
     @Override
     public boolean onCreate() {
+        // 获取数据库帮助类实例
         mHelper = NotesDatabaseHelper.getInstance(getContext());
         return true;
     }
 
+    /**
+     * 查询数据
+     * @param uri 查询的URI
+     * @param projection 要查询的列
+     * @param selection 查询条件
+     * @param selectionArgs 查询条件参数
+     * @param sortOrder 排序方式
+     * @return 查询结果游标
+     */
     @Override
     public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
             String sortOrder) {
@@ -147,6 +203,12 @@ public class NotesProvider extends ContentProvider {
         return c;
     }
 
+    /**
+     * 插入数据
+     * @param uri 插入的URI
+     * @param values 要插入的数据
+     * @return 插入数据的URI
+     */
     @Override
     public Uri insert(Uri uri, ContentValues values) {
         SQLiteDatabase db = mHelper.getWritableDatabase();
@@ -181,6 +243,13 @@ public class NotesProvider extends ContentProvider {
         return ContentUris.withAppendedId(uri, insertedId);
     }
 
+    /**
+     * 删除数据
+     * @param uri 删除的URI
+     * @param selection 删除条件
+     * @param selectionArgs 删除条件参数
+     * @return 删除的行数
+     */
     @Override
     public int delete(Uri uri, String selection, String[] selectionArgs) {
         int count = 0;
@@ -227,6 +296,14 @@ public class NotesProvider extends ContentProvider {
         return count;
     }
 
+    /**
+     * 更新数据
+     * @param uri 更新的URI
+     * @param values 要更新的数据
+     * @param selection 更新条件
+     * @param selectionArgs 更新条件参数
+     * @return 更新的行数
+     */
     @Override
     public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) {
         int count = 0;
@@ -267,10 +344,21 @@ public class NotesProvider extends ContentProvider {
         return count;
     }
 
+    /**
+     * 解析查询条件
+     * @param selection 查询条件
+     * @return 解析后的查询条件
+     */
     private String parseSelection(String selection) {
         return (!TextUtils.isEmpty(selection) ? " AND (" + selection + ')' : "");
     }
 
+    /**
+     * 增加笔记版本号
+     * @param id 笔记ID
+     * @param selection 查询条件
+     * @param selectionArgs 查询条件参数
+     */
     private void increaseNoteVersion(long id, String selection, String[] selectionArgs) {
         StringBuilder sql = new StringBuilder(120);
         sql.append("UPDATE ");
@@ -296,6 +384,11 @@ public class NotesProvider extends ContentProvider {
         mHelper.getWritableDatabase().execSQL(sql.toString());
     }
 
+    /**
+     * 获取MIME类型
+     * @param uri URI
+     * @return MIME类型
+     */
     @Override
     public String getType(Uri uri) {
         // TODO Auto-generated method stub

src/notes/gtask/data/MetaData.java

@@ -25,33 +25,65 @@ import org.json.JSONException;
 import org.json.JSONObject;
 
 
+/**
+ * MetaData类 - 继承自Task类，用于存储与GTask同步相关的元数据信息
+ * 
+ * 该类主要用于在GTask同步过程中存储和管理元数据，包含与特定GTask相关联的ID信息
+ * 重写了Task类的部分方法，以适应元数据的特殊处理需求
+ */
 public class MetaData extends Task {
     private final static String TAG = MetaData.class.getSimpleName();
 
+    // 与当前元数据关联的GTask ID
     private String mRelatedGid = null;
 
+    /**
+     * 设置元数据信息
+     * 
+     * @param gid       相关联的GTask ID
+     * @param metaInfo  元数据JSON对象
+     */
     public void setMeta(String gid, JSONObject metaInfo) {
         try {
+            // 将GTask ID添加到元数据中
             metaInfo.put(GTaskStringUtils.META_HEAD_GTASK_ID, gid);
         } catch (JSONException e) {
             Log.e(TAG, "failed to put related gid");
         }
+        // 将元数据以字符串形式存储到Task的notes字段中
         setNotes(metaInfo.toString());
+        // 设置元数据任务的名称
         setName(GTaskStringUtils.META_NOTE_NAME);
     }
 
+    /**
+     * 获取与当前元数据关联的GTask ID
+     * 
+     * @return 关联的GTask ID
+     */
     public String getRelatedGid() {
         return mRelatedGid;
     }
 
+    /**
+     * 判断元数据是否值得保存
+     * 
+     * @return 如果有notes内容则返回true，否则返回false
+     */
     @Override
     public boolean isWorthSaving() {
         return getNotes() != null;
     }
 
+    /**
+     * 从远程JSON对象设置内容
+     * 
+     * @param js 远程JSON对象
+     */
     @Override
     public void setContentByRemoteJSON(JSONObject js) {
         super.setContentByRemoteJSON(js);
+        // 如果有notes内容，则解析获取关联的GTask ID
         if (getNotes() != null) {
             try {
                 JSONObject metaInfo = new JSONObject(getNotes().trim());
@@ -63,19 +95,40 @@ public class MetaData extends Task {
         }
     }
 
+    /**
+     * 从本地JSON对象设置内容 - 该方法不应被调用
+     * 
+     * @param js 本地JSON对象
+     * @throws IllegalAccessError 总是抛出该异常，表示方法不应被调用
+     */
     @Override
     public void setContentByLocalJSON(JSONObject js) {
-        // this function should not be called
+        // 元数据不支持从本地JSON设置内容
         throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");
     }
 
+    /**
+     * 从内容获取本地JSON对象 - 该方法不应被调用
+     * 
+     * @return 本地JSON对象
+     * @throws IllegalAccessError 总是抛出该异常，表示方法不应被调用
+     */
     @Override
     public JSONObject getLocalJSONFromContent() {
+        // 元数据不支持获取本地JSON对象
         throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called");
     }
 
+    /**
+     * 获取同步操作类型 - 该方法不应被调用
+     * 
+     * @param c 数据库游标
+     * @return 同步操作类型
+     * @throws IllegalAccessError 总是抛出该异常，表示方法不应被调用
+     */
     @Override
     public int getSyncAction(Cursor c) {
+        // 元数据不支持获取同步操作类型
         throw new IllegalAccessError("MetaData:getSyncAction should not be called");
     }
 

src/notes/gtask/data/Node.java

@@ -20,33 +20,81 @@ import android.database.Cursor;
 
 import org.json.JSONObject;
 
+/**
+ * Node类 - GTask同步系统中的抽象基类，定义了所有同步节点的基本属性和行为
+ * 
+ * 该抽象类为TaskList、Task和MetaData等具体类提供了统一的接口和基础功能，
+ * 主要用于管理GTask同步系统中的节点对象及其与服务器的同步操作。
+ */
 public abstract class Node {
+    /**
+     * 同步操作类型：无需同步
+     */
     public static final int SYNC_ACTION_NONE = 0;
 
+    /**
+     * 同步操作类型：在远程服务器添加
+     */
     public static final int SYNC_ACTION_ADD_REMOTE = 1;
 
+    /**
+     * 同步操作类型：在本地添加
+     */
     public static final int SYNC_ACTION_ADD_LOCAL = 2;
 
+    /**
+     * 同步操作类型：在远程服务器删除
+     */
     public static final int SYNC_ACTION_DEL_REMOTE = 3;
 
+    /**
+     * 同步操作类型：在本地删除
+     */
     public static final int SYNC_ACTION_DEL_LOCAL = 4;
 
+    /**
+     * 同步操作类型：更新远程服务器数据
+     */
     public static final int SYNC_ACTION_UPDATE_REMOTE = 5;
 
+    /**
+     * 同步操作类型：更新本地数据
+     */
     public static final int SYNC_ACTION_UPDATE_LOCAL = 6;
 
+    /**
+     * 同步操作类型：同步冲突
+     */
     public static final int SYNC_ACTION_UPDATE_CONFLICT = 7;
 
+    /**
+     * 同步操作类型：同步错误
+     */
     public static final int SYNC_ACTION_ERROR = 8;
 
+    /**
+     * 节点在Google Tasks系统中的全局唯一ID
+     */
     private String mGid;
 
+    /**
+     * 节点名称
+     */
     private String mName;
 
+    /**
+     * 节点最后修改时间戳
+     */
     private long mLastModified;
 
+    /**
+     * 节点是否已删除的标记
+     */
     private boolean mDeleted;
 
+    /**
+     * 构造函数 - 初始化节点的基本属性
+     */
     public Node() {
         mGid = null;
         mName = "";
@@ -54,46 +102,119 @@ public abstract class Node {
         mDeleted = false;
     }
 
+    /**
+     * 生成创建节点的JSON操作对象（抽象方法，子类必须实现）
+     * 
+     * @param actionId 操作ID，用于标识该同步操作
+     * @return 包含创建节点所需信息的JSON对象
+     */
     public abstract JSONObject getCreateAction(int actionId);
 
+    /**
+     * 生成更新节点的JSON操作对象（抽象方法，子类必须实现）
+     * 
+     * @param actionId 操作ID，用于标识该同步操作
+     * @return 包含更新节点所需信息的JSON对象
+     */
     public abstract JSONObject getUpdateAction(int actionId);
 
+    /**
+     * 根据远程JSON对象设置节点内容（抽象方法，子类必须实现）
+     * 
+     * @param js 从Google Tasks服务器获取的JSON对象
+     */
     public abstract void setContentByRemoteJSON(JSONObject js);
 
+    /**
+     * 根据本地JSON对象设置节点内容（抽象方法，子类必须实现）
+     * 
+     * @param js 本地存储的JSON对象
+     */
     public abstract void setContentByLocalJSON(JSONObject js);
 
+    /**
+     * 从节点内容生成本地JSON对象（抽象方法，子类必须实现）
+     * 
+     * @return 包含节点本地存储信息的JSON对象
+     */
     public abstract JSONObject getLocalJSONFromContent();
 
+    /**
+     * 根据本地数据库游标判断同步操作类型（抽象方法，子类必须实现）
+     * 
+     * @param c 本地数据库游标，包含节点的本地存储信息
+     * @return 同步操作类型（使用SYNC_ACTION_*常量）
+     */
     public abstract int getSyncAction(Cursor c);
 
+    /**
+     * 设置节点在Google Tasks系统中的全局唯一ID
+     * 
+     * @param gid 全局唯一ID
+     */
     public void setGid(String gid) {
         this.mGid = gid;
     }
 
+    /**
+     * 设置节点名称
+     * 
+     * @param name 节点名称
+     */
     public void setName(String name) {
         this.mName = name;
     }
 
+    /**
+     * 设置节点最后修改时间戳
+     * 
+     * @param lastModified 最后修改时间戳
+     */
     public void setLastModified(long lastModified) {
         this.mLastModified = lastModified;
     }
 
+    /**
+     * 设置节点是否已删除
+     * 
+     * @param deleted 是否已删除
+     */
     public void setDeleted(boolean deleted) {
         this.mDeleted = deleted;
     }
 
+    /**
+     * 获取节点在Google Tasks系统中的全局唯一ID
+     * 
+     * @return 全局唯一ID
+     */
     public String getGid() {
         return this.mGid;
     }
 
+    /**
+     * 获取节点名称
+     * 
+     * @return 节点名称
+     */
     public String getName() {
         return this.mName;
     }
 
+    /**
+     * 获取节点最后修改时间戳
+     * 
+     * @return 最后修改时间戳
+     */
     public long getLastModified() {
         return this.mLastModified;
     }
 
+    /**
+     * 获取节点是否已删除
+     * 
+     * @return 是否已删除
+     */
     public boolean getDeleted() {
         return this.mDeleted;
     }

src/notes/gtask/data/SqlData.java

@@ -35,42 +35,101 @@ import org.json.JSONException;
 import org.json.JSONObject;
 
 
+/**
+ * SqlData类 - 用于管理与笔记数据相关的SQL操作，处理Notes应用中数据行的创建、更新和内容同步
+ * 
+ * 该类主要负责：
+ * 1. 管理笔记数据的基本信息（ID、MIME类型、内容等）
+ * 2. 支持从Cursor加载数据和生成JSON格式内容
+ * 3. 处理数据的创建和更新操作，使用ContentValues跟踪差异变化
+ * 4. 将数据提交到数据库，支持版本验证
+ */
 public class SqlData {
     private static final String TAG = SqlData.class.getSimpleName();
 
+    /**
+     * 无效的ID值，用于标记未初始化或无效的数据ID
+     */
     private static final int INVALID_ID = -99999;
 
+    /**
+     * 数据库查询投影，定义了查询数据表时需要返回的列
+     */
     public static final String[] PROJECTION_DATA = new String[] {
             DataColumns.ID, DataColumns.MIME_TYPE, DataColumns.CONTENT, DataColumns.DATA1,
             DataColumns.DATA3
     };
 
+    /**
+     * PROJECTION_DATA中ID列的索引
+     */
     public static final int DATA_ID_COLUMN = 0;
 
+    /**
+     * PROJECTION_DATA中MIME类型列的索引
+     */
     public static final int DATA_MIME_TYPE_COLUMN = 1;
 
+    /**
+     * PROJECTION_DATA中内容列的索引
+     */
     public static final int DATA_CONTENT_COLUMN = 2;
 
+    /**
+     * PROJECTION_DATA中DATA1列的索引
+     */
     public static final int DATA_CONTENT_DATA_1_COLUMN = 3;
 
+    /**
+     * PROJECTION_DATA中DATA3列的索引
+     */
     public static final int DATA_CONTENT_DATA_3_COLUMN = 4;
 
+    /**
+     * 用于访问Android ContentProvider的ContentResolver对象
+     */
     private ContentResolver mContentResolver;
 
+    /**
+     * 标记当前数据是否为新创建的数据
+     */
     private boolean mIsCreate;
 
+    /**
+     * 数据的唯一标识符
+     */
     private long mDataId;
 
+    /**
+     * 数据的MIME类型
+     */
     private String mDataMimeType;
 
+    /**
+     * 数据的内容
+     */
     private String mDataContent;
 
+    /**
+     * 数据的额外信息字段1
+     */
     private long mDataContentData1;
 
+    /**
+     * 数据的额外信息字段3
+     */
     private String mDataContentData3;
 
+    /**
+     * 用于存储差异更新的ContentValues对象，只包含需要更新的字段
+     */
     private ContentValues mDiffDataValues;
 
+    /**
+     * 构造函数 - 创建一个新的SqlData对象
+     * 
+     * @param context 上下文对象，用于获取ContentResolver
+     */
     public SqlData(Context context) {
         mContentResolver = context.getContentResolver();
         mIsCreate = true;
@@ -82,6 +141,12 @@ public class SqlData {
         mDiffDataValues = new ContentValues();
     }
 
+    /**
+     * 构造函数 - 从Cursor创建SqlData对象
+     * 
+     * @param context 上下文对象，用于获取ContentResolver
+     * @param c 包含数据的Cursor对象
+     */
     public SqlData(Context context, Cursor c) {
         mContentResolver = context.getContentResolver();
         mIsCreate = false;
@@ -89,6 +154,11 @@ public class SqlData {
         mDiffDataValues = new ContentValues();
     }
 
+    /**
+     * 从Cursor加载数据到成员变量
+     * 
+     * @param c 包含数据的Cursor对象
+     */
     private void loadFromCursor(Cursor c) {
         mDataId = c.getLong(DATA_ID_COLUMN);
         mDataMimeType = c.getString(DATA_MIME_TYPE_COLUMN);
@@ -97,6 +167,12 @@ public class SqlData {
         mDataContentData3 = c.getString(DATA_CONTENT_DATA_3_COLUMN);
     }
 
+    /**
+     * 根据JSON对象设置数据内容
+     * 
+     * @param js 包含数据内容的JSON对象
+     * @throws JSONException 如果解析JSON失败
+     */
     public void setContent(JSONObject js) throws JSONException {
         long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID;
         if (mIsCreate || mDataId != dataId) {
@@ -130,6 +206,12 @@ public class SqlData {
         mDataContentData3 = dataContentData3;
     }
 
+    /**
+     * 生成包含数据内容的JSON对象
+     * 
+     * @return 包含数据内容的JSON对象
+     * @throws JSONException 如果生成JSON失败
+     */
     public JSONObject getContent() throws JSONException {
         if (mIsCreate) {
             Log.e(TAG, "it seems that we haven't created this in database yet");
@@ -144,6 +226,14 @@ public class SqlData {
         return js;
     }
 
+    /**
+     * 将数据提交到数据库
+     * 
+     * @param noteId 所属笔记的ID
+     * @param validateVersion 是否验证版本号
+     * @param version 验证的版本号
+     * @throws ActionFailureException 如果创建数据失败
+     */
     public void commit(long noteId, boolean validateVersion, long version) {
 
         if (mIsCreate) {
@@ -183,6 +273,11 @@ public class SqlData {
         mIsCreate = false;
     }
 
+    /**
+     * 获取数据ID
+     * 
+     * @return 数据的唯一标识符
+     */
     public long getId() {
         return mDataId;
     }

src/notes/gtask/data/SqlNote.java

@@ -38,11 +38,19 @@ import org.json.JSONObject;
 import java.util.ArrayList;
 
 
+/**
+ * SqlNote类 - 用于管理本地笔记数据的核心类
+ * 
+ * 该类负责处理笔记数据的加载、存储、更新和转换，是GTask同步机制与本地数据库之间的桥梁
+ * 支持从Cursor加载数据、从JSON设置内容、提交更改到数据库等功能
+ */
 public class SqlNote {
     private static final String TAG = SqlNote.class.getSimpleName();
 
+    // 无效ID常量，用于初始化和验证
     private static final int INVALID_ID = -99999;
 
+    // 笔记查询投影数组，定义了从数据库查询笔记时返回的列
     public static final String[] PROJECTION_NOTE = new String[] {
             NoteColumns.ID, NoteColumns.ALERTED_DATE, NoteColumns.BG_COLOR_ID,
             NoteColumns.CREATED_DATE, NoteColumns.HAS_ATTACHMENT, NoteColumns.MODIFIED_DATE,
@@ -52,139 +60,154 @@ public class SqlNote {
             NoteColumns.VERSION
     };
 
+    // 投影数组中各列的索引常量定义
     public static final int ID_COLUMN = 0;
-
     public static final int ALERTED_DATE_COLUMN = 1;
-
     public static final int BG_COLOR_ID_COLUMN = 2;
-
     public static final int CREATED_DATE_COLUMN = 3;
-
     public static final int HAS_ATTACHMENT_COLUMN = 4;
-
     public static final int MODIFIED_DATE_COLUMN = 5;
-
     public static final int NOTES_COUNT_COLUMN = 6;
-
     public static final int PARENT_ID_COLUMN = 7;
-
     public static final int SNIPPET_COLUMN = 8;
-
     public static final int TYPE_COLUMN = 9;
-
     public static final int WIDGET_ID_COLUMN = 10;
-
     public static final int WIDGET_TYPE_COLUMN = 11;
-
     public static final int SYNC_ID_COLUMN = 12;
-
     public static final int LOCAL_MODIFIED_COLUMN = 13;
-
     public static final int ORIGIN_PARENT_ID_COLUMN = 14;
-
     public static final int GTASK_ID_COLUMN = 15;
-
     public static final int VERSION_COLUMN = 16;
 
+    // 上下文对象，用于访问系统服务
     private Context mContext;
-
+    // 内容解析器，用于与ContentProvider交互
     private ContentResolver mContentResolver;
-
+    // 是否为新创建的笔记
     private boolean mIsCreate;
-
+    // 笔记ID
     private long mId;
-
+    // 提醒日期
     private long mAlertDate;
-
+    // 背景颜色ID
     private int mBgColorId;
-
+    // 创建日期
     private long mCreatedDate;
-
+    // 是否有附件
     private int mHasAttachment;
-
+    // 修改日期
     private long mModifiedDate;
-
+    // 父文件夹ID
     private long mParentId;
-
+    // 笔记摘要
     private String mSnippet;
-
+    // 笔记类型（普通笔记、文件夹等）
     private int mType;
-
+    // 小部件ID
     private int mWidgetId;
-
+    // 小部件类型
     private int mWidgetType;
-
+    // 原始父文件夹ID
     private long mOriginParent;
-
+    // 版本号，用于并发控制
     private long mVersion;
-
+    // 差异内容值，用于记录需要更新的字段
     private ContentValues mDiffNoteValues;
-
+    
+    // 私有成员变量，用于存储SqlData类型的数据列表
+    // 使用ArrayList作为数据结构，可以动态存储SqlData对象
     private ArrayList<SqlData> mDataList;
 
+    /**
+     * 创建新笔记的构造函数
+     * 
+     * @param context 上下文对象，用于访问系统服务
+     */
     public SqlNote(Context context) {
         mContext = context;
         mContentResolver = context.getContentResolver();
-        mIsCreate = true;
+        mIsCreate = true; // 标记为新创建的笔记
-        mId = INVALID_ID;
+        mId = INVALID_ID; // 初始化为无效ID
-        mAlertDate = 0;
+        mAlertDate = 0; // 无提醒日期
-        mBgColorId = ResourceParser.getDefaultBgId(context);
+        mBgColorId = ResourceParser.getDefaultBgId(context); // 使用默认背景颜色
-        mCreatedDate = System.currentTimeMillis();
+        mCreatedDate = System.currentTimeMillis(); // 创建日期设为当前时间
-        mHasAttachment = 0;
+        mHasAttachment = 0; // 初始没有附件
-        mModifiedDate = System.currentTimeMillis();
+        mModifiedDate = System.currentTimeMillis(); // 修改日期设为当前时间
-        mParentId = 0;
+        mParentId = 0; // 默认父文件夹ID为0
-        mSnippet = "";
+        mSnippet = ""; // 摘要为空
-        mType = Notes.TYPE_NOTE;
+        mType = Notes.TYPE_NOTE; // 默认类型为普通笔记
-        mWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
+        mWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID; // 无效小部件ID
-        mWidgetType = Notes.TYPE_WIDGET_INVALIDE;
+        mWidgetType = Notes.TYPE_WIDGET_INVALIDE; // 无效小部件类型
-        mOriginParent = 0;
+        mOriginParent = 0; // 原始父文件夹ID
-        mVersion = 0;
+        mVersion = 0; // 初始版本号
-        mDiffNoteValues = new ContentValues();
+        mDiffNoteValues = new ContentValues(); // 用于记录差异的内容值
-        mDataList = new ArrayList<SqlData>();
+        mDataList = new ArrayList<SqlData>(); // 初始化数据列表
     }
 
+    /**
+     * 从Cursor创建SqlNote对象的构造函数
+     * 
+     * @param context 上下文对象
+     * @param c       包含笔记数据的Cursor对象
+     */
     public SqlNote(Context context, Cursor c) {
         mContext = context;
         mContentResolver = context.getContentResolver();
-        mIsCreate = false;
+        mIsCreate = false; // 标记为已存在的笔记
-        loadFromCursor(c);
+        loadFromCursor(c); // 从Cursor加载数据
-        mDataList = new ArrayList<SqlData>();
+        mDataList = new ArrayList<SqlData>(); // 初始化数据列表
-        if (mType == Notes.TYPE_NOTE)
+        if (mType == Notes.TYPE_NOTE) // 如果是普通笔记，加载其数据内容
             loadDataContent();
-        mDiffNoteValues = new ContentValues();
+        mDiffNoteValues = new ContentValues(); // 用于记录差异的内容值
     }
 
+    /**
+     * 根据ID创建SqlNote对象的构造函数
+     * 
+     * @param context 上下文对象
+     * @param id      笔记的ID
+     */
     public SqlNote(Context context, long id) {
         mContext = context;
         mContentResolver = context.getContentResolver();
-        mIsCreate = false;
+        mIsCreate = false; // 标记为已存在的笔记
-        loadFromCursor(id);
+        loadFromCursor(id); // 根据ID从数据库加载数据
-        mDataList = new ArrayList<SqlData>();
+        mDataList = new ArrayList<SqlData>(); // 初始化数据列表
-        if (mType == Notes.TYPE_NOTE)
+        if (mType == Notes.TYPE_NOTE) // 如果是普通笔记，加载其数据内容
             loadDataContent();
-        mDiffNoteValues = new ContentValues();
+        mDiffNoteValues = new ContentValues(); // 用于记录差异的内容值
-
     }
 
+    /**
+     * 根据ID从数据库加载笔记数据
+     * 
+     * @param id 笔记的ID
+     */
     private void loadFromCursor(long id) {
         Cursor c = null;
         try {
+            // 查询指定ID的笔记数据
             c = mContentResolver.query(Notes.CONTENT_NOTE_URI, PROJECTION_NOTE, "(_id=?)",
                     new String[] {
                         String.valueOf(id)
                     }, null);
             if (c != null) {
                 c.moveToNext();
-                loadFromCursor(c);
+                loadFromCursor(c); // 调用Cursor版本的loadFromCursor方法
             } else {
                 Log.w(TAG, "loadFromCursor: cursor = null");
             }
         } finally {
             if (c != null)
-                c.close();
+                c.close(); // 确保Cursor被关闭
         }
     }
 
+    /**
+     * 从Cursor对象加载笔记数据到成员变量
+     * 
+     * @param c 包含笔记数据的Cursor对象
+     */
     private void loadFromCursor(Cursor c) {
         mId = c.getLong(ID_COLUMN);
         mAlertDate = c.getLong(ALERTED_DATE_COLUMN);
@@ -200,10 +223,16 @@ public class SqlNote {
         mVersion = c.getLong(VERSION_COLUMN);
     }
 
+    /**
+     * 加载笔记的具体数据内容
+     * 
+     * 该方法从数据库中查询与当前笔记关联的所有数据项，并将它们加载到mDataList中
+     */
     private void loadDataContent() {
         Cursor c = null;
-        mDataList.clear();
+        mDataList.clear(); // 清空现有数据列表
         try {
+            // 查询与当前笔记ID关联的所有数据项
             c = mContentResolver.query(Notes.CONTENT_DATA_URI, SqlData.PROJECTION_DATA,
                     "(note_id=?)", new String[] {
                         String.valueOf(mId)
@@ -213,6 +242,7 @@ public class SqlNote {
                     Log.w(TAG, "it seems that the note has not data");
                     return;
                 }
+                // 遍历Cursor，创建SqlData对象并添加到数据列表
                 while (c.moveToNext()) {
                     SqlData data = new SqlData(mContext, c);
                     mDataList.add(data);
@@ -222,17 +252,25 @@ public class SqlNote {
             }
         } finally {
             if (c != null)
-                c.close();
+                c.close(); // 确保Cursor被关闭
         }
     }
 
+    /**
+     * 从JSON对象设置笔记内容
+     * 
+     * @param js 包含笔记数据的JSON对象
+     * @return 是否成功设置内容
+     */
     public boolean setContent(JSONObject js) {
         try {
             JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
+            
+            // 根据笔记类型进行不同处理
             if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM) {
                 Log.w(TAG, "cannot set system folder");
             } else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {
-                // for folder we can only update the snnipet and type
+                // 文件夹类型只能更新摘要和类型
                 String snippet = note.has(NoteColumns.SNIPPET) ? note
                         .getString(NoteColumns.SNIPPET) : "";
                 if (mIsCreate || !mSnippet.equals(snippet)) {
@@ -247,7 +285,10 @@ public class SqlNote {
                 }
                 mType = type;
             } else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_NOTE) {
+                // 普通笔记类型，需要处理所有字段和关联的数据
                 JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
+                
+                // 更新笔记基本信息
                 long id = note.has(NoteColumns.ID) ? note.getLong(NoteColumns.ID) : INVALID_ID;
                 if (mIsCreate || mId != id) {
                     mDiffNoteValues.put(NoteColumns.ID, id);
@@ -331,9 +372,12 @@ public class SqlNote {
                 }
                 mOriginParent = originParent;
 
+                // 处理笔记关联的数据项
                 for (int i = 0; i < dataArray.length(); i++) {
                     JSONObject data = dataArray.getJSONObject(i);
                     SqlData sqlData = null;
+                    
+                    // 尝试在现有数据列表中找到匹配的SqlData对象
                     if (data.has(DataColumns.ID)) {
                         long dataId = data.getLong(DataColumns.ID);
                         for (SqlData temp : mDataList) {
@@ -343,11 +387,13 @@ public class SqlNote {
                         }
                     }
 
+                    // 如果找不到匹配的SqlData对象，则创建新的
                     if (sqlData == null) {
                         sqlData = new SqlData(mContext);
                         mDataList.add(sqlData);
                     }
 
+                    // 设置SqlData的内容
                     sqlData.setContent(data);
                 }
             }
@@ -359,17 +405,26 @@ public class SqlNote {
         return true;
     }
 
+    /**
+     * 获取笔记内容的JSON表示
+     * 
+     * @return 包含笔记内容的JSON对象，如果获取失败则返回null
+     */
     public JSONObject getContent() {
         try {
             JSONObject js = new JSONObject();
 
+            // 如果是新创建的笔记（尚未保存到数据库），则无法获取内容
             if (mIsCreate) {
                 Log.e(TAG, "it seems that we haven't created this in database yet");
                 return null;
             }
 
             JSONObject note = new JSONObject();
+            
+            // 根据笔记类型构建不同的JSON结构
             if (mType == Notes.TYPE_NOTE) {
+                // 普通笔记类型，包含完整的笔记信息和关联数据
                 note.put(NoteColumns.ID, mId);
                 note.put(NoteColumns.ALERTED_DATE, mAlertDate);
                 note.put(NoteColumns.BG_COLOR_ID, mBgColorId);
@@ -384,6 +439,7 @@ public class SqlNote {
                 note.put(NoteColumns.ORIGIN_PARENT_ID, mOriginParent);
                 js.put(GTaskStringUtils.META_HEAD_NOTE, note);
 
+                // 添加关联的数据项
                 JSONArray dataArray = new JSONArray();
                 for (SqlData sqlData : mDataList) {
                     JSONObject data = sqlData.getContent();
@@ -393,6 +449,7 @@ public class SqlNote {
                 }
                 js.put(GTaskStringUtils.META_HEAD_DATA, dataArray);
             } else if (mType == Notes.TYPE_FOLDER || mType == Notes.TYPE_SYSTEM) {
+                // 文件夹或系统类型，只包含基本信息
                 note.put(NoteColumns.ID, mId);
                 note.put(NoteColumns.TYPE, mType);
                 note.put(NoteColumns.SNIPPET, mSnippet);
@@ -407,48 +464,97 @@ public class SqlNote {
         return null;
     }
 
+    /**
+     * 设置笔记的父文件夹ID
+     * 
+     * @param id 父文件夹的ID
+     */
     public void setParentId(long id) {
         mParentId = id;
         mDiffNoteValues.put(NoteColumns.PARENT_ID, id);
     }
 
+    /**
+     * 设置笔记的GTask ID（用于同步）
+     * 
+     * @param gid GTask ID
+     */
     public void setGtaskId(String gid) {
         mDiffNoteValues.put(NoteColumns.GTASK_ID, gid);
     }
 
+    /**
+     * 设置笔记的同步ID
+     * 
+     * @param syncId 同步ID
+     */
     public void setSyncId(long syncId) {
         mDiffNoteValues.put(NoteColumns.SYNC_ID, syncId);
     }
 
+    /**
+     * 重置本地修改标志
+     * 
+     * 将本地修改标志设置为0，表示当前内容与服务器同步
+     */
     public void resetLocalModified() {
         mDiffNoteValues.put(NoteColumns.LOCAL_MODIFIED, 0);
     }
 
+    /**
+     * 获取笔记的ID
+     * 
+     * @return 笔记的ID
+     */
     public long getId() {
         return mId;
     }
 
+    /**
+     * 获取笔记的父文件夹ID
+     * 
+     * @return 父文件夹的ID
+     */
     public long getParentId() {
         return mParentId;
     }
 
+    /**
+     * 获取笔记的摘要
+     * 
+     * @return 笔记的摘要
+     */
     public String getSnippet() {
         return mSnippet;
     }
 
+    /**
+     * 检查笔记是否为普通笔记类型
+     * 
+     * @return 是否为普通笔记类型
+     */
     public boolean isNoteType() {
         return mType == Notes.TYPE_NOTE;
     }
 
+    /**
+     * 将笔记内容提交到数据库
+     * 
+     * @param validateVersion 是否验证版本号
+     * @throws ActionFailureException 如果创建笔记失败
+     * @throws IllegalStateException 如果更新笔记时ID无效
+     */
     public void commit(boolean validateVersion) {
         if (mIsCreate) {
+            // 新创建的笔记，执行插入操作
             if (mId == INVALID_ID && mDiffNoteValues.containsKey(NoteColumns.ID)) {
-                mDiffNoteValues.remove(NoteColumns.ID);
+                mDiffNoteValues.remove(NoteColumns.ID); // 移除无效ID
             }
 
+            // 插入笔记到数据库
             Uri uri = mContentResolver.insert(Notes.CONTENT_NOTE_URI, mDiffNoteValues);
             try {
-                mId = Long.valueOf(uri.getPathSegments().get(1));
+                mId = Long.valueOf(uri.getPathSegments().get(1)); // 获取自动生成的ID
             } catch (NumberFormatException e) {
                 Log.e(TAG, "Get note id error :" + e.toString());
                 throw new ActionFailureException("create note failed");
@@ -457,27 +563,29 @@ public class SqlNote {
                 throw new IllegalStateException("Create thread id failed");
             }
 
+            // 如果是普通笔记，提交其关联的数据
             if (mType == Notes.TYPE_NOTE) {
                 for (SqlData sqlData : mDataList) {
                     sqlData.commit(mId, false, -1);
                 }
             }
         } else {
+            // 已存在的笔记，执行更新操作
             if (mId <= 0 && mId != Notes.ID_ROOT_FOLDER && mId != Notes.ID_CALL_RECORD_FOLDER) {
                 Log.e(TAG, "No such note");
                 throw new IllegalStateException("Try to update note with invalid id");
             }
             if (mDiffNoteValues.size() > 0) {
-                mVersion ++;
+                mVersion ++; // 版本号递增
                 int result = 0;
                 if (!validateVersion) {
-                    result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
+                    // 不验证版本，直接更新
-                            + NoteColumns.ID + "=?)", new String[] {
+                    result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "(" + NoteColumns.ID + "=?)", new String[] {
                         String.valueOf(mId)
                     });
                 } else {
-                    result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
+                    // 验证版本，防止并发更新冲突
-                            + NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)",
+                    result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "(" + NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)",
                             new String[] {
                                     String.valueOf(mId), String.valueOf(mVersion)
                             });
@@ -487,6 +595,7 @@ public class SqlNote {
                 }
             }
 
+            // 如果是普通笔记，提交其关联的数据
             if (mType == Notes.TYPE_NOTE) {
                 for (SqlData sqlData : mDataList) {
                     sqlData.commit(mId, validateVersion, mVersion);
@@ -494,11 +603,12 @@ public class SqlNote {
             }
         }
 
-        // refresh local info
+        // 刷新本地信息，确保与数据库一致
         loadFromCursor(mId);
         if (mType == Notes.TYPE_NOTE)
             loadDataContent();
 
+        // 清空差异内容值并标记为已存在
         mDiffNoteValues.clear();
         mIsCreate = false;
     }

src/notes/gtask/data/Task.java

@@ -32,19 +32,47 @@ import org.json.JSONException;
 import org.json.JSONObject;
 
 
+/**
+ * Task类 - 继承自Node类，用于表示GTask同步系统中的单个任务
+ * 
+ * 该类主要负责：
+ * 1. 管理任务的基本信息（名称、备注、完成状态等）
+ * 2. 维护任务之间的关系（前一个兄弟任务、父任务列表）
+ * 3. 处理与GTask服务器的同步操作（创建、更新、同步状态判断）
+ * 4. 支持本地与远程JSON格式的相互转换
+ * 5. 管理任务的元信息，用于与本地笔记系统关联
+ */
 public class Task extends Node {
     private static final String TAG = Task.class.getSimpleName();
 
+    /**
+     * 任务的完成状态
+     */
     private boolean mCompleted;
 
+    /**
+     * 任务的备注信息
+     */
     private String mNotes;
 
+    /**
+     * 任务的元信息，以JSON格式存储，用于与本地笔记系统关联
+     */
     private JSONObject mMetaInfo;
 
+    /**
+     * 当前任务的前一个兄弟任务，用于维护任务列表中的顺序
+     */
     private Task mPriorSibling;
 
+    /**
+     * 当前任务所属的父任务列表
+     */
     private TaskList mParent;
 
+    /**
+     * 构造函数 - 初始化任务的基本属性
+     */
     public Task() {
         super();
         mCompleted = false;
@@ -54,6 +82,13 @@ public class Task extends Node {
         mMetaInfo = null;
     }
 
+    /**
+     * 生成创建任务的JSON操作对象
+     * 
+     * @param actionId 操作ID，用于标识该同步操作
+     * @return 包含创建任务所需信息的JSON对象
+     * @throws ActionFailureException 如果生成JSON失败
+     */
     public JSONObject getCreateAction(int actionId) {
         JSONObject js = new JSONObject();
 
@@ -103,6 +138,13 @@ public class Task extends Node {
         return js;
     }
 
+    /**
+     * 生成更新任务的JSON操作对象
+     * 
+     * @param actionId 操作ID，用于标识该同步操作
+     * @return 包含更新任务所需信息的JSON对象
+     * @throws ActionFailureException 如果生成JSON失败
+     */
     public JSONObject getUpdateAction(int actionId) {
         JSONObject js = new JSONObject();
 
@@ -135,6 +177,12 @@ public class Task extends Node {
         return js;
     }
 
+    /**
+     * 根据远程JSON对象设置任务内容
+     * 
+     * @param js 从Google Tasks服务器获取的JSON对象
+     * @throws ActionFailureException 如果解析JSON失败
+     */
     public void setContentByRemoteJSON(JSONObject js) {
         if (js != null) {
             try {
@@ -175,6 +223,11 @@ public class Task extends Node {
         }
     }
 
+    /**
+     * 根据本地JSON对象设置任务内容
+     * 
+     * @param js 本地存储的JSON对象
+     */
     public void setContentByLocalJSON(JSONObject js) {
         if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)
                 || !js.has(GTaskStringUtils.META_HEAD_DATA)) {
@@ -204,6 +257,11 @@ public class Task extends Node {
         }
     }
 
+    /**
+     * 从任务内容生成本地JSON对象
+     * 
+     * @return 包含任务本地存储信息的JSON对象，如果生成失败则返回null
+     */
     public JSONObject getLocalJSONFromContent() {
         String name = getName();
         try {
@@ -247,6 +305,11 @@ public class Task extends Node {
         }
     }
 
+    /**
+     * 设置任务的元信息
+     * 
+     * @param metaData 包含任务元信息的MetaData对象
+     */
     public void setMetaInfo(MetaData metaData) {
         if (metaData != null && metaData.getNotes() != null) {
             try {
@@ -258,6 +321,17 @@ public class Task extends Node {
         }
     }
 
+    /**
+     * 根据本地数据库游标判断同步操作类型
+     * 
+     * @param c 本地数据库游标，包含任务的本地存储信息
+     * @return 同步操作类型：
+     *         - SYNC_ACTION_NONE: 无需同步
+     *         - SYNC_ACTION_UPDATE_LOCAL: 更新本地数据
+     *         - SYNC_ACTION_UPDATE_REMOTE: 更新远程数据
+     *         - SYNC_ACTION_UPDATE_CONFLICT: 同步冲突
+     *         - SYNC_ACTION_ERROR: 同步错误
+     */
     public int getSyncAction(Cursor c) {
         try {
             JSONObject noteInfo = null;
@@ -311,39 +385,84 @@ public class Task extends Node {
         return SYNC_ACTION_ERROR;
     }
 
+    /**
+     * 判断任务是否值得保存
+     * 
+     * @return 如果任务有元信息、名称或备注，则返回true，否则返回false
+     */
     public boolean isWorthSaving() {
         return mMetaInfo != null || (getName() != null && getName().trim().length() > 0)
                 || (getNotes() != null && getNotes().trim().length() > 0);
     }
 
+    /**
+     * 设置任务的完成状态
+     * 
+     * @param completed 任务的完成状态
+     */
     public void setCompleted(boolean completed) {
         this.mCompleted = completed;
     }
 
+    /**
+     * 设置任务的备注信息
+     * 
+     * @param notes 任务的备注信息
+     */
     public void setNotes(String notes) {
         this.mNotes = notes;
     }
 
+    /**
+     * 设置任务的前一个兄弟任务
+     * 
+     * @param priorSibling 前一个兄弟任务
+     */
     public void setPriorSibling(Task priorSibling) {
         this.mPriorSibling = priorSibling;
     }
 
+    /**
+     * 设置任务的父任务列表
+     * 
+     * @param parent 父任务列表
+     */
     public void setParent(TaskList parent) {
         this.mParent = parent;
     }
 
+    /**
+     * 获取任务的完成状态
+     * 
+     * @return 任务的完成状态
+     */
     public boolean getCompleted() {
         return this.mCompleted;
     }
 
+    /**
+     * 获取任务的备注信息
+     * 
+     * @return 任务的备注信息
+     */
     public String getNotes() {
         return this.mNotes;
     }
 
+    /**
+     * 获取任务的前一个兄弟任务
+     * 
+     * @return 前一个兄弟任务
+     */
     public Task getPriorSibling() {
         return this.mPriorSibling;
     }
 
+    /**
+     * 获取任务的父任务列表
+     * 
+     * @return 父任务列表
+     */
     public TaskList getParent() {
         return this.mParent;
     }

src/notes/gtask/data/TaskList.java

@@ -30,19 +30,44 @@ import org.json.JSONObject;
 import java.util.ArrayList;
 
 
+/**
+ * TaskList类 - 继承自Node类，用于表示任务列表并管理其中的Task对象集合
+ * 
+ * 该类主要负责：
+ * 1. 管理任务列表的基本信息（名称、ID、修改时间等）
+ * 2. 维护子Task对象的集合及其关系
+ * 3. 处理与GTask服务器的同步操作（创建、更新、同步状态判断）
+ * 4. 支持本地与远程JSON格式的相互转换
+ */
 public class TaskList extends Node {
     private static final String TAG = TaskList.class.getSimpleName();
 
+    /**
+     * 任务列表在Google Tasks中的索引位置，用于排序
+     */
     private int mIndex;
 
+    /**
+     * 存储当前任务列表包含的所有Task对象
+     */
     private ArrayList<Task> mChildren;
 
+    /**
+     * 构造函数 - 初始化空的Task列表，设置默认索引为1
+     */
     public TaskList() {
         super();
         mChildren = new ArrayList<Task>();
         mIndex = 1;
     }
 
+    /**
+     * 生成创建任务列表的JSON操作对象
+     * 
+     * @param actionId 操作ID，用于标识该同步操作
+     * @return 包含创建任务列表所需信息的JSON对象
+     * @throws ActionFailureException 如果生成JSON失败
+     */
     public JSONObject getCreateAction(int actionId) {
         JSONObject js = new JSONObject();
 
@@ -74,6 +99,13 @@ public class TaskList extends Node {
         return js;
     }
 
+    /**
+     * 生成更新任务列表的JSON操作对象
+     * 
+     * @param actionId 操作ID，用于标识该同步操作
+     * @return 包含更新任务列表所需信息的JSON对象
+     * @throws ActionFailureException 如果生成JSON失败
+     */
     public JSONObject getUpdateAction(int actionId) {
         JSONObject js = new JSONObject();
 
@@ -103,6 +135,12 @@ public class TaskList extends Node {
         return js;
     }
 
+    /**
+     * 根据远程JSON对象设置任务列表内容
+     * 
+     * @param js 从Google Tasks服务器获取的JSON对象
+     * @throws ActionFailureException 如果解析JSON失败
+     */
     public void setContentByRemoteJSON(JSONObject js) {
         if (js != null) {
             try {
@@ -129,6 +167,11 @@ public class TaskList extends Node {
         }
     }
 
+    /**
+     * 根据本地JSON对象设置任务列表内容
+     * 
+     * @param js 本地存储的JSON对象
+     */
     public void setContentByLocalJSON(JSONObject js) {
         if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)) {
             Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
@@ -157,6 +200,11 @@ public class TaskList extends Node {
         }
     }
 
+    /**
+     * 从任务列表内容生成本地JSON对象
+     * 
+     * @return 包含任务列表本地存储信息的JSON对象，如果生成失败则返回null
+     */
     public JSONObject getLocalJSONFromContent() {
         try {
             JSONObject js = new JSONObject();
@@ -183,6 +231,16 @@ public class TaskList extends Node {
         }
     }
 
+    /**
+     * 根据本地数据库游标判断同步操作类型
+     * 
+     * @param c 本地数据库游标，包含任务列表的本地存储信息
+     * @return 同步操作类型：
+     *         - SYNC_ACTION_NONE: 无需同步
+     *         - SYNC_ACTION_UPDATE_LOCAL: 更新本地数据
+     *         - SYNC_ACTION_UPDATE_REMOTE: 更新远程数据
+     *         - SYNC_ACTION_ERROR: 同步错误
+     */
     public int getSyncAction(Cursor c) {
         try {
             if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
@@ -216,10 +274,21 @@ public class TaskList extends Node {
         return SYNC_ACTION_ERROR;
     }
 
+    /**
+     * 获取子任务数量
+     * 
+     * @return 子任务的总数
+     */
     public int getChildTaskCount() {
         return mChildren.size();
     }
 
+    /**
+     * 添加子任务到任务列表末尾
+     * 
+     * @param task 要添加的子任务
+     * @return 是否添加成功
+     */
     public boolean addChildTask(Task task) {
         boolean ret = false;
         if (task != null && !mChildren.contains(task)) {
@@ -234,6 +303,13 @@ public class TaskList extends Node {
         return ret;
     }
 
+    /**
+     * 在指定位置添加子任务
+     * 
+     * @param task 要添加的子任务
+     * @param index 要插入的位置索引
+     * @return 是否添加成功
+     */
     public boolean addChildTask(Task task, int index) {
         if (index < 0 || index > mChildren.size()) {
             Log.e(TAG, "add child task: invalid index");
@@ -260,6 +336,12 @@ public class TaskList extends Node {
         return true;
     }
 
+    /**
+     * 从任务列表中移除子任务
+     * 
+     * @param task 要移除的子任务
+     * @return 是否移除成功
+     */
     public boolean removeChildTask(Task task) {
         boolean ret = false;
         int index = mChildren.indexOf(task);
@@ -281,6 +363,13 @@ public class TaskList extends Node {
         return ret;
     }
 
+    /**
+     * 移动子任务到指定位置
+     * 
+     * @param task 要移动的子任务
+     * @param index 目标位置索引
+     * @return 是否移动成功
+     */
     public boolean moveChildTask(Task task, int index) {
 
         if (index < 0 || index >= mChildren.size()) {
@@ -299,6 +388,12 @@ public class TaskList extends Node {
         return (removeChildTask(task) && addChildTask(task, index));
     }
 
+    /**
+     * 根据Gid查找子任务
+     * 
+     * @param gid 要查找的任务Gid
+     * @return 找到的Task对象，如果未找到则返回null
+     */
     public Task findChildTaskByGid(String gid) {
         for (int i = 0; i < mChildren.size(); i++) {
             Task t = mChildren.get(i);
@@ -309,10 +404,22 @@ public class TaskList extends Node {
         return null;
     }
 
+    /**
+     * 获取子任务在列表中的索引位置
+     * 
+     * @param task 要查找的子任务
+     * @return 子任务在列表中的索引，未找到则返回-1
+     */
     public int getChildTaskIndex(Task task) {
         return mChildren.indexOf(task);
     }
 
+    /**
+     * 根据索引获取子任务
+     * 
+     * @param index 子任务的索引位置
+     * @return 对应索引的Task对象，如果索引无效则返回null
+     */
     public Task getChildTaskByIndex(int index) {
         if (index < 0 || index >= mChildren.size()) {
             Log.e(TAG, "getTaskByIndex: invalid index");
@@ -321,6 +428,12 @@ public class TaskList extends Node {
         return mChildren.get(index);
     }
 
+    /**
+     * 根据Gid查找子任务（与findChildTaskByGid功能相同，为了兼容性保留）
+     * 
+     * @param gid 要查找的任务Gid
+     * @return 找到的Task对象，如果未找到则返回null
+     */
     public Task getChilTaskByGid(String gid) {
         for (Task task : mChildren) {
             if (task.getGid().equals(gid))
@@ -329,14 +442,29 @@ public class TaskList extends Node {
         return null;
     }
 
+    /**
+     * 获取所有子任务的列表
+     * 
+     * @return 包含所有子任务的ArrayList
+     */
     public ArrayList<Task> getChildTaskList() {
         return this.mChildren;
     }
 
+    /**
+     * 设置任务列表的索引位置
+     * 
+     * @param index 新的索引位置
+     */
     public void setIndex(int index) {
         this.mIndex = index;
     }
 
+    /**
+     * 获取任务列表的索引位置
+     * 
+     * @return 当前索引位置
+     */
     public int getIndex() {
         return this.mIndex;
     }

src/notes/gtask/exception/ActionFailureException.java

@@ -16,17 +16,39 @@
 
 package net.micode.notes.gtask.exception;
 
+/**
+ * ActionFailureException类 - 继承自RuntimeException，用于表示GTask同步操作失败的异常
+ * 
+ * 该异常主要在GTask同步过程中，当执行任务列表或任务的创建、更新、删除等操作失败时抛出
+ * 作为运行时异常，可以由上层调用者选择性捕获，用于处理同步操作失败的情况
+ * 
+ * @author MiCode Open Source Community
+ */
 public class ActionFailureException extends RuntimeException {
     private static final long serialVersionUID = 4425249765923293627L;
 
+    /**
+     * 无参构造方法，创建一个没有详细消息和原因的ActionFailureException
+     */
     public ActionFailureException() {
         super();
     }
 
+    /**
+     * 构造方法，创建一个包含指定详细消息的ActionFailureException
+     * 
+     * @param paramString 详细错误消息，描述异常发生的原因
+     */
     public ActionFailureException(String paramString) {
         super(paramString);
     }
 
+    /**
+     * 构造方法，创建一个包含指定详细消息和原因的ActionFailureException
+     * 
+     * @param paramString 详细错误消息，描述异常发生的原因
+     * @param paramThrowable 导致当前异常的原因异常
+     */
     public ActionFailureException(String paramString, Throwable paramThrowable) {
         super(paramString, paramThrowable);
     }

src/notes/gtask/exception/NetworkFailureException.java

@@ -16,17 +16,39 @@
 
 package net.micode.notes.gtask.exception;
 
+/**
+ * NetworkFailureException类 - 继承自Exception，用于表示GTask同步过程中的网络故障异常
+ * 
+ * 该异常主要在GTask同步过程中，当与Google Tasks服务器通信时出现网络问题（如连接超时、网络不可用等）时抛出
+ * 作为受检异常，必须由调用者显式捕获并处理，用于处理网络相关的错误情况
+ * 
+ * @author MiCode Open Source Community
+ */
 public class NetworkFailureException extends Exception {
     private static final long serialVersionUID = 2107610287180234136L;
 
+    /**
+     * 无参构造方法，创建一个没有详细消息和原因的NetworkFailureException
+     */
     public NetworkFailureException() {
         super();
     }
 
+    /**
+     * 构造方法，创建一个包含指定详细消息的NetworkFailureException
+     * 
+     * @param paramString 详细错误消息，描述网络故障的原因
+     */
     public NetworkFailureException(String paramString) {
         super(paramString);
     }
 
+    /**
+     * 构造方法，创建一个包含指定详细消息和原因的NetworkFailureException
+     * 
+     * @param paramString 详细错误消息，描述网络故障的原因
+     * @param paramThrowable 导致当前异常的原因异常（如IOException等）
+     */
     public NetworkFailureException(String paramString, Throwable paramThrowable) {
         super(paramString, paramThrowable);
     }

src/notes/gtask/remote/GTaskASyncTask.java

@@ -29,11 +29,35 @@ import net.micode.notes.ui.NotesListActivity;
 import net.micode.notes.ui.NotesPreferenceActivity;
 
 
+/**
+ * GTaskASyncTask类 - 继承自AsyncTask，用于在后台执行Google Tasks同步操作
+ * 
+ * 该类负责在后台线程中执行Google Tasks的同步工作，并在UI线程中更新同步进度和结果
+ * 主要功能包括：
+ * - 在后台执行同步操作
+ * - 显示同步进度通知
+ * - 发送同步状态广播
+ * - 处理同步完成后的回调
+ * - 支持取消同步操作
+ * 
+ * @author MiCode Open Source Community
+ */
 public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
 
+    /**
+     * 同步通知的唯一标识符
+     */
     private static int GTASK_SYNC_NOTIFICATION_ID = 5234235;
 
+    /**
+     * OnCompleteListener接口 - 同步完成事件的监听器
+     * 
+     * 该接口用于在同步操作完成后接收回调通知
+     */
     public interface OnCompleteListener {
+        /**
+         * 同步完成时调用的方法
+         */
         void onComplete();
     }
 
@@ -45,6 +69,12 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
 
     private OnCompleteListener mOnCompleteListener;
 
+    /**
+     * 构造方法，创建一个GTaskASyncTask实例
+     * 
+     * @param context 上下文对象，用于获取系统服务和资源
+     * @param listener 同步完成监听器，用于接收同步完成的回调
+     */
     public GTaskASyncTask(Context context, OnCompleteListener listener) {
         mContext = context;
         mOnCompleteListener = listener;
@@ -53,35 +83,75 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
         mTaskManager = GTaskManager.getInstance();
     }
 
+    /**
+     * 取消正在进行的同步操作
+     * 
+     * 该方法通过调用GTaskManager的cancelSync方法来取消同步
+     */
     public void cancelSync() {
         mTaskManager.cancelSync();
     }
 
+    /**
+     * 发布同步进度消息
+     * 
+     * 该方法用于向UI线程发送同步进度更新
+     * 
+     * @param message 进度消息内容
+     */
     public void publishProgess(String message) {
         publishProgress(new String[] {
             message
         });
     }
 
+    /**
+     * 显示同步通知
+     * 
+     * 该方法用于显示同步状态的通知消息，包括进度通知和结果通知
+     * 
+     * @param tickerId 通知标题的资源ID
+     * @param content 通知内容
+     */
     private void showNotification(int tickerId, String content) {
-        Notification notification = new Notification(R.drawable.notification, mContext
+        // 1. 创建通知构建器（替代旧构造函数）
-                .getString(tickerId), System.currentTimeMillis());
+        Notification.Builder builder = new Notification.Builder(mContext)
-        notification.defaults = Notification.DEFAULT_LIGHTS;
+                .setSmallIcon(R.drawable.notification)  // 替代旧的第一个参数
-        notification.flags = Notification.FLAG_AUTO_CANCEL;
+                .setTicker(mContext.getString(tickerId))  // 替代旧的第二个参数
-        PendingIntent pendingIntent;
+                .setWhen(System.currentTimeMillis())  // 替代旧的第三个参数
+                .setDefaults(Notification.DEFAULT_LIGHTS)  // 替代 notification.defaults
+                .setAutoCancel(true)  // 替代 notification.flags = FLAG_AUTO_CANCEL
+                .setContentTitle(mContext.getString(R.string.app_name))
+                .setContentText(content);
+
+        // 2. 创建 PendingIntent
+        Intent intent;
         if (tickerId != R.string.ticker_success) {
-            pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+            intent = new Intent(mContext, NotesPreferenceActivity.class);
-                    NotesPreferenceActivity.class), 0);
-
         } else {
-            pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+            intent = new Intent(mContext, NotesListActivity.class);
-                    NotesListActivity.class), 0);
         }
-        notification.setLatestEventInfo(mContext, mContext.getString(R.string.app_name), content,
+
-                pendingIntent);
+        // Android 12+ 需要 FLAG_IMMUTABLE 或 FLAG_MUTABLE
+        PendingIntent pendingIntent = PendingIntent.getActivity(
+                mContext, 0, intent, PendingIntent.FLAG_IMMUTABLE);
+
+        // 3. 设置意图
+        builder.setContentIntent(pendingIntent);
+
+        // 4. 构建并发送通知
+        Notification notification = builder.build();
         mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
     }
 
+    /**
+     * 在后台线程中执行同步操作
+     * 
+     * 该方法是AsyncTask的核心方法，在后台线程中执行Google Tasks的同步工作
+     * 
+     * @param unused 未使用的参数
+     * @return 同步结果状态码，对应GTaskManager中的状态常量
+     */
     @Override
     protected Integer doInBackground(Void... unused) {
         publishProgess(mContext.getString(R.string.sync_progress_login, NotesPreferenceActivity
@@ -89,6 +159,13 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
         return mTaskManager.sync(mContext, this);
     }
 
+    /**
+     * 在UI线程中更新同步进度
+     * 
+     * 当后台线程调用publishProgress方法时，该方法会在UI线程中被调用
+     * 
+     * @param progress 进度消息数组，包含最新的进度消息
+     */
     @Override
     protected void onProgressUpdate(String... progress) {
         showNotification(R.string.ticker_syncing, progress[0]);
@@ -97,6 +174,13 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
         }
     }
 
+    /**
+     * 在UI线程中处理同步完成后的结果
+     * 
+     * 当后台线程的doInBackground方法执行完成后，该方法会在UI线程中被调用
+     * 
+     * @param result 同步结果状态码，对应GTaskManager中的状态常量
+     */
     @Override
     protected void onPostExecute(Integer result) {
         if (result == GTaskManager.STATE_SUCCESS) {

src/notes/gtask/remote/GTaskClient.java

@@ -61,6 +61,14 @@ import java.util.zip.Inflater;
 import java.util.zip.InflaterInputStream;
 
 
+/**
+ * GTaskClient类 - Google Tasks服务器通信的核心客户端类，使用单例模式实现
+ * 
+ * 该类负责与Google Tasks服务器进行通信，处理用户认证、任务列表和任务的创建、更新、删除等操作
+ * 封装了HTTP请求和响应处理，JSON数据解析，以及与Google Tasks API的交互逻辑
+ * 
+ * @author MiCode Open Source Community
+ */
 public class GTaskClient {
     private static final String TAG = GTaskClient.class.getSimpleName();
 
@@ -102,6 +110,14 @@ public class GTaskClient {
         mUpdateArray = null;
     }
 
+    /**
+     * 获取GTaskClient的单例实例
+     * 
+     * 该方法采用同步机制，确保在多线程环境下只有一个GTaskClient实例
+     * 单例模式保证了全局只有一个客户端实例，避免了重复创建连接和资源浪费
+     * 
+     * @return GTaskClient的单例实例
+     */
     public static synchronized GTaskClient getInstance() {
         if (mInstance == null) {
             mInstance = new GTaskClient();
@@ -109,6 +125,16 @@ public class GTaskClient {
         return mInstance;
     }
 
+    /**
+     * 登录Google Tasks服务
+     * 
+     * 该方法负责处理用户认证，包括获取Google账户令牌、设置认证cookie等
+     * 支持自定义域名和官方域名登录尝试，确保在各种环境下都能成功登录
+     * 登录成功后会记录客户端版本和登录时间
+     * 
+     * @param activity 上下文Activity，用于获取账户管理器
+     * @return 登录成功返回true，否则返回false
+     */
     public boolean login(Activity activity) {
         // we suppose that the cookie would expire after 5 minutes
         // then we need to re-login
@@ -360,6 +386,16 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 创建Google Tasks任务
+     * 
+     * 该方法将本地任务对象同步到Google Tasks服务器，创建新的任务
+     * 创建成功后会从服务器返回的响应中获取并设置任务的全局唯一ID（GID）
+     * 
+     * @param task 要创建的任务对象，包含任务的各种属性
+     * @throws NetworkFailureException 网络通信失败时抛出此异常
+     * @throws ActionFailureException 任务创建操作失败时抛出此异常
+     */
     public void createTask(Task task) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -386,6 +422,16 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 创建Google Tasks任务列表
+     * 
+     * 该方法将本地任务列表对象同步到Google Tasks服务器，创建新的任务列表
+     * 创建成功后会从服务器返回的响应中获取并设置任务列表的全局唯一ID（GID）
+     * 
+     * @param tasklist 要创建的任务列表对象，包含任务列表的各种属性
+     * @throws NetworkFailureException 网络通信失败时抛出此异常
+     * @throws ActionFailureException 任务列表创建操作失败时抛出此异常
+     */
     public void createTaskList(TaskList tasklist) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -412,6 +458,15 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 提交所有待更新的节点到服务器
+     * 
+     * 该方法将缓存的更新操作批量发送到Google Tasks服务器，实现批量更新
+     * 主要用于优化性能，减少网络请求次数
+     * 
+     * @throws NetworkFailureException 网络通信失败时抛出此异常
+     * @throws ActionFailureException 更新提交操作失败时抛出此异常
+     */
     public void commitUpdate() throws NetworkFailureException {
         if (mUpdateArray != null) {
             try {
@@ -433,6 +488,16 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 添加待更新的节点到缓存中
+     * 
+     * 该方法将需要更新的节点添加到缓存数组中，当缓存达到一定数量（10个）时自动提交
+     * 用于实现批量更新，减少网络请求次数
+     * 
+     * @param node 要更新的节点对象
+     * @throws NetworkFailureException 网络通信失败时抛出此异常
+     * @throws ActionFailureException 添加节点操作失败时抛出此异常
+     */
     public void addUpdateNode(Node node) throws NetworkFailureException {
         if (node != null) {
             // too many update items may result in an error
@@ -447,6 +512,19 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 移动任务到指定的任务列表或同一列表内的新位置
+     * 
+     * 该方法支持两种移动操作：
+     * 1. 在同一任务列表内移动任务（调整任务顺序）
+     * 2. 在不同任务列表之间移动任务
+     * 
+     * @param task 要移动的任务对象
+     * @param preParent 移动前的父任务列表
+     * @param curParent 移动后的父任务列表
+     * @throws NetworkFailureException 网络通信失败时抛出此异常
+     * @throws ActionFailureException 任务移动操作失败时抛出此异常
+     */
     public void moveTask(Task task, TaskList preParent, TaskList curParent)
             throws NetworkFailureException {
         commitUpdate();
@@ -486,6 +564,15 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 删除指定的节点（任务或任务列表）
+     * 
+     * 该方法将节点标记为已删除，并发送删除请求到Google Tasks服务器
+     * 
+     * @param node 要删除的节点对象
+     * @throws NetworkFailureException 网络通信失败时抛出此异常
+     * @throws ActionFailureException 节点删除操作失败时抛出此异常
+     */
     public void deleteNode(Node node) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -509,6 +596,15 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 获取所有任务列表
+     * 
+     * 该方法从Google Tasks服务器获取用户的所有任务列表
+     * 
+     * @return 包含所有任务列表信息的JSONArray
+     * @throws NetworkFailureException 网络通信失败时抛出此异常
+     * @throws ActionFailureException 获取任务列表操作失败时抛出此异常
+     */
     public JSONArray getTaskLists() throws NetworkFailureException {
         if (!mLoggedin) {
             Log.e(TAG, "please login first");
@@ -547,6 +643,16 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 获取指定任务列表的所有任务
+     * 
+     * 该方法从Google Tasks服务器获取指定任务列表中的所有任务
+     * 
+     * @param listGid 任务列表的全局唯一ID
+     * @return 包含指定任务列表所有任务信息的JSONArray
+     * @throws NetworkFailureException 网络通信失败时抛出此异常
+     * @throws ActionFailureException 获取任务列表内容操作失败时抛出此异常
+     */
     public JSONArray getTaskList(String listGid) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -575,10 +681,20 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 获取当前同步使用的Google账户
+     * 
+     * @return 当前同步使用的Google账户对象
+     */
     public Account getSyncAccount() {
         return mAccount;
     }
 
+    /**
+     * 重置更新数组，清空所有待更新的节点
+     * 
+     * 该方法用于取消所有未提交的更新操作
+     */
     public void resetUpdateArray() {
         mUpdateArray = null;
     }

src/notes/gtask/remote/GTaskManager.java

@@ -48,17 +48,45 @@ import java.util.Iterator;
 import java.util.Map;
 
 
+/**
+ * GTaskManager类 - Google Tasks同步管理的核心类，使用单例模式实现
+ * 
+ * 该类负责协调本地笔记数据与Google Tasks服务器之间的同步工作
+ * 主要功能包括：
+ * - 管理同步生命周期和状态
+ * - 协调本地与远程数据的增删改查操作
+ * - 处理同步冲突和错误
+ * - 维护本地与远程数据的映射关系
+ * - 管理元数据和同步状态
+ * 
+ * @author MiCode Open Source Community
+ */
 public class GTaskManager {
     private static final String TAG = GTaskManager.class.getSimpleName();
 
+    /**
+     * 同步状态：成功完成
+     */
     public static final int STATE_SUCCESS = 0;
 
+    /**
+     * 同步状态：网络错误
+     */
     public static final int STATE_NETWORK_ERROR = 1;
 
+    /**
+     * 同步状态：内部错误
+     */
     public static final int STATE_INTERNAL_ERROR = 2;
 
+    /**
+     * 同步状态：同步进行中
+     */
     public static final int STATE_SYNC_IN_PROGRESS = 3;
 
+    /**
+     * 同步状态：同步已取消
+     */
     public static final int STATE_SYNC_CANCELLED = 4;
 
     private static GTaskManager mInstance = null;
@@ -99,6 +127,14 @@ public class GTaskManager {
         mNidToGid = new HashMap<Long, String>();
     }
 
+    /**
+     * 获取GTaskManager的单例实例
+     * 
+     * 该方法采用同步机制，确保在多线程环境下只有一个GTaskManager实例
+     * 单例模式保证了全局只有一个同步管理器实例，避免了重复创建和资源浪费
+     * 
+     * @return GTaskManager的单例实例
+     */
     public static synchronized GTaskManager getInstance() {
         if (mInstance == null) {
             mInstance = new GTaskManager();
@@ -106,11 +142,36 @@ public class GTaskManager {
         return mInstance;
     }
 
+    /**
+     * 设置Activity上下文
+     * 
+     * 该方法用于设置获取Google认证令牌所需的Activity上下文
+     * 
+     * @param activity 上下文Activity，用于获取账户管理器和认证令牌
+     */
     public synchronized void setActivityContext(Activity activity) {
         // used for getting authtoken
         mActivity = activity;
     }
 
+    /**
+     * 执行Google Tasks同步操作
+     * 
+     * 该方法是同步的入口点，负责协调整个同步流程：
+     * 1. 登录Google Tasks服务
+     * 2. 初始化任务列表
+     * 3. 执行内容同步
+     * 4. 处理同步结果和错误
+     * 
+     * @param context 上下文对象，用于获取内容解析器
+     * @param asyncTask 异步任务对象，用于发布同步进度
+     * @return 同步状态码：
+     *         - STATE_SUCCESS：同步成功
+     *         - STATE_NETWORK_ERROR：网络错误
+     *         - STATE_INTERNAL_ERROR：内部错误
+     *         - STATE_SYNC_IN_PROGRESS：同步已在进行中
+     *         - STATE_SYNC_CANCELLED：同步已取消
+     */
     public int sync(Context context, GTaskASyncTask asyncTask) {
         if (mSyncing) {
             Log.d(TAG, "Sync is in progress");
@@ -790,10 +851,20 @@ public class GTaskManager {
         }
     }
 
+    /**
+     * 获取当前同步使用的Google账户名
+     * 
+     * @return 当前同步使用的Google账户名
+     */
     public String getSyncAccount() {
         return GTaskClient.getInstance().getSyncAccount().name;
     }
 
+    /**
+     * 取消正在进行的同步操作
+     * 
+     * 设置取消标志，使同步过程在适当的时机停止
+     */
     public void cancelSync() {
         mCancelled = true;
     }

src/notes/gtask/remote/GTaskSyncService.java

@@ -23,25 +23,66 @@ import android.content.Intent;
 import android.os.Bundle;
 import android.os.IBinder;
 
+/**
+ * GTaskSyncService类 - 继承自Android Service，用于管理Google Tasks同步服务
+ * 
+ * 该服务负责处理Google Tasks的同步生命周期，包括启动同步、取消同步以及发送同步状态广播
+ * 它通过GTaskASyncTask在后台执行同步操作，并通过广播通知UI组件同步状态和进度
+ * 
+ * @author MiCode Open Source Community
+ */
 public class GTaskSyncService extends Service {
+    /**
+     * 同步操作类型的Intent额外数据键名
+     */
     public final static String ACTION_STRING_NAME = "sync_action_type";
 
+    /**
+     * 同步操作类型：开始同步
+     */
     public final static int ACTION_START_SYNC = 0;
 
+    /**
+     * 同步操作类型：取消同步
+     */
     public final static int ACTION_CANCEL_SYNC = 1;
 
+    /**
+     * 同步操作类型：无效操作
+     */
     public final static int ACTION_INVALID = 2;
 
+    /**
+     * 同步服务广播的Action名称
+     */
     public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service";
 
+    /**
+     * 广播中表示同步状态的额外数据键名
+     */
     public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing";
 
+    /**
+     * 广播中表示同步进度消息的额外数据键名
+     */
     public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg";
 
+    /**
+     * 当前正在执行的同步任务实例
+     */
     private static GTaskASyncTask mSyncTask = null;
 
+    /**
+     * 当前同步进度消息
+     */
     private static String mSyncProgress = "";
 
+    /**
+     * 开始同步操作
+     * 
+     * 如果当前没有正在执行的同步任务，则创建新的GTaskASyncTask实例并执行同步
+     * 同步完成后会清理任务实例并停止服务
+     */
     private void startSync() {
         if (mSyncTask == null) {
             mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
@@ -56,6 +97,11 @@ public class GTaskSyncService extends Service {
         }
     }
 
+    /**
+     * 取消当前同步操作
+     * 
+     * 如果当前有正在执行的同步任务，则调用其cancelSync方法取消同步
+     */
     private void cancelSync() {
         if (mSyncTask != null) {
             mSyncTask.cancelSync();
@@ -67,6 +113,16 @@ public class GTaskSyncService extends Service {
         mSyncTask = null;
     }
 
+    /**
+     * 处理服务启动命令
+     * 
+     * 根据Intent中携带的操作类型，执行对应的同步操作（开始或取消）
+     * 
+     * @param intent 启动服务的Intent，包含操作类型
+     * @param flags 启动标志
+     * @param startId 服务启动ID
+     * @return 服务启动模式，此处返回START_STICKY表示服务被杀死后会自动重启
+     */
     @Override
     public int onStartCommand(Intent intent, int flags, int startId) {
         Bundle bundle = intent.getExtras();
@@ -86,6 +142,11 @@ public class GTaskSyncService extends Service {
         return super.onStartCommand(intent, flags, startId);
     }
 
+    /**
+     * 当系统内存不足时调用
+     * 
+     * 在此方法中取消当前正在执行的同步任务，以释放系统资源
+     */
     @Override
     public void onLowMemory() {
         if (mSyncTask != null) {
@@ -93,10 +154,25 @@ public class GTaskSyncService extends Service {
         }
     }
 
+    /**
+     * 绑定服务时调用
+     * 
+     * 该服务不支持绑定，因此返回null
+     * 
+     * @param intent 绑定服务的Intent
+     * @return 服务的IBinder接口，此处返回null
+     */
     public IBinder onBind(Intent intent) {
         return null;
     }
 
+    /**
+     * 发送同步状态广播
+     * 
+     * 将当前同步状态和进度消息通过广播发送给所有监听该广播的组件
+     * 
+     * @param msg 当前同步进度消息
+     */
     public void sendBroadcast(String msg) {
         mSyncProgress = msg;
         Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
@@ -105,6 +181,13 @@ public class GTaskSyncService extends Service {
         sendBroadcast(intent);
     }
 
+    /**
+     * 静态方法：启动同步服务
+     * 
+     * 通过Activity上下文启动GTaskSyncService并发送开始同步的命令
+     * 
+     * @param activity 用于启动服务的Activity上下文
+     */
     public static void startSync(Activity activity) {
         GTaskManager.getInstance().setActivityContext(activity);
         Intent intent = new Intent(activity, GTaskSyncService.class);
@@ -112,16 +195,37 @@ public class GTaskSyncService extends Service {
         activity.startService(intent);
     }
 
+    /**
+     * 静态方法：取消同步服务
+     * 
+     * 通过Context上下文启动GTaskSyncService并发送取消同步的命令
+     * 
+     * @param context 用于启动服务的上下文
+     */
     public static void cancelSync(Context context) {
         Intent intent = new Intent(context, GTaskSyncService.class);
         intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_CANCEL_SYNC);
         context.startService(intent);
     }
 
+    /**
+     * 静态方法：检查是否正在同步
+     * 
+     * 判断当前是否有正在执行的同步任务
+     * 
+     * @return true表示正在同步，false表示未同步
+     */
     public static boolean isSyncing() {
         return mSyncTask != null;
     }
 
+    /**
+     * 静态方法：获取当前同步进度消息
+     * 
+     * 获取当前同步进度的字符串消息
+     * 
+     * @return 当前同步进度消息
+     */
     public static String getProgressString() {
         return mSyncProgress;
     }

src/notes/model/Note.java

@@ -34,12 +34,38 @@ import net.micode.notes.data.Notes.TextNote;
 import java.util.ArrayList;
 
 
+/**
+ * Note类 - 表示应用中的笔记数据模型
+ * 
+ * 该类是笔记应用的核心数据模型，用于封装笔记的基本信息和内容数据
+ * 支持文本笔记和通话笔记两种类型，提供了笔记的创建、更新和同步功能
+ * 采用ContentResolver与ContentProvider进行数据交互，实现数据的持久化存储
+ * 
+ * @author MiCode Open Source Community
+ */
 public class Note {
+    /**
+     * 笔记基本信息的变更值
+     */
     private ContentValues mNoteDiffValues;
+    /**
+     * 笔记内容数据（文本和通话）
+     */
     private NoteData mNoteData;
+    /**
+     * 日志标签
+     */
     private static final String TAG = "Note";
     /**
-     * Create a new note id for adding a new note to databases
+     * 创建一个新的笔记ID并在数据库中插入新笔记
+     * 
+     * 该方法会在数据库中创建一个新的笔记记录，并返回生成的笔记ID
+     * 新笔记会设置默认的创建时间、修改时间和类型
+     * 
+     * @param context 上下文对象，用于获取ContentResolver
+     * @param folderId 笔记所属的文件夹ID
+     * @return 新创建的笔记ID
+     * @throws IllegalStateException 如果创建笔记失败
      */
     public static synchronized long getNewNoteId(Context context, long folderId) {
         // Create a new note in the database
@@ -65,41 +91,92 @@ public class Note {
         return noteId;
     }
 
+    /**
+     * 默认构造方法
+     * 
+     * 初始化笔记的基本信息和内容数据对象
+     */
     public Note() {
         mNoteDiffValues = new ContentValues();
         mNoteData = new NoteData();
     }
 
+    /**
+     * 设置笔记的基本信息值
+     * 
+     * @param key 字段名
+     * @param value 字段值
+     */
     public void setNoteValue(String key, String value) {
         mNoteDiffValues.put(key, value);
         mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
         mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
     }
 
+    /**
+     * 设置笔记的文本数据
+     * 
+     * @param key 文本数据字段名
+     * @param value 文本数据字段值
+     */
     public void setTextData(String key, String value) {
         mNoteData.setTextData(key, value);
     }
 
+    /**
+     * 设置笔记文本数据的ID
+     * 
+     * @param id 文本数据ID
+     */
     public void setTextDataId(long id) {
         mNoteData.setTextDataId(id);
     }
 
+    /**
+     * 获取笔记文本数据的ID
+     * 
+     * @return 文本数据ID
+     */
     public long getTextDataId() {
         return mNoteData.mTextDataId;
     }
 
+    /**
+     * 设置笔记通话数据的ID
+     * 
+     * @param id 通话数据ID
+     */
     public void setCallDataId(long id) {
         mNoteData.setCallDataId(id);
     }
 
+    /**
+     * 设置笔记的通话数据
+     * 
+     * @param key 通话数据字段名
+     * @param value 通话数据字段值
+     */
     public void setCallData(String key, String value) {
         mNoteData.setCallData(key, value);
     }
 
+    /**
+     * 检查笔记是否在本地被修改
+     * 
+     * @return true表示本地已修改，false表示未修改
+     */
     public boolean isLocalModified() {
         return mNoteDiffValues.size() > 0 || mNoteData.isLocalModified();
     }
 
+    /**
+     * 将笔记的本地修改同步到数据库
+     * 
+     * @param context 上下文对象，用于获取ContentResolver
+     * @param noteId 笔记ID
+     * @return true表示同步成功，false表示同步失败
+     * @throws IllegalArgumentException 如果笔记ID无效
+     */
     public boolean syncNote(Context context, long noteId) {
         if (noteId <= 0) {
             throw new IllegalArgumentException("Wrong note id:" + noteId);
@@ -130,17 +207,43 @@ public class Note {
         return true;
     }
 
+    /**
+     * NoteData类 - 表示笔记的内容数据（内部类）
+     * 
+     * 该内部类用于封装笔记的内容数据，包括文本数据和通话数据
+     * 提供了数据的设置、修改检查和同步到ContentResolver的功能
+     */
     private class NoteData {
+        /**
+         * 文本数据的ID
+         */
         private long mTextDataId;
 
+        /**
+         * 文本数据的变更值
+         */
         private ContentValues mTextDataValues;
 
+        /**
+         * 通话数据的ID
+         */
         private long mCallDataId;
 
+        /**
+         * 通话数据的变更值
+         */
         private ContentValues mCallDataValues;
 
+        /**
+         * 日志标签
+         */
         private static final String TAG = "NoteData";
 
+        /**
+         * 默认构造方法
+         * 
+         * 初始化文本数据和通话数据的内容值对象
+         */
         public NoteData() {
             mTextDataValues = new ContentValues();
             mCallDataValues = new ContentValues();
@@ -148,10 +251,21 @@ public class Note {
             mCallDataId = 0;
         }
 
+        /**
+         * 检查内容数据是否在本地被修改
+         * 
+         * @return true表示本地已修改，false表示未修改
+         */
         boolean isLocalModified() {
             return mTextDataValues.size() > 0 || mCallDataValues.size() > 0;
         }
 
+        /**
+         * 设置文本数据的ID
+         * 
+         * @param id 文本数据ID
+         * @throws IllegalArgumentException 如果ID无效
+         */
         void setTextDataId(long id) {
             if(id <= 0) {
                 throw new IllegalArgumentException("Text data id should larger than 0");
@@ -159,6 +273,12 @@ public class Note {
             mTextDataId = id;
         }
 
+        /**
+         * 设置通话数据的ID
+         * 
+         * @param id 通话数据ID
+         * @throws IllegalArgumentException 如果ID无效
+         */
         void setCallDataId(long id) {
             if (id <= 0) {
                 throw new IllegalArgumentException("Call data id should larger than 0");
@@ -166,18 +286,38 @@ public class Note {
             mCallDataId = id;
         }
 
+        /**
+         * 设置通话数据
+         * 
+         * @param key 通话数据字段名
+         * @param value 通话数据字段值
+         */
         void setCallData(String key, String value) {
             mCallDataValues.put(key, value);
             mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
             mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
         }
 
+        /**
+         * 设置文本数据
+         * 
+         * @param key 文本数据字段名
+         * @param value 文本数据字段值
+         */
         void setTextData(String key, String value) {
             mTextDataValues.put(key, value);
             mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
             mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
         }
 
+        /**
+         * 将内容数据同步到ContentResolver
+         * 
+         * @param context 上下文对象，用于获取ContentResolver
+         * @param noteId 所属笔记的ID
+         * @return 同步成功返回笔记URI，失败返回null
+         * @throws IllegalArgumentException 如果笔记ID无效
+         */
         Uri pushIntoContentResolver(Context context, long noteId) {
             /**
              * Check for safety

src/notes/model/WorkingNote.java

@@ -32,34 +32,71 @@ import net.micode.notes.data.Notes.TextNote;
 import net.micode.notes.tool.ResourceParser.NoteBgResources;
 
 
+/**
+ * WorkingNote类 - 表示正在编辑或使用中的笔记
+ * 
+ * 该类是Note类的包装器，提供了更丰富的功能和更便捷的操作方式
+ * 用于处理笔记的创建、加载、保存、属性设置等操作，支持文本笔记和通话笔记
+ * 管理笔记的各种属性，如背景颜色、提醒时间、小部件信息等
+ * 
+ * @author MiCode Open Source Community
+ */
 public class WorkingNote {
-    // Note for the working note
+    /**
+     * 内部封装的Note对象
+     */
     private Note mNote;
-    // Note Id
+    /**
+     * 笔记ID
+     */
     private long mNoteId;
-    // Note content
+    /**
+     * 笔记内容
+     */
     private String mContent;
-    // Note mode
+    /**
+     * 笔记模式（如普通模式、清单模式）
+     */
     private int mMode;
-
+    /**
+     * 提醒时间
+     */
     private long mAlertDate;
-
+    /**
+     * 修改时间
+     */
     private long mModifiedDate;
-
+    /**
+     * 背景颜色ID
+     */
     private int mBgColorId;
-
+    /**
+     * 小部件ID
+     */
     private int mWidgetId;
-
+    /**
+     * 小部件类型
+     */
     private int mWidgetType;
-
+    /**
+     * 所属文件夹ID
+     */
     private long mFolderId;
-
+    /**
+     * 上下文对象
+     */
     private Context mContext;
-
+    /**
+     * 日志标签
+     */
     private static final String TAG = "WorkingNote";
-
+    /**
+     * 是否已删除标志
+     */
     private boolean mIsDeleted;
-
+    /**
+     * 笔记设置变化监听器
+     */
     private NoteSettingChangedListener mNoteSettingStatusListener;
 
     public static final String[] DATA_PROJECTION = new String[] {

src/notes/tool/BackupUtils.java

@@ -35,10 +35,10 @@ import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.PrintStream;
 
-
 public class BackupUtils {
     private static final String TAG = "BackupUtils";
-    // Singleton stuff
+
+    // 单例模式实现
     private static BackupUtils sInstance;
 
     public static synchronized BackupUtils getInstance(Context context) {
@@ -49,43 +49,45 @@ public class BackupUtils {
     }
 
     /**
-     * Following states are signs to represents backup or restore
+     * 备份/恢复操作状态码
-     * status
      */
-    // Currently, the sdcard is not mounted
+    public static final int STATE_SD_CARD_UNMOUONTED           = 0;  // SD卡未挂载
-    public static final int STATE_SD_CARD_UNMOUONTED           = 0;
+    public static final int STATE_BACKUP_FILE_NOT_EXIST        = 1;  // 备份文件不存在
-    // The backup file not exist
+    public static final int STATE_DATA_DESTROIED               = 2;  // 数据被破坏
-    public static final int STATE_BACKUP_FILE_NOT_EXIST        = 1;
+    public static final int STATE_SYSTEM_ERROR                 = 3;  // 系统错误
-    // The data is not well formated, may be changed by other programs
+    public static final int STATE_SUCCESS                      = 4;  // 操作成功
-    public static final int STATE_DATA_DESTROIED               = 2;
+
-    // Some run-time exception which causes restore or backup fails
+    private TextExport mTextExport;  // 文本导出处理器
-    public static final int STATE_SYSTEM_ERROR                 = 3;
-    // Backup or restore success
-    public static final int STATE_SUCCESS                      = 4;
-
-    private TextExport mTextExport;
 
     private BackupUtils(Context context) {
         mTextExport = new TextExport(context);
     }
 
+    // 检查外部存储是否可用
     private static boolean externalStorageAvailable() {
         return Environment.MEDIA_MOUNTED.equals(Environment.getExternalStorageState());
     }
 
+    // 导出到文本文件的主入口方法
     public int exportToText() {
         return mTextExport.exportToText();
     }
 
+    // 获取导出的文本文件名
     public String getExportedTextFileName() {
         return mTextExport.mFileName;
     }
 
+    // 获取导出的文本文件目录
     public String getExportedTextFileDir() {
         return mTextExport.mFileDirectory;
     }
 
+    /**
+     * 内部类：处理文本导出的具体逻辑
+     */
     private static class TextExport {
+        // 笔记表查询字段
         private static final String[] NOTE_PROJECTION = {
                 NoteColumns.ID,
                 NoteColumns.MODIFIED_DATE,
@@ -93,12 +95,11 @@ public class BackupUtils {
                 NoteColumns.TYPE
         };
 
-        private static final int NOTE_COLUMN_ID = 0;
+        private static final int NOTE_COLUMN_ID = 0;                // 笔记ID索引
-
+        private static final int NOTE_COLUMN_MODIFIED_DATE = 1;     // 修改日期索引
-        private static final int NOTE_COLUMN_MODIFIED_DATE = 1;
+        private static final int NOTE_COLUMN_SNIPPET = 2;           // 摘要内容索引
-
-        private static final int NOTE_COLUMN_SNIPPET = 2;
 
+        // 数据表查询字段
         private static final String[] DATA_PROJECTION = {
                 DataColumns.CONTENT,
                 DataColumns.MIME_TYPE,
@@ -108,52 +109,54 @@ public class BackupUtils {
                 DataColumns.DATA4,
         };
 
-        private static final int DATA_COLUMN_CONTENT = 0;
+        private static final int DATA_COLUMN_CONTENT = 0;          // 内容索引
-
+        private static final int DATA_COLUMN_MIME_TYPE = 1;        // MIME类型索引
-        private static final int DATA_COLUMN_MIME_TYPE = 1;
+        private static final int DATA_COLUMN_CALL_DATE = 2;        // 通话日期索引
-
+        private static final int DATA_COLUMN_PHONE_NUMBER = 4;     // 电话号码索引
-        private static final int DATA_COLUMN_CALL_DATE = 2;
-
-        private static final int DATA_COLUMN_PHONE_NUMBER = 4;
 
+        // 文本格式化字符串（从资源文件加载）
         private final String [] TEXT_FORMAT;
-        private static final int FORMAT_FOLDER_NAME          = 0;
+        private static final int FORMAT_FOLDER_NAME          = 0;  // 文件夹名称格式
-        private static final int FORMAT_NOTE_DATE            = 1;
+        private static final int FORMAT_NOTE_DATE            = 1;  // 笔记日期格式
-        private static final int FORMAT_NOTE_CONTENT         = 2;
+        private static final int FORMAT_NOTE_CONTENT         = 2;  // 笔记内容格式
 
         private Context mContext;
-        private String mFileName;
+        private String mFileName;      // 导出的文件名
-        private String mFileDirectory;
+        private String mFileDirectory; // 导出的文件目录
 
         public TextExport(Context context) {
+            // 从资源文件加载导出格式
             TEXT_FORMAT = context.getResources().getStringArray(R.array.format_for_exported_note);
             mContext = context;
             mFileName = "";
             mFileDirectory = "";
         }
 
+        // 获取指定格式的字符串
         private String getFormat(int id) {
             return TEXT_FORMAT[id];
         }
 
         /**
-         * Export the folder identified by folder id to text
+         * 导出指定文件夹下的所有笔记到文本
+         * @param folderId 文件夹ID
+         * @param ps 输出流
          */
         private void exportFolderToText(String folderId, PrintStream ps) {
-            // Query notes belong to this folder
+            // 查询属于该文件夹的所有笔记
             Cursor notesCursor = mContext.getContentResolver().query(Notes.CONTENT_NOTE_URI,
                     NOTE_PROJECTION, NoteColumns.PARENT_ID + "=?", new String[] {
-                        folderId
+                            folderId
                     }, null);
 
             if (notesCursor != null) {
                 if (notesCursor.moveToFirst()) {
                     do {
-                        // Print note's last modified date
+                        // 输出笔记的最后修改日期
                         ps.println(String.format(getFormat(FORMAT_NOTE_DATE), DateFormat.format(
                                 mContext.getString(R.string.format_datetime_mdhm),
                                 notesCursor.getLong(NOTE_COLUMN_MODIFIED_DATE))));
-                        // Query data belong to this note
+                        // 导出该笔记的具体内容
                         String noteId = notesCursor.getString(NOTE_COLUMN_ID);
                         exportNoteToText(noteId, ps);
                     } while (notesCursor.moveToNext());
@@ -163,20 +166,25 @@ public class BackupUtils {
         }
 
         /**
-         * Export note identified by id to a print stream
+         * 导出指定笔记的内容到文本
+         * @param noteId 笔记ID
+         * @param ps 输出流
          */
         private void exportNoteToText(String noteId, PrintStream ps) {
+            // 查询该笔记的所有数据项
             Cursor dataCursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI,
                     DATA_PROJECTION, DataColumns.NOTE_ID + "=?", new String[] {
-                        noteId
+                            noteId
                     }, null);
 
             if (dataCursor != null) {
                 if (dataCursor.moveToFirst()) {
                     do {
                         String mimeType = dataCursor.getString(DATA_COLUMN_MIME_TYPE);
+
+                        // 根据MIME类型处理不同类型的数据
                         if (DataConstants.CALL_NOTE.equals(mimeType)) {
-                            // Print phone number
+                            // 处理通话记录类型的笔记
                             String phoneNumber = dataCursor.getString(DATA_COLUMN_PHONE_NUMBER);
                             long callDate = dataCursor.getLong(DATA_COLUMN_CALL_DATE);
                             String location = dataCursor.getString(DATA_COLUMN_CONTENT);
@@ -185,16 +193,17 @@ public class BackupUtils {
                                 ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
                                         phoneNumber));
                             }
-                            // Print call date
+                            // 输出通话日期
                             ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), DateFormat
                                     .format(mContext.getString(R.string.format_datetime_mdhm),
                                             callDate)));
-                            // Print call attachment location
+                            // 输出通话附件位置
                             if (!TextUtils.isEmpty(location)) {
                                 ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
                                         location));
                             }
                         } else if (DataConstants.NOTE.equals(mimeType)) {
+                            // 处理普通文本笔记
                             String content = dataCursor.getString(DATA_COLUMN_CONTENT);
                             if (!TextUtils.isEmpty(content)) {
                                 ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
@@ -205,7 +214,8 @@ public class BackupUtils {
                 }
                 dataCursor.close();
             }
-            // print a line separator between note
+
+            // 在笔记之间添加分隔符
             try {
                 ps.write(new byte[] {
                         Character.LINE_SEPARATOR, Character.LETTER_NUMBER
@@ -216,20 +226,25 @@ public class BackupUtils {
         }
 
         /**
-         * Note will be exported as text which is user readable
+         * 主导出方法：将所有笔记导出为可读的文本格式
+         * @return 导出状态码
          */
         public int exportToText() {
+            // 检查存储卡是否可用
             if (!externalStorageAvailable()) {
                 Log.d(TAG, "Media was not mounted");
                 return STATE_SD_CARD_UNMOUONTED;
             }
 
+            // 获取输出流
             PrintStream ps = getExportToTextPrintStream();
             if (ps == null) {
                 Log.e(TAG, "get print stream error");
                 return STATE_SYSTEM_ERROR;
             }
-            // First export folder and its notes
+
+            // 第一部分：导出文件夹及其中的笔记
+            // 查询所有文件夹（排除回收站，但包含通话记录文件夹）
             Cursor folderCursor = mContext.getContentResolver().query(
                     Notes.CONTENT_NOTE_URI,
                     NOTE_PROJECTION,
@@ -240,7 +255,7 @@ public class BackupUtils {
             if (folderCursor != null) {
                 if (folderCursor.moveToFirst()) {
                     do {
-                        // Print folder's name
+                        // 输出文件夹名称
                         String folderName = "";
                         if(folderCursor.getLong(NOTE_COLUMN_ID) == Notes.ID_CALL_RECORD_FOLDER) {
                             folderName = mContext.getString(R.string.call_record_folder_name);
@@ -250,6 +265,7 @@ public class BackupUtils {
                         if (!TextUtils.isEmpty(folderName)) {
                             ps.println(String.format(getFormat(FORMAT_FOLDER_NAME), folderName));
                         }
+                        // 导出该文件夹下的所有笔记
                         String folderId = folderCursor.getString(NOTE_COLUMN_ID);
                         exportFolderToText(folderId, ps);
                     } while (folderCursor.moveToNext());
@@ -257,7 +273,7 @@ public class BackupUtils {
                 folderCursor.close();
             }
 
-            // Export notes in root's folder
+            // 第二部分：导出根目录下的笔记（不属于任何文件夹的笔记）
             Cursor noteCursor = mContext.getContentResolver().query(
                     Notes.CONTENT_NOTE_URI,
                     NOTE_PROJECTION,
@@ -270,30 +286,36 @@ public class BackupUtils {
                         ps.println(String.format(getFormat(FORMAT_NOTE_DATE), DateFormat.format(
                                 mContext.getString(R.string.format_datetime_mdhm),
                                 noteCursor.getLong(NOTE_COLUMN_MODIFIED_DATE))));
-                        // Query data belong to this note
+                        // 导出该笔记的内容
                         String noteId = noteCursor.getString(NOTE_COLUMN_ID);
                         exportNoteToText(noteId, ps);
                     } while (noteCursor.moveToNext());
                 }
                 noteCursor.close();
             }
-            ps.close();
 
+            // 关闭输出流
+            ps.close();
             return STATE_SUCCESS;
         }
 
         /**
-         * Get a print stream pointed to the file {@generateExportedTextFile}
+         * 创建并获取指向导出文件的输出流
+         * @return PrintStream 输出流，失败返回null
          */
         private PrintStream getExportToTextPrintStream() {
+            // 生成文件名（基于当前时间）
             File file = generateFileMountedOnSDcard(mContext, R.string.file_path,
                     R.string.file_name_txt_format);
             if (file == null) {
                 Log.e(TAG, "create file to exported failed");
                 return null;
             }
+
+            // 记录文件名和目录
             mFileName = file.getName();
             mFileDirectory = mContext.getString(R.string.file_path);
+
             PrintStream ps = null;
             try {
                 FileOutputStream fos = new FileOutputStream(file);
@@ -310,13 +332,20 @@ public class BackupUtils {
     }
 
     /**
-     * Generate the text file to store imported data
+     * 在SD卡上创建用于存储导出数据的文本文件
+     * @param context 上下文
+     * @param filePathResId 文件路径资源ID
+     * @param fileNameFormatResId 文件名格式资源ID
+     * @return 创建的File对象，失败返回null
      */
     private static File generateFileMountedOnSDcard(Context context, int filePathResId, int fileNameFormatResId) {
+        // 构建完整文件路径
         StringBuilder sb = new StringBuilder();
-        sb.append(Environment.getExternalStorageDirectory());
+        sb.append(Environment.getExternalStorageDirectory());  // SD卡根目录
-        sb.append(context.getString(filePathResId));
+        sb.append(context.getString(filePathResId));           // 相对路径
         File filedir = new File(sb.toString());
+
+        // 构建完整文件名（包含时间戳）
         sb.append(context.getString(
                 fileNameFormatResId,
                 DateFormat.format(context.getString(R.string.format_date_ymd),
@@ -324,9 +353,11 @@ public class BackupUtils {
         File file = new File(sb.toString());
 
         try {
+            // 创建目录（如果不存在）
             if (!filedir.exists()) {
                 filedir.mkdir();
             }
+            // 创建文件（如果不存在）
             if (!file.exists()) {
                 file.createNewFile();
             }
@@ -339,6 +370,4 @@ public class BackupUtils {
 
         return null;
     }
-}
+}
-
-

src/notes/tool/DataUtils.java

@@ -34,9 +34,15 @@ import net.micode.notes.ui.NotesListAdapter.AppWidgetAttribute;
 import java.util.ArrayList;
 import java.util.HashSet;
 
-
 public class DataUtils {
     public static final String TAG = "DataUtils";
+
+    /**
+     * 批量删除笔记
+     * @param resolver ContentResolver实例
+     * @param ids 要删除的笔记ID集合
+     * @return 删除是否成功
+     */
     public static boolean batchDeleteNotes(ContentResolver resolver, HashSet<Long> ids) {
         if (ids == null) {
             Log.d(TAG, "the ids is null");
@@ -47,17 +53,21 @@ public class DataUtils {
             return true;
         }
 
+        // 构建批量删除操作列表
         ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
         for (long id : ids) {
             if(id == Notes.ID_ROOT_FOLDER) {
-                Log.e(TAG, "Don't delete system folder root");
+                Log.e(TAG, "Don't delete system folder root");  // 禁止删除根文件夹
                 continue;
             }
+            // 为每个笔记ID创建删除操作
             ContentProviderOperation.Builder builder = ContentProviderOperation
                     .newDelete(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id));
             operationList.add(builder.build());
         }
+
         try {
+            // 执行批量操作
             ContentProviderResult[] results = resolver.applyBatch(Notes.AUTHORITY, operationList);
             if (results == null || results.length == 0 || results[0] == null) {
                 Log.d(TAG, "delete notes failed, ids:" + ids.toString());
@@ -72,31 +82,48 @@ public class DataUtils {
         return false;
     }
 
+    /**
+     * 移动笔记到目标文件夹
+     * @param resolver ContentResolver实例
+     * @param id 笔记ID
+     * @param srcFolderId 源文件夹ID
+     * @param desFolderId 目标文件夹ID
+     */
     public static void moveNoteToFoler(ContentResolver resolver, long id, long srcFolderId, long desFolderId) {
         ContentValues values = new ContentValues();
-        values.put(NoteColumns.PARENT_ID, desFolderId);
+        values.put(NoteColumns.PARENT_ID, desFolderId);  // 设置新的父文件夹ID
-        values.put(NoteColumns.ORIGIN_PARENT_ID, srcFolderId);
+        values.put(NoteColumns.ORIGIN_PARENT_ID, srcFolderId);  // 记录原始父文件夹ID
-        values.put(NoteColumns.LOCAL_MODIFIED, 1);
+        values.put(NoteColumns.LOCAL_MODIFIED, 1);  // 标记为已本地修改
+        // 更新笔记记录
         resolver.update(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id), values, null, null);
     }
 
+    /**
+     * 批量移动笔记到指定文件夹
+     * @param resolver ContentResolver实例
+     * @param ids 要移动的笔记ID集合
+     * @param folderId 目标文件夹ID
+     * @return 移动是否成功
+     */
     public static boolean batchMoveToFolder(ContentResolver resolver, HashSet<Long> ids,
-            long folderId) {
+                                            long folderId) {
         if (ids == null) {
             Log.d(TAG, "the ids is null");
             return true;
         }
 
+        // 构建批量更新操作列表
         ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
         for (long id : ids) {
             ContentProviderOperation.Builder builder = ContentProviderOperation
                     .newUpdate(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id));
-            builder.withValue(NoteColumns.PARENT_ID, folderId);
+            builder.withValue(NoteColumns.PARENT_ID, folderId);  // 更新父文件夹ID
-            builder.withValue(NoteColumns.LOCAL_MODIFIED, 1);
+            builder.withValue(NoteColumns.LOCAL_MODIFIED, 1);  // 标记为已本地修改
             operationList.add(builder.build());
         }
 
         try {
+            // 执行批量操作
             ContentProviderResult[] results = resolver.applyBatch(Notes.AUTHORITY, operationList);
             if (results == null || results.length == 0 || results[0] == null) {
                 Log.d(TAG, "delete notes failed, ids:" + ids.toString());
@@ -112,9 +139,12 @@ public class DataUtils {
     }
 
     /**
-     * Get the all folder count except system folders {@link Notes#TYPE_SYSTEM}}
+     * 获取用户文件夹数量（排除系统文件夹）
+     * @param resolver ContentResolver实例
+     * @return 用户文件夹数量
      */
     public static int getUserFolderCount(ContentResolver resolver) {
+        // 查询类型为文件夹且不在回收站中的记录数量
         Cursor cursor =resolver.query(Notes.CONTENT_NOTE_URI,
                 new String[] { "COUNT(*)" },
                 NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>?",
@@ -125,7 +155,7 @@ public class DataUtils {
         if(cursor != null) {
             if(cursor.moveToFirst()) {
                 try {
-                    count = cursor.getInt(0);
+                    count = cursor.getInt(0);  // 获取计数结果
                 } catch (IndexOutOfBoundsException e) {
                     Log.e(TAG, "get folder count failed:" + e.toString());
                 } finally {
@@ -136,7 +166,15 @@ public class DataUtils {
         return count;
     }
 
+    /**
+     * 检查指定类型和ID的笔记是否在数据库中可见（不在回收站中）
+     * @param resolver ContentResolver实例
+     * @param noteId 笔记ID
+     * @param type 笔记类型
+     * @return 是否可见
+     */
     public static boolean visibleInNoteDatabase(ContentResolver resolver, long noteId, int type) {
+        // 查询指定ID和类型，且不在回收站中的笔记
         Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId),
                 null,
                 NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER,
@@ -145,7 +183,7 @@ public class DataUtils {
 
         boolean exist = false;
         if (cursor != null) {
-            if (cursor.getCount() > 0) {
+            if (cursor.getCount() > 0) {  // 如果查询结果数量大于0，则表示存在
                 exist = true;
             }
             cursor.close();
@@ -153,7 +191,14 @@ public class DataUtils {
         return exist;
     }
 
+    /**
+     * 检查指定ID的笔记是否存在（不考虑是否在回收站中）
+     * @param resolver ContentResolver实例
+     * @param noteId 笔记ID
+     * @return 是否存在
+     */
     public static boolean existInNoteDatabase(ContentResolver resolver, long noteId) {
+        // 根据笔记ID直接查询
         Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId),
                 null, null, null, null);
 
@@ -167,7 +212,14 @@ public class DataUtils {
         return exist;
     }
 
+    /**
+     * 检查指定ID的数据项是否存在
+     * @param resolver ContentResolver实例
+     * @param dataId 数据项ID
+     * @return 是否存在
+     */
     public static boolean existInDataDatabase(ContentResolver resolver, long dataId) {
+        // 根据数据项ID直接查询
         Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, dataId),
                 null, null, null, null);
 
@@ -181,11 +233,18 @@ public class DataUtils {
         return exist;
     }
 
+    /**
+     * 检查指定的文件夹名称是否已存在（在可见文件夹中，排除回收站）
+     * @param resolver ContentResolver实例
+     * @param name 文件夹名称
+     * @return 是否存在同名文件夹
+     */
     public static boolean checkVisibleFolderName(ContentResolver resolver, String name) {
+        // 查询类型为文件夹、不在回收站中且名称匹配的记录
         Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI, null,
                 NoteColumns.TYPE + "=" + Notes.TYPE_FOLDER +
-                " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER +
+                        " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER +
-                " AND " + NoteColumns.SNIPPET + "=?",
+                        " AND " + NoteColumns.SNIPPET + "=?",
                 new String[] { name }, null);
         boolean exist = false;
         if(cursor != null) {
@@ -197,7 +256,14 @@ public class DataUtils {
         return exist;
     }
 
+    /**
+     * 获取指定文件夹中所有笔记关联的小部件属性
+     * @param resolver ContentResolver实例
+     * @param folderId 文件夹ID
+     * @return 小部件属性集合
+     */
     public static HashSet<AppWidgetAttribute> getFolderNoteWidget(ContentResolver resolver, long folderId) {
+        // 查询指定文件夹下所有笔记的小部件信息
         Cursor c = resolver.query(Notes.CONTENT_NOTE_URI,
                 new String[] { NoteColumns.WIDGET_ID, NoteColumns.WIDGET_TYPE },
                 NoteColumns.PARENT_ID + "=?",
@@ -211,8 +277,8 @@ public class DataUtils {
                 do {
                     try {
                         AppWidgetAttribute widget = new AppWidgetAttribute();
-                        widget.widgetId = c.getInt(0);
+                        widget.widgetId = c.getInt(0);      // 小部件ID
-                        widget.widgetType = c.getInt(1);
+                        widget.widgetType = c.getInt(1);    // 小部件类型
                         set.add(widget);
                     } catch (IndexOutOfBoundsException e) {
                         Log.e(TAG, e.toString());
@@ -224,7 +290,14 @@ public class DataUtils {
         return set;
     }
 
+    /**
+     * 根据笔记ID获取通话记录的电话号码
+     * @param resolver ContentResolver实例
+     * @param noteId 笔记ID
+     * @return 电话号码（如果不存在则返回空字符串）
+     */
     public static String getCallNumberByNoteId(ContentResolver resolver, long noteId) {
+        // 查询通话记录类型数据项中的电话号码
         Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI,
                 new String [] { CallNote.PHONE_NUMBER },
                 CallNote.NOTE_ID + "=? AND " + CallNote.MIME_TYPE + "=?",
@@ -233,7 +306,7 @@ public class DataUtils {
 
         if (cursor != null && cursor.moveToFirst()) {
             try {
-                return cursor.getString(0);
+                return cursor.getString(0);  // 返回电话号码
             } catch (IndexOutOfBoundsException e) {
                 Log.e(TAG, "Get call number fails " + e.toString());
             } finally {
@@ -243,18 +316,26 @@ public class DataUtils {
         return "";
     }
 
+    /**
+     * 根据电话号码和通话日期获取对应的笔记ID
+     * @param resolver ContentResolver实例
+     * @param phoneNumber 电话号码
+     * @param callDate 通话日期（时间戳）
+     * @return 笔记ID（如果不存在则返回0）
+     */
     public static long getNoteIdByPhoneNumberAndCallDate(ContentResolver resolver, String phoneNumber, long callDate) {
+        // 查询指定电话号码和通话日期的通话记录
         Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI,
                 new String [] { CallNote.NOTE_ID },
                 CallNote.CALL_DATE + "=? AND " + CallNote.MIME_TYPE + "=? AND PHONE_NUMBERS_EQUAL("
-                + CallNote.PHONE_NUMBER + ",?)",
+                        + CallNote.PHONE_NUMBER + ",?)",
                 new String [] { String.valueOf(callDate), CallNote.CONTENT_ITEM_TYPE, phoneNumber },
                 null);
 
         if (cursor != null) {
             if (cursor.moveToFirst()) {
                 try {
-                    return cursor.getLong(0);
+                    return cursor.getLong(0);  // 返回笔记ID
                 } catch (IndexOutOfBoundsException e) {
                     Log.e(TAG, "Get call note id fails " + e.toString());
                 }
@@ -264,7 +345,15 @@ public class DataUtils {
         return 0;
     }
 
+    /**
+     * 根据笔记ID获取笔记摘要
+     * @param resolver ContentResolver实例
+     * @param noteId 笔记ID
+     * @return 笔记摘要
+     * @throws IllegalArgumentException 如果笔记不存在
+     */
     public static String getSnippetById(ContentResolver resolver, long noteId) {
+        // 查询指定笔记的摘要
         Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI,
                 new String [] { NoteColumns.SNIPPET },
                 NoteColumns.ID + "=?",
@@ -274,7 +363,7 @@ public class DataUtils {
         if (cursor != null) {
             String snippet = "";
             if (cursor.moveToFirst()) {
-                snippet = cursor.getString(0);
+                snippet = cursor.getString(0);  // 获取摘要内容
             }
             cursor.close();
             return snippet;
@@ -282,14 +371,19 @@ public class DataUtils {
         throw new IllegalArgumentException("Note is not found with id: " + noteId);
     }
 
+    /**
+     * 格式化摘要：去除首尾空格，只保留第一行内容
+     * @param snippet 原始摘要
+     * @return 格式化后的摘要
+     */
     public static String getFormattedSnippet(String snippet) {
         if (snippet != null) {
-            snippet = snippet.trim();
+            snippet = snippet.trim();  // 去除首尾空格
-            int index = snippet.indexOf('\n');
+            int index = snippet.indexOf('\n');  // 查找换行符位置
             if (index != -1) {
-                snippet = snippet.substring(0, index);
+                snippet = snippet.substring(0, index);  // 只保留第一行
             }
         }
         return snippet;
     }
-}
+}

src/notes/tool/GTaskStringUtils.java

@@ -17,97 +17,72 @@
 package net.micode.notes.tool;
 
 public class GTaskStringUtils {
-
+    // GTasks API JSON字段常量定义
-    public final static String GTASK_JSON_ACTION_ID = "action_id";
+
-
+    // 动作相关的字段
-    public final static String GTASK_JSON_ACTION_LIST = "action_list";
+    public final static String GTASK_JSON_ACTION_ID = "action_id";          // 动作ID标识
-
+    public final static String GTASK_JSON_ACTION_LIST = "action_list";      // 动作列表
-    public final static String GTASK_JSON_ACTION_TYPE = "action_type";
+    public final static String GTASK_JSON_ACTION_TYPE = "action_type";      // 动作类型
-
+
-    public final static String GTASK_JSON_ACTION_TYPE_CREATE = "create";
+    // 动作类型枚举
-
+    public final static String GTASK_JSON_ACTION_TYPE_CREATE = "create";    // 创建动作
-    public final static String GTASK_JSON_ACTION_TYPE_GETALL = "get_all";
+    public final static String GTASK_JSON_ACTION_TYPE_GETALL = "get_all";   // 获取所有数据动作
-
+    public final static String GTASK_JSON_ACTION_TYPE_MOVE = "move";        // 移动动作
-    public final static String GTASK_JSON_ACTION_TYPE_MOVE = "move";
+    public final static String GTASK_JSON_ACTION_TYPE_UPDATE = "update";    // 更新动作
-
+
-    public final static String GTASK_JSON_ACTION_TYPE_UPDATE = "update";
+    // 实体相关字段
-
+    public final static String GTASK_JSON_CREATOR_ID = "creator_id";        // 创建者ID
-    public final static String GTASK_JSON_CREATOR_ID = "creator_id";
+    public final static String GTASK_JSON_CHILD_ENTITY = "child_entity";    // 子实体
-
+    public final static String GTASK_JSON_CLIENT_VERSION = "client_version"; // 客户端版本号
-    public final static String GTASK_JSON_CHILD_ENTITY = "child_entity";
+    public final static String GTASK_JSON_COMPLETED = "completed";          // 完成状态
-
+    public final static String GTASK_JSON_CURRENT_LIST_ID = "current_list_id"; // 当前列表ID
-    public final static String GTASK_JSON_CLIENT_VERSION = "client_version";
+    public final static String GTASK_JSON_DEFAULT_LIST_ID = "default_list_id"; // 默认列表ID
-
+    public final static String GTASK_JSON_DELETED = "deleted";              // 删除状态标记
-    public final static String GTASK_JSON_COMPLETED = "completed";
+    public final static String GTASK_JSON_DEST_LIST = "dest_list";          // 目标列表
-
+    public final static String GTASK_JSON_DEST_PARENT = "dest_parent";      // 目标父节点
-    public final static String GTASK_JSON_CURRENT_LIST_ID = "current_list_id";
+    public final static String GTASK_JSON_DEST_PARENT_TYPE = "dest_parent_type"; // 目标父节点类型
-
+    public final static String GTASK_JSON_ENTITY_DELTA = "entity_delta";    // 实体增量变化
-    public final static String GTASK_JSON_DEFAULT_LIST_ID = "default_list_id";
+    public final static String GTASK_JSON_ENTITY_TYPE = "entity_type";      // 实体类型
-
+    public final static String GTASK_JSON_GET_DELETED = "get_deleted";      // 是否获取已删除项
-    public final static String GTASK_JSON_DELETED = "deleted";
+    public final static String GTASK_JSON_ID = "id";                        // 实体ID
-
+    public final static String GTASK_JSON_INDEX = "index";                  // 索引位置
-    public final static String GTASK_JSON_DEST_LIST = "dest_list";
+    public final static String GTASK_JSON_LAST_MODIFIED = "last_modified";  // 最后修改时间
-
+    public final static String GTASK_JSON_LATEST_SYNC_POINT = "latest_sync_point"; // 最新同步点
-    public final static String GTASK_JSON_DEST_PARENT = "dest_parent";
+
-
+    // 列表相关字段
-    public final static String GTASK_JSON_DEST_PARENT_TYPE = "dest_parent_type";
+    public final static String GTASK_JSON_LIST_ID = "list_id";              // 列表ID
-
+    public final static String GTASK_JSON_LISTS = "lists";                  // 列表集合
-    public final static String GTASK_JSON_ENTITY_DELTA = "entity_delta";
+    public final static String GTASK_JSON_NAME = "name";                    // 实体名称
-
+    public final static String GTASK_JSON_NEW_ID = "new_id";                // 新ID（用于ID映射）
-    public final static String GTASK_JSON_ENTITY_TYPE = "entity_type";
+    public final static String GTASK_JSON_NOTES = "notes";                  // 笔记集合
-
+
-    public final static String GTASK_JSON_GET_DELETED = "get_deleted";
+    // 层级关系字段
-
+    public final static String GTASK_JSON_PARENT_ID = "parent_id";          // 父节点ID
-    public final static String GTASK_JSON_ID = "id";
+    public final static String GTASK_JSON_PRIOR_SIBLING_ID = "prior_sibling_id"; // 前一个兄弟节点ID
-
+
-    public final static String GTASK_JSON_INDEX = "index";
+    // 响应相关字段
-
+    public final static String GTASK_JSON_RESULTS = "results";              // 操作结果集
-    public final static String GTASK_JSON_LAST_MODIFIED = "last_modified";
+    public final static String GTASK_JSON_SOURCE_LIST = "source_list";      // 源列表
-
+
-    public final static String GTASK_JSON_LATEST_SYNC_POINT = "latest_sync_point";
+    // 任务相关字段
-
+    public final static String GTASK_JSON_TASKS = "tasks";                  // 任务集合
-    public final static String GTASK_JSON_LIST_ID = "list_id";
+    public final static String GTASK_JSON_TYPE = "type";                    // 实体类型标识
-
+
-    public final static String GTASK_JSON_LISTS = "lists";
+    // 实体类型常量
-
+    public final static String GTASK_JSON_TYPE_GROUP = "GROUP";             // 分组/文件夹类型
-    public final static String GTASK_JSON_NAME = "name";
+    public final static String GTASK_JSON_TYPE_TASK = "TASK";               // 任务类型
-
+
-    public final static String GTASK_JSON_NEW_ID = "new_id";
+    public final static String GTASK_JSON_USER = "user";                    // 用户信息
-
+
-    public final static String GTASK_JSON_NOTES = "notes";
+    // 小米便签同步相关的文件夹命名前缀和常量
-
+    public final static String MIUI_FOLDER_PREFFIX = "[MIUI_Notes]";        // 小米便签文件夹前缀
-    public final static String GTASK_JSON_PARENT_ID = "parent_id";
+    public final static String FOLDER_DEFAULT = "Default";                  // 默认文件夹名称
-
+    public final static String FOLDER_CALL_NOTE = "Call_Note";              // 通话记录文件夹名称
-    public final static String GTASK_JSON_PRIOR_SIBLING_ID = "prior_sibling_id";
+    public final static String FOLDER_META = "METADATA";                    // 元数据文件夹名称
-
+
-    public final static String GTASK_JSON_RESULTS = "results";
+    // 元数据相关的常量
-
+    public final static String META_HEAD_GTASK_ID = "meta_gid";             // Google Task ID的元数据头
-    public final static String GTASK_JSON_SOURCE_LIST = "source_list";
+    public final static String META_HEAD_NOTE = "meta_note";                // 笔记元数据头
-
+    public final static String META_HEAD_DATA = "meta_data";                // 数据元数据头
-    public final static String GTASK_JSON_TASKS = "tasks";
+    public final static String META_NOTE_NAME = "[META INFO] DON'T UPDATE AND DELETE"; // 元数据笔记名称（用户不应修改或删除）
-
+}
-    public final static String GTASK_JSON_TYPE = "type";
-
-    public final static String GTASK_JSON_TYPE_GROUP = "GROUP";
-
-    public final static String GTASK_JSON_TYPE_TASK = "TASK";
-
-    public final static String GTASK_JSON_USER = "user";
-
-    public final static String MIUI_FOLDER_PREFFIX = "[MIUI_Notes]";
-
-    public final static String FOLDER_DEFAULT = "Default";
-
-    public final static String FOLDER_CALL_NOTE = "Call_Note";
-
-    public final static String FOLDER_META = "METADATA";
-
-    public final static String META_HEAD_GTASK_ID = "meta_gid";
-
-    public final static String META_HEAD_NOTE = "meta_note";
-
-    public final static String META_HEAD_DATA = "meta_data";
-
-    public final static String META_NOTE_NAME = "[META INFO] DON'T UPDATE AND DELETE";
-
-}

src/notes/tool/ResourceParser.java

@@ -23,150 +23,236 @@ import net.micode.notes.R;
 import net.micode.notes.ui.NotesPreferenceActivity;
 
 public class ResourceParser {
+    // 笔记背景颜色常量定义
+    public static final int YELLOW           = 0;  // 黄色背景
+    public static final int BLUE             = 1;  // 蓝色背景
+    public static final int WHITE            = 2;  // 白色背景
+    public static final int GREEN            = 3;  // 绿色背景
+    public static final int RED              = 4;  // 红色背景
 
-    public static final int YELLOW           = 0;
+    public static final int BG_DEFAULT_COLOR = YELLOW;  // 默认背景颜色（黄色）
-    public static final int BLUE             = 1;
-    public static final int WHITE            = 2;
-    public static final int GREEN            = 3;
-    public static final int RED              = 4;
 
-    public static final int BG_DEFAULT_COLOR = YELLOW;
+    // 字体大小常量定义
+    public static final int TEXT_SMALL       = 0;  // 小号字体
+    public static final int TEXT_MEDIUM      = 1;  // 中号字体
+    public static final int TEXT_LARGE       = 2;  // 大号字体
+    public static final int TEXT_SUPER       = 3;  // 超大号字体
 
-    public static final int TEXT_SMALL       = 0;
+    public static final int BG_DEFAULT_FONT_SIZE = TEXT_MEDIUM;  // 默认字体大小（中号）
-    public static final int TEXT_MEDIUM      = 1;
-    public static final int TEXT_LARGE       = 2;
-    public static final int TEXT_SUPER       = 3;
-
-    public static final int BG_DEFAULT_FONT_SIZE = TEXT_MEDIUM;
 
+    /**
+     * 内部类：笔记编辑界面的背景资源
+     * 用于获取不同颜色对应的编辑器和标题栏背景资源ID
+     */
     public static class NoteBgResources {
+        // 编辑器背景资源数组（与颜色常量顺序一致）
         private final static int [] BG_EDIT_RESOURCES = new int [] {
-            R.drawable.edit_yellow,
+                R.drawable.edit_yellow,    // 黄色编辑器背景
-            R.drawable.edit_blue,
+                R.drawable.edit_blue,      // 蓝色编辑器背景
-            R.drawable.edit_white,
+                R.drawable.edit_white,     // 白色编辑器背景
-            R.drawable.edit_green,
+                R.drawable.edit_green,     // 绿色编辑器背景
-            R.drawable.edit_red
+                R.drawable.edit_red        // 红色编辑器背景
         };
 
+        // 编辑器标题栏背景资源数组（与颜色常量顺序一致）
         private final static int [] BG_EDIT_TITLE_RESOURCES = new int [] {
-            R.drawable.edit_title_yellow,
+                R.drawable.edit_title_yellow,  // 黄色标题背景
-            R.drawable.edit_title_blue,
+                R.drawable.edit_title_blue,    // 蓝色标题背景
-            R.drawable.edit_title_white,
+                R.drawable.edit_title_white,   // 白色标题背景
-            R.drawable.edit_title_green,
+                R.drawable.edit_title_green,   // 绿色标题背景
-            R.drawable.edit_title_red
+                R.drawable.edit_title_red      // 红色标题背景
         };
 
+        /**
+         * 获取笔记编辑器背景资源ID
+         * @param id 颜色ID（YELLOW, BLUE等）
+         * @return 对应的Drawable资源ID
+         */
         public static int getNoteBgResource(int id) {
             return BG_EDIT_RESOURCES[id];
         }
 
+        /**
+         * 获取笔记标题栏背景资源ID
+         * @param id 颜色ID（YELLOW, BLUE等）
+         * @return 对应的Drawable资源ID
+         */
         public static int getNoteTitleBgResource(int id) {
             return BG_EDIT_TITLE_RESOURCES[id];
         }
     }
 
+    /**
+     * 获取默认背景颜色ID
+     * 根据用户偏好设置决定使用随机颜色还是默认颜色
+     * @param context 上下文对象
+     * @return 颜色ID
+     */
     public static int getDefaultBgId(Context context) {
+        // 检查用户是否启用了随机背景颜色功能
         if (PreferenceManager.getDefaultSharedPreferences(context).getBoolean(
                 NotesPreferenceActivity.PREFERENCE_SET_BG_COLOR_KEY, false)) {
+            // 随机选择一个背景颜色
             return (int) (Math.random() * NoteBgResources.BG_EDIT_RESOURCES.length);
         } else {
+            // 使用默认的背景颜色（黄色）
             return BG_DEFAULT_COLOR;
         }
     }
 
+    /**
+     * 内部类：笔记列表项的背景资源
+     * 用于获取列表项在不同位置（首项、中间项、末项、单一项）的背景资源ID
+     */
     public static class NoteItemBgResources {
+        // 列表首项背景资源数组
         private final static int [] BG_FIRST_RESOURCES = new int [] {
-            R.drawable.list_yellow_up,
+                R.drawable.list_yellow_up,    // 黄色列表首项背景
-            R.drawable.list_blue_up,
+                R.drawable.list_blue_up,      // 蓝色列表首项背景
-            R.drawable.list_white_up,
+                R.drawable.list_white_up,     // 白色列表首项背景
-            R.drawable.list_green_up,
+                R.drawable.list_green_up,     // 绿色列表首项背景
-            R.drawable.list_red_up
+                R.drawable.list_red_up        // 红色列表首项背景
         };
 
+        // 列表中间项背景资源数组
         private final static int [] BG_NORMAL_RESOURCES = new int [] {
-            R.drawable.list_yellow_middle,
+                R.drawable.list_yellow_middle,  // 黄色列表中间项背景
-            R.drawable.list_blue_middle,
+                R.drawable.list_blue_middle,    // 蓝色列表中间项背景
-            R.drawable.list_white_middle,
+                R.drawable.list_white_middle,   // 白色列表中间项背景
-            R.drawable.list_green_middle,
+                R.drawable.list_green_middle,   // 绿色列表中间项背景
-            R.drawable.list_red_middle
+                R.drawable.list_red_middle      // 红色列表中间项背景
         };
 
+        // 列表末项背景资源数组
         private final static int [] BG_LAST_RESOURCES = new int [] {
-            R.drawable.list_yellow_down,
+                R.drawable.list_yellow_down,    // 黄色列表末项背景
-            R.drawable.list_blue_down,
+                R.drawable.list_blue_down,      // 蓝色列表末项背景
-            R.drawable.list_white_down,
+                R.drawable.list_white_down,     // 白色列表末项背景
-            R.drawable.list_green_down,
+                R.drawable.list_green_down,     // 绿色列表末项背景
-            R.drawable.list_red_down,
+                R.drawable.list_red_down,       // 红色列表末项背景
         };
 
+        // 列表单项（只有一个项）背景资源数组
         private final static int [] BG_SINGLE_RESOURCES = new int [] {
-            R.drawable.list_yellow_single,
+                R.drawable.list_yellow_single,  // 黄色列表单项背景
-            R.drawable.list_blue_single,
+                R.drawable.list_blue_single,    // 蓝色列表单项背景
-            R.drawable.list_white_single,
+                R.drawable.list_white_single,   // 白色列表单项背景
-            R.drawable.list_green_single,
+                R.drawable.list_green_single,   // 绿色列表单项背景
-            R.drawable.list_red_single
+                R.drawable.list_red_single      // 红色列表单项背景
         };
 
+        /**
+         * 获取列表首项背景资源ID
+         * @param id 颜色ID
+         * @return 对应的Drawable资源ID
+         */
         public static int getNoteBgFirstRes(int id) {
             return BG_FIRST_RESOURCES[id];
         }
 
+        /**
+         * 获取列表末项背景资源ID
+         * @param id 颜色ID
+         * @return 对应的Drawable资源ID
+         */
         public static int getNoteBgLastRes(int id) {
             return BG_LAST_RESOURCES[id];
         }
 
+        /**
+         * 获取列表单项背景资源ID（当列表只有一项时使用）
+         * @param id 颜色ID
+         * @return 对应的Drawable资源ID
+         */
         public static int getNoteBgSingleRes(int id) {
             return BG_SINGLE_RESOURCES[id];
         }
 
+        /**
+         * 获取列表中间项背景资源ID
+         * @param id 颜色ID
+         * @return 对应的Drawable资源ID
+         */
         public static int getNoteBgNormalRes(int id) {
             return BG_NORMAL_RESOURCES[id];
         }
 
+        /**
+         * 获取文件夹图标的背景资源ID（文件夹使用统一的图标）
+         * @return 文件夹Drawable资源ID
+         */
         public static int getFolderBgRes() {
             return R.drawable.list_folder;
         }
     }
 
+    /**
+     * 内部类：桌面小部件的背景资源
+     * 用于获取不同尺寸小部件的背景资源ID
+     */
     public static class WidgetBgResources {
+        // 2x小部件背景资源数组
         private final static int [] BG_2X_RESOURCES = new int [] {
-            R.drawable.widget_2x_yellow,
+                R.drawable.widget_2x_yellow,  // 黄色2x小部件背景
-            R.drawable.widget_2x_blue,
+                R.drawable.widget_2x_blue,    // 蓝色2x小部件背景
-            R.drawable.widget_2x_white,
+                R.drawable.widget_2x_white,   // 白色2x小部件背景
-            R.drawable.widget_2x_green,
+                R.drawable.widget_2x_green,   // 绿色2x小部件背景
-            R.drawable.widget_2x_red,
+                R.drawable.widget_2x_red,     // 红色2x小部件背景
         };
 
+        /**
+         * 获取2x小部件背景资源ID
+         * @param id 颜色ID
+         * @return 对应的Drawable资源ID
+         */
         public static int getWidget2xBgResource(int id) {
             return BG_2X_RESOURCES[id];
         }
 
+        // 4x小部件背景资源数组
         private final static int [] BG_4X_RESOURCES = new int [] {
-            R.drawable.widget_4x_yellow,
+                R.drawable.widget_4x_yellow,  // 黄色4x小部件背景
-            R.drawable.widget_4x_blue,
+                R.drawable.widget_4x_blue,    // 蓝色4x小部件背景
-            R.drawable.widget_4x_white,
+                R.drawable.widget_4x_white,   // 白色4x小部件背景
-            R.drawable.widget_4x_green,
+                R.drawable.widget_4x_green,   // 绿色4x小部件背景
-            R.drawable.widget_4x_red
+                R.drawable.widget_4x_red      // 红色4x小部件背景
         };
 
+        /**
+         * 获取4x小部件背景资源ID
+         * @param id 颜色ID
+         * @return 对应的Drawable资源ID
+         */
         public static int getWidget4xBgResource(int id) {
             return BG_4X_RESOURCES[id];
         }
     }
 
+    /**
+     * 内部类：文字外观样式资源
+     * 用于获取不同字体大小对应的样式资源ID
+     */
     public static class TextAppearanceResources {
+        // 文字外观样式资源数组
         private final static int [] TEXTAPPEARANCE_RESOURCES = new int [] {
-            R.style.TextAppearanceNormal,
+                R.style.TextAppearanceNormal,  // 正常大小文字样式
-            R.style.TextAppearanceMedium,
+                R.style.TextAppearanceMedium,  // 中等大小文字样式
-            R.style.TextAppearanceLarge,
+                R.style.TextAppearanceLarge,   // 大号文字样式
-            R.style.TextAppearanceSuper
+                R.style.TextAppearanceSuper    // 超大号文字样式
         };
 
+        /**
+         * 获取文字外观样式资源ID
+         * @param id 字体大小ID（TEXT_SMALL, TEXT_MEDIUM等）
+         * @return 对应的样式资源ID
+         *
+         * 注意：这里有一个修复bug的hack方法。因为在SharedPreferences中可能存储了
+         * 超出资源数组范围的ID，这种情况下返回默认字体大小ID
+         */
         public static int getTexAppearanceResource(int id) {
             /**
-             * HACKME: Fix bug of store the resource id in shared preference.
+             * HACKME: 修复在SharedPreferences中存储资源ID的bug。
-             * The id may larger than the length of resources, in this case,
+             * 当ID大于等于资源数组长度时，返回默认字体大小ID
-             * return the {@link ResourceParser#BG_DEFAULT_FONT_SIZE}
              */
             if (id >= TEXTAPPEARANCE_RESOURCES.length) {
                 return BG_DEFAULT_FONT_SIZE;
@@ -174,8 +260,12 @@ public class ResourceParser {
             return TEXTAPPEARANCE_RESOURCES[id];
         }
 
+        /**
+         * 获取文字外观样式资源的数量
+         * @return 可用的文字外观样式数量
+         */
         public static int getResourcesSize() {
             return TEXTAPPEARANCE_RESOURCES.length;
         }
     }
-}
+}

src/notes/ui/AlarmAlertActivity.java

@@ -39,21 +39,27 @@ import net.micode.notes.tool.DataUtils;
 
 import java.io.IOException;
 
-
+/**
+ * 闹钟提醒Activity - 当笔记的闹钟触发时显示提醒界面
+ * 实现DialogInterface.OnClickListener和OnDismissListener接口，处理对话框事件
+ */
 public class AlarmAlertActivity extends Activity implements OnClickListener, OnDismissListener {
-    private long mNoteId;
+    private long mNoteId;        // 触发闹钟的笔记ID
-    private String mSnippet;
+    private String mSnippet;     // 笔记内容摘要
-    private static final int SNIPPET_PREW_MAX_LEN = 60;
+    private static final int SNIPPET_PREW_MAX_LEN = 60;  // 摘要最大显示长度
-    MediaPlayer mPlayer;
+    MediaPlayer mPlayer;         // 媒体播放器，用于播放闹钟声音
 
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
+        // 移除标题栏
         requestWindowFeature(Window.FEATURE_NO_TITLE);
 
+        // 获取窗口并设置标志，使Activity在锁屏状态下也能显示
         final Window win = getWindow();
         win.addFlags(WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED);
 
+        // 如果屏幕未亮，则设置更多标志来唤醒屏幕
         if (!isScreenOn()) {
             win.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON
                     | WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON
@@ -61,98 +67,143 @@ public class AlarmAlertActivity extends Activity implements OnClickListener, OnD
                     | WindowManager.LayoutParams.FLAG_LAYOUT_INSET_DECOR);
         }
 
+        // 从Intent中获取笔记ID和内容摘要
         Intent intent = getIntent();
 
         try {
+            // 从Intent的URI中解析出笔记ID（URI格式：content://xxx/note/笔记ID）
             mNoteId = Long.valueOf(intent.getData().getPathSegments().get(1));
+            // 通过笔记ID从数据库获取笔记摘要
             mSnippet = DataUtils.getSnippetById(this.getContentResolver(), mNoteId);
+            // 如果摘要过长，截取前60个字符并添加省略号
             mSnippet = mSnippet.length() > SNIPPET_PREW_MAX_LEN ? mSnippet.substring(0,
                     SNIPPET_PREW_MAX_LEN) + getResources().getString(R.string.notelist_string_info)
                     : mSnippet;
         } catch (IllegalArgumentException e) {
+            // 如果解析失败，打印异常并返回（Activity将结束）
             e.printStackTrace();
             return;
         }
 
+        // 初始化媒体播放器
         mPlayer = new MediaPlayer();
+        // 检查笔记是否仍然存在且可见（未被删除或移到回收站）
         if (DataUtils.visibleInNoteDatabase(getContentResolver(), mNoteId, Notes.TYPE_NOTE)) {
-            showActionDialog();
+            showActionDialog();  // 显示提醒对话框
-            playAlarmSound();
+            playAlarmSound();    // 播放闹钟声音
         } else {
+            // 如果笔记已不存在，直接结束Activity
             finish();
         }
     }
 
+    /**
+     * 检查屏幕是否亮着
+     * @return true表示屏幕亮着，false表示屏幕关闭
+     */
     private boolean isScreenOn() {
         PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE);
         return pm.isScreenOn();
     }
 
+    /**
+     * 播放闹钟声音
+     * 使用系统默认的闹钟铃声
+     */
     private void playAlarmSound() {
+        // 获取系统默认的闹钟铃声URI
         Uri url = RingtoneManager.getActualDefaultRingtoneUri(this, RingtoneManager.TYPE_ALARM);
 
+        // 获取当前静音模式影响的音频流设置
         int silentModeStreams = Settings.System.getInt(getContentResolver(),
                 Settings.System.MODE_RINGER_STREAMS_AFFECTED, 0);
 
+        // 如果静音模式影响闹钟音频流，则使用静音模式的设置
         if ((silentModeStreams & (1 << AudioManager.STREAM_ALARM)) != 0) {
             mPlayer.setAudioStreamType(silentModeStreams);
         } else {
+            // 否则使用闹钟音频流
             mPlayer.setAudioStreamType(AudioManager.STREAM_ALARM);
         }
+
         try {
+            // 设置数据源并准备播放
             mPlayer.setDataSource(this, url);
             mPlayer.prepare();
-            mPlayer.setLooping(true);
+            mPlayer.setLooping(true);  // 设置为循环播放
-            mPlayer.start();
+            mPlayer.start();           // 开始播放
         } catch (IllegalArgumentException e) {
-            // TODO Auto-generated catch block
+            // TODO: 异常处理，自动生成的catch块
             e.printStackTrace();
         } catch (SecurityException e) {
-            // TODO Auto-generated catch block
+            // TODO: 异常处理，自动生成的catch块
             e.printStackTrace();
         } catch (IllegalStateException e) {
-            // TODO Auto-generated catch block
+            // TODO: 异常处理，自动生成的catch块
             e.printStackTrace();
         } catch (IOException e) {
-            // TODO Auto-generated catch block
+            // TODO: 异常处理，自动生成的catch块
             e.printStackTrace();
         }
     }
 
+    /**
+     * 显示操作对话框，包含笔记摘要和操作按钮
+     */
     private void showActionDialog() {
         AlertDialog.Builder dialog = new AlertDialog.Builder(this);
-        dialog.setTitle(R.string.app_name);
+        dialog.setTitle(R.string.app_name);      // 设置对话框标题为应用名称
-        dialog.setMessage(mSnippet);
+        dialog.setMessage(mSnippet);              // 设置对话框内容为笔记摘要
+
+        // 确定按钮 - 关闭提醒
         dialog.setPositiveButton(R.string.notealert_ok, this);
+
+        // 如果屏幕已亮，显示"进入"按钮，用于打开笔记编辑页面
         if (isScreenOn()) {
             dialog.setNegativeButton(R.string.notealert_enter, this);
         }
+
+        // 显示对话框并设置关闭监听器
         dialog.show().setOnDismissListener(this);
     }
 
+    /**
+     * 对话框按钮点击事件处理
+     * @param dialog 触发事件的对话框
+     * @param which 被点击的按钮标识
+     */
     public void onClick(DialogInterface dialog, int which) {
         switch (which) {
             case DialogInterface.BUTTON_NEGATIVE:
+                // "进入"按钮：打开笔记编辑页面
                 Intent intent = new Intent(this, NoteEditActivity.class);
                 intent.setAction(Intent.ACTION_VIEW);
-                intent.putExtra(Intent.EXTRA_UID, mNoteId);
+                intent.putExtra(Intent.EXTRA_UID, mNoteId);  // 传递笔记ID
                 startActivity(intent);
                 break;
             default:
+                // "确定"按钮或其他按钮：不做特殊处理，对话框会自动关闭
                 break;
         }
     }
 
+    /**
+     * 对话框关闭事件处理
+     * @param dialog 被关闭的对话框
+     */
     public void onDismiss(DialogInterface dialog) {
-        stopAlarmSound();
+        stopAlarmSound();  // 停止播放闹钟声音
-        finish();
+        finish();          // 结束Activity
     }
 
+    /**
+     * 停止播放闹钟声音并释放资源
+     */
     private void stopAlarmSound() {
         if (mPlayer != null) {
-            mPlayer.stop();
+            mPlayer.stop();     // 停止播放
-            mPlayer.release();
+            mPlayer.release();  // 释放媒体播放器资源
-            mPlayer = null;
+            mPlayer = null;     // 置空引用
         }
     }
-}
+}

src/notes/ui/AlarmInitReceiver.java

@@ -27,39 +27,64 @@ import android.database.Cursor;
 import net.micode.notes.data.Notes;
 import net.micode.notes.data.Notes.NoteColumns;
 
-
+/**
+ * 闹钟初始化接收器 - 在设备启动或应用安装后重新设置所有未触发的闹钟
+ * 这是一个BroadcastReceiver，通常响应系统启动完成的广播
+ */
 public class AlarmInitReceiver extends BroadcastReceiver {
-
+    // 数据库查询字段投影，只需要笔记ID和提醒时间
     private static final String [] PROJECTION = new String [] {
-        NoteColumns.ID,
+            NoteColumns.ID,           // 笔记ID
-        NoteColumns.ALERTED_DATE
+            NoteColumns.ALERTED_DATE  // 闹钟提醒时间
     };
 
-    private static final int COLUMN_ID                = 0;
+    private static final int COLUMN_ID                = 0;  // 笔记ID在查询结果中的列索引
-    private static final int COLUMN_ALERTED_DATE      = 1;
+    private static final int COLUMN_ALERTED_DATE      = 1;  // 提醒时间在查询结果中的列索引
 
     @Override
     public void onReceive(Context context, Intent intent) {
-        long currentDate = System.currentTimeMillis();
+        long currentDate = System.currentTimeMillis();  // 获取当前系统时间
+
+        // 查询所有未过期的闹钟笔记：
+        // 1. 提醒时间大于当前时间（ALERTED_DATE > ?）
+        // 2. 笔记类型为普通笔记（TYPE = Notes.TYPE_NOTE）
         Cursor c = context.getContentResolver().query(Notes.CONTENT_NOTE_URI,
                 PROJECTION,
                 NoteColumns.ALERTED_DATE + ">? AND " + NoteColumns.TYPE + "=" + Notes.TYPE_NOTE,
-                new String[] { String.valueOf(currentDate) },
+                new String[] { String.valueOf(currentDate) },  // 将当前时间作为参数传入
                 null);
 
         if (c != null) {
             if (c.moveToFirst()) {
                 do {
+                    // 获取该笔记的提醒时间
                     long alertDate = c.getLong(COLUMN_ALERTED_DATE);
+
+                    // 创建指向AlarmReceiver的Intent，用于在闹钟时间触发时发送广播
                     Intent sender = new Intent(context, AlarmReceiver.class);
+                    // 将笔记URI附加到Intent中，这样AlarmReceiver就能知道是哪个笔记的闹钟
                     sender.setData(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, c.getLong(COLUMN_ID)));
+
+                    // 创建PendingIntent，用于在指定时间触发广播
                     PendingIntent pendingIntent = PendingIntent.getBroadcast(context, 0, sender, 0);
+
+                    // 获取系统AlarmManager服务
                     AlarmManager alermManager = (AlarmManager) context
                             .getSystemService(Context.ALARM_SERVICE);
+
+                    // 设置闹钟：
+                    // 1. 使用RTC_WAKEUP类型，即使设备休眠也会唤醒CPU并发送PendingIntent
+                    // 2. 在alertDate时间触发
+                    // 3. 触发pendingIntent，即发送广播给AlarmReceiver
                     alermManager.set(AlarmManager.RTC_WAKEUP, alertDate, pendingIntent);
-                } while (c.moveToNext());
+
+                } while (c.moveToNext());  // 遍历所有查询结果
             }
-            c.close();
+            c.close();  // 关闭Cursor释放资源
         }
+
+        // 注意：这个方法没有处理重复闹钟的情况
+        // 当设备重启后，所有之前设置的AlarmManager闹钟都会被清除
+        // 所以需要这个Receiver来重新设置所有未触发的闹钟
     }
-}
+}

src/notes/ui/AlarmReceiver.java

@@ -20,11 +20,28 @@ import android.content.BroadcastReceiver;
 import android.content.Context;
 import android.content.Intent;
 
+/**
+ * 闹钟接收器 - 当AlarmManager设置的闹钟时间到达时，接收系统广播
+ * 这是闹钟系统的中间组件，负责将系统广播转发到AlarmAlertActivity
+ */
 public class AlarmReceiver extends BroadcastReceiver {
+
     @Override
     public void onReceive(Context context, Intent intent) {
+        // 修改Intent的目标类为AlarmAlertActivity
+        // 这样当闹钟触发时，会启动AlarmAlertActivity显示提醒界面
         intent.setClass(context, AlarmAlertActivity.class);
+
+        // 添加FLAG_ACTIVITY_NEW_TASK标志
+        // 因为BroadcastReceiver不是Activity上下文，需要新任务栈启动Activity
         intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+
+        // 启动AlarmAlertActivity
         context.startActivity(intent);
+
+        // 注意：这个Intent中已经包含了笔记的URI数据
+        // 这个URI是在AlarmInitReceiver中设置的：
+        // sender.setData(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, c.getLong(COLUMN_ID)))
+        // 所以AlarmAlertActivity可以通过getIntent().getData()获取到笔记信息
     }
-}
+}

src/notes/ui/DateTimePicker.java

@@ -21,92 +21,121 @@ import java.util.Calendar;
 
 import net.micode.notes.R;
 
-
 import android.content.Context;
 import android.text.format.DateFormat;
 import android.view.View;
 import android.widget.FrameLayout;
 import android.widget.NumberPicker;
 
+/**
+ * 自定义日期时间选择器控件
+ * 继承自FrameLayout，包含日期、小时、分钟和AM/PM四个选择器
+ */
 public class DateTimePicker extends FrameLayout {
+    // 常量定义
+    private static final boolean DEFAULT_ENABLE_STATE = true;  // 默认启用状态
 
-    private static final boolean DEFAULT_ENABLE_STATE = true;
+    // 时间相关常量
+    private static final int HOURS_IN_HALF_DAY = 12;      // 半天的小时数（12小时制）
+    private static final int HOURS_IN_ALL_DAY = 24;       // 全天的小时数（24小时制）
+    private static final int DAYS_IN_ALL_WEEK = 7;        // 一周的天数（用于显示一周的日期）
 
-    private static final int HOURS_IN_HALF_DAY = 12;
+    // NumberPicker的最小最大值常量
-    private static final int HOURS_IN_ALL_DAY = 24;
+    private static final int DATE_SPINNER_MIN_VAL = 0;    // 日期选择器最小值
-    private static final int DAYS_IN_ALL_WEEK = 7;
+    private static final int DATE_SPINNER_MAX_VAL = DAYS_IN_ALL_WEEK - 1;  // 日期选择器最大值
-    private static final int DATE_SPINNER_MIN_VAL = 0;
+
-    private static final int DATE_SPINNER_MAX_VAL = DAYS_IN_ALL_WEEK - 1;
+    // 24小时制下的小时选择器范围
     private static final int HOUR_SPINNER_MIN_VAL_24_HOUR_VIEW = 0;
     private static final int HOUR_SPINNER_MAX_VAL_24_HOUR_VIEW = 23;
+
+    // 12小时制下的小时选择器范围
     private static final int HOUR_SPINNER_MIN_VAL_12_HOUR_VIEW = 1;
     private static final int HOUR_SPINNER_MAX_VAL_12_HOUR_VIEW = 12;
+
+    // 分钟选择器范围
     private static final int MINUT_SPINNER_MIN_VAL = 0;
     private static final int MINUT_SPINNER_MAX_VAL = 59;
+
+    // AM/PM选择器范围
     private static final int AMPM_SPINNER_MIN_VAL = 0;
     private static final int AMPM_SPINNER_MAX_VAL = 1;
 
-    private final NumberPicker mDateSpinner;
+    // 控件引用
-    private final NumberPicker mHourSpinner;
+    private final NumberPicker mDateSpinner;    // 日期选择器
-    private final NumberPicker mMinuteSpinner;
+    private final NumberPicker mHourSpinner;    // 小时选择器
-    private final NumberPicker mAmPmSpinner;
+    private final NumberPicker mMinuteSpinner;  // 分钟选择器
-    private Calendar mDate;
+    private final NumberPicker mAmPmSpinner;    // AM/PM选择器
-
-    private String[] mDateDisplayValues = new String[DAYS_IN_ALL_WEEK];
-
-    private boolean mIsAm;
 
-    private boolean mIs24HourView;
+    private Calendar mDate;                     // 当前选择的日期时间
+    private String[] mDateDisplayValues = new String[DAYS_IN_ALL_WEEK];  // 日期显示值数组
 
-    private boolean mIsEnabled = DEFAULT_ENABLE_STATE;
+    private boolean mIsAm;                      // 是否为上午（true=上午，false=下午）
+    private boolean mIs24HourView;              // 是否为24小时制
+    private boolean mIsEnabled = DEFAULT_ENABLE_STATE;  // 控件是否启用
+    private boolean mInitialising;              // 是否正在初始化
 
-    private boolean mInitialising;
+    private OnDateTimeChangedListener mOnDateTimeChangedListener;  // 日期时间变化监听器
-
-    private OnDateTimeChangedListener mOnDateTimeChangedListener;
 
+    // 日期变化监听器
     private NumberPicker.OnValueChangeListener mOnDateChangedListener = new NumberPicker.OnValueChangeListener() {
         @Override
         public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
+            // 计算日期差异并更新日期
             mDate.add(Calendar.DAY_OF_YEAR, newVal - oldVal);
-            updateDateControl();
+            updateDateControl();      // 更新日期控件显示
-            onDateTimeChanged();
+            onDateTimeChanged();      // 触发日期时间变化回调
         }
     };
 
+    // 小时变化监听器（处理复杂的时间逻辑，包括12/24小时制转换和日期跨天）
     private NumberPicker.OnValueChangeListener mOnHourChangedListener = new NumberPicker.OnValueChangeListener() {
         @Override
         public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
-            boolean isDateChanged = false;
+            boolean isDateChanged = false;  // 标记日期是否发生变化
             Calendar cal = Calendar.getInstance();
+
+            // 12小时制下的特殊处理
             if (!mIs24HourView) {
+                // 处理从11PM到12AM或12AM到11PM的日期变化
                 if (!mIsAm && oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY) {
+                    // 从下午11点切换到12点，日期加1天
                     cal.setTimeInMillis(mDate.getTimeInMillis());
                     cal.add(Calendar.DAY_OF_YEAR, 1);
                     isDateChanged = true;
                 } else if (mIsAm && oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) {
+                    // 从上午12点切换到11点，日期减1天
                     cal.setTimeInMillis(mDate.getTimeInMillis());
                     cal.add(Calendar.DAY_OF_YEAR, -1);
                     isDateChanged = true;
                 }
+
+                // 处理AM/PM切换（当在11和12之间切换时）
                 if (oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY ||
                         oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) {
-                    mIsAm = !mIsAm;
+                    mIsAm = !mIsAm;  // 切换AM/PM状态
-                    updateAmPmControl();
+                    updateAmPmControl();  // 更新AM/PM控件
                 }
             } else {
+                // 24小时制下的特殊处理
                 if (oldVal == HOURS_IN_ALL_DAY - 1 && newVal == 0) {
+                    // 从23点切换到0点，日期加1天
                     cal.setTimeInMillis(mDate.getTimeInMillis());
                     cal.add(Calendar.DAY_OF_YEAR, 1);
                     isDateChanged = true;
                 } else if (oldVal == 0 && newVal == HOURS_IN_ALL_DAY - 1) {
+                    // 从0点切换到23点，日期减1天
                     cal.setTimeInMillis(mDate.getTimeInMillis());
                     cal.add(Calendar.DAY_OF_YEAR, -1);
                     isDateChanged = true;
                 }
             }
+
+            // 计算新的小时（考虑12小时制和AM/PM）
             int newHour = mHourSpinner.getValue() % HOURS_IN_HALF_DAY + (mIsAm ? 0 : HOURS_IN_HALF_DAY);
             mDate.set(Calendar.HOUR_OF_DAY, newHour);
-            onDateTimeChanged();
+            onDateTimeChanged();  // 触发日期时间变化回调
+
+            // 如果日期发生变化，更新年、月、日
             if (isDateChanged) {
                 setCurrentYear(cal.get(Calendar.YEAR));
                 setCurrentMonth(cal.get(Calendar.MONTH));
@@ -115,21 +144,30 @@ public class DateTimePicker extends FrameLayout {
         }
     };
 
+    // 分钟变化监听器（处理分钟滚动到边界时的日期变化）
     private NumberPicker.OnValueChangeListener mOnMinuteChangedListener = new NumberPicker.OnValueChangeListener() {
         @Override
         public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
             int minValue = mMinuteSpinner.getMinValue();
             int maxValue = mMinuteSpinner.getMaxValue();
-            int offset = 0;
+            int offset = 0;  // 小时偏移量
+
+            // 处理分钟滚动到边界的情况
             if (oldVal == maxValue && newVal == minValue) {
+                // 从59分滚动到0分，小时加1
                 offset += 1;
             } else if (oldVal == minValue && newVal == maxValue) {
+                // 从0分滚动到59分，小时减1
                 offset -= 1;
             }
+
+            // 如果需要调整小时
             if (offset != 0) {
-                mDate.add(Calendar.HOUR_OF_DAY, offset);
+                mDate.add(Calendar.HOUR_OF_DAY, offset);  // 调整小时
-                mHourSpinner.setValue(getCurrentHour());
+                mHourSpinner.setValue(getCurrentHour());  // 更新小时选择器
-                updateDateControl();
+                updateDateControl();  // 更新日期控件
+
+                // 检查并更新AM/PM状态
                 int newHour = getCurrentHourOfDay();
                 if (newHour >= HOURS_IN_HALF_DAY) {
                     mIsAm = false;
@@ -139,78 +177,110 @@ public class DateTimePicker extends FrameLayout {
                     updateAmPmControl();
                 }
             }
-            mDate.set(Calendar.MINUTE, newVal);
+
-            onDateTimeChanged();
+            mDate.set(Calendar.MINUTE, newVal);  // 设置新的分钟值
+            onDateTimeChanged();  // 触发日期时间变化回调
         }
     };
 
+    // AM/PM变化监听器
     private NumberPicker.OnValueChangeListener mOnAmPmChangedListener = new NumberPicker.OnValueChangeListener() {
         @Override
         public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
-            mIsAm = !mIsAm;
+            mIsAm = !mIsAm;  // 切换AM/PM状态
+            // 根据AM/PM状态调整小时
             if (mIsAm) {
-                mDate.add(Calendar.HOUR_OF_DAY, -HOURS_IN_HALF_DAY);
+                mDate.add(Calendar.HOUR_OF_DAY, -HOURS_IN_HALF_DAY);  // 从PM切换到AM，减12小时
             } else {
-                mDate.add(Calendar.HOUR_OF_DAY, HOURS_IN_HALF_DAY);
+                mDate.add(Calendar.HOUR_OF_DAY, HOURS_IN_HALF_DAY);   // 从AM切换到PM，加12小时
             }
-            updateAmPmControl();
+            updateAmPmControl();  // 更新AM/PM控件
-            onDateTimeChanged();
+            onDateTimeChanged();   // 触发日期时间变化回调
         }
     };
 
+    /**
+     * 日期时间变化监听器接口
+     */
     public interface OnDateTimeChangedListener {
         void onDateTimeChanged(DateTimePicker view, int year, int month,
-                int dayOfMonth, int hourOfDay, int minute);
+                               int dayOfMonth, int hourOfDay, int minute);
     }
 
+    /**
+     * 构造函数1：使用当前时间
+     * @param context 上下文
+     */
     public DateTimePicker(Context context) {
         this(context, System.currentTimeMillis());
     }
 
+    /**
+     * 构造函数2：使用指定时间和系统默认的24小时制设置
+     * @param context 上下文
+     * @param date 初始日期时间（毫秒时间戳）
+     */
     public DateTimePicker(Context context, long date) {
         this(context, date, DateFormat.is24HourFormat(context));
     }
 
+    /**
+     * 构造函数3：使用指定时间和指定的24小时制设置
+     * @param context 上下文
+     * @param date 初始日期时间（毫秒时间戳）
+     * @param is24HourView 是否为24小时制
+     */
     public DateTimePicker(Context context, long date, boolean is24HourView) {
         super(context);
-        mDate = Calendar.getInstance();
+        mDate = Calendar.getInstance();  // 初始化日历对象
-        mInitialising = true;
+        mInitialising = true;  // 标记为初始化阶段
+
+        // 根据当前小时确定AM/PM状态
         mIsAm = getCurrentHourOfDay() >= HOURS_IN_HALF_DAY;
+
+        // 加载布局
         inflate(context, R.layout.datetime_picker, this);
 
+        // 初始化日期选择器
         mDateSpinner = (NumberPicker) findViewById(R.id.date);
         mDateSpinner.setMinValue(DATE_SPINNER_MIN_VAL);
         mDateSpinner.setMaxValue(DATE_SPINNER_MAX_VAL);
         mDateSpinner.setOnValueChangedListener(mOnDateChangedListener);
 
+        // 初始化小时选择器
         mHourSpinner = (NumberPicker) findViewById(R.id.hour);
         mHourSpinner.setOnValueChangedListener(mOnHourChangedListener);
+
+        // 初始化分钟选择器
         mMinuteSpinner =  (NumberPicker) findViewById(R.id.minute);
         mMinuteSpinner.setMinValue(MINUT_SPINNER_MIN_VAL);
         mMinuteSpinner.setMaxValue(MINUT_SPINNER_MAX_VAL);
-        mMinuteSpinner.setOnLongPressUpdateInterval(100);
+        mMinuteSpinner.setOnLongPressUpdateInterval(100);  // 设置长按更新间隔为100毫秒
         mMinuteSpinner.setOnValueChangedListener(mOnMinuteChangedListener);
 
-        String[] stringsForAmPm = new DateFormatSymbols().getAmPmStrings();
+        // 初始化AM/PM选择器
+        String[] stringsForAmPm = new DateFormatSymbols().getAmPmStrings();  // 获取AM/PM本地化字符串
         mAmPmSpinner = (NumberPicker) findViewById(R.id.amPm);
         mAmPmSpinner.setMinValue(AMPM_SPINNER_MIN_VAL);
         mAmPmSpinner.setMaxValue(AMPM_SPINNER_MAX_VAL);
-        mAmPmSpinner.setDisplayedValues(stringsForAmPm);
+        mAmPmSpinner.setDisplayedValues(stringsForAmPm);  // 设置显示值
         mAmPmSpinner.setOnValueChangedListener(mOnAmPmChangedListener);
 
-        // update controls to initial state
+        // 更新控件到初始状态
         updateDateControl();
         updateHourControl();
         updateAmPmControl();
 
+        // 设置24小时制视图
         set24HourView(is24HourView);
 
-        // set to current time
+        // 设置为当前时间
         setCurrentDate(date);
 
+        // 设置启用状态
         setEnabled(isEnabled());
 
-        // set the content descriptions
+        // 初始化完成
         mInitialising = false;
     }
 
@@ -220,6 +290,7 @@ public class DateTimePicker extends FrameLayout {
             return;
         }
         super.setEnabled(enabled);
+        // 设置所有子控件的启用状态
         mDateSpinner.setEnabled(enabled);
         mMinuteSpinner.setEnabled(enabled);
         mHourSpinner.setEnabled(enabled);
@@ -233,18 +304,16 @@ public class DateTimePicker extends FrameLayout {
     }
 
     /**
-     * Get the current date in millis
+     * 获取当前日期时间的毫秒时间戳
-     *
+     * @return 当前日期时间的毫秒时间戳
-     * @return the current date in millis
      */
     public long getCurrentDateInTimeMillis() {
         return mDate.getTimeInMillis();
     }
 
     /**
-     * Set the current date
+     * 设置当前日期时间（毫秒时间戳）
-     *
+     * @param date 日期时间的毫秒时间戳
-     * @param date The current date in millis
      */
     public void setCurrentDate(long date) {
         Calendar cal = Calendar.getInstance();
@@ -254,16 +323,15 @@ public class DateTimePicker extends FrameLayout {
     }
 
     /**
-     * Set the current date
+     * 设置当前日期时间（各分量）
-     *
+     * @param year 年
-     * @param year The current year
+     * @param month 月
-     * @param month The current month
+     * @param dayOfMonth 日
-     * @param dayOfMonth The current dayOfMonth
+     * @param hourOfDay 小时（24小时制）
-     * @param hourOfDay The current hourOfDay
+     * @param minute 分钟
-     * @param minute The current minute
      */
     public void setCurrentDate(int year, int month,
-            int dayOfMonth, int hourOfDay, int minute) {
+                               int dayOfMonth, int hourOfDay, int minute) {
         setCurrentYear(year);
         setCurrentMonth(month);
         setCurrentDay(dayOfMonth);
@@ -272,214 +340,239 @@ public class DateTimePicker extends FrameLayout {
     }
 
     /**
-     * Get current year
+     * 获取当前年
-     *
+     * @return 当前年
-     * @return The current year
      */
     public int getCurrentYear() {
         return mDate.get(Calendar.YEAR);
     }
 
     /**
-     * Set current year
+     * 设置当前年
-     *
+     * @param year 年
-     * @param year The current year
      */
     public void setCurrentYear(int year) {
         if (!mInitialising && year == getCurrentYear()) {
-            return;
+            return;  // 如果不是初始化且值未变化，直接返回
         }
         mDate.set(Calendar.YEAR, year);
-        updateDateControl();
+        updateDateControl();  // 更新日期控件
-        onDateTimeChanged();
+        onDateTimeChanged();  // 触发日期时间变化回调
     }
 
     /**
-     * Get current month in the year
+     * 获取当前月
-     *
+     * @return 当前月（0-11）
-     * @return The current month in the year
      */
     public int getCurrentMonth() {
         return mDate.get(Calendar.MONTH);
     }
 
     /**
-     * Set current month in the year
+     * 设置当前月
-     *
+     * @param month 月（0-11）
-     * @param month The month in the year
      */
     public void setCurrentMonth(int month) {
         if (!mInitialising && month == getCurrentMonth()) {
-            return;
+            return;  // 如果不是初始化且值未变化，直接返回
         }
         mDate.set(Calendar.MONTH, month);
-        updateDateControl();
+        updateDateControl();  // 更新日期控件
-        onDateTimeChanged();
+        onDateTimeChanged();  // 触发日期时间变化回调
     }
 
     /**
-     * Get current day of the month
+     * 获取当前日
-     *
+     * @return 当前日
-     * @return The day of the month
      */
     public int getCurrentDay() {
         return mDate.get(Calendar.DAY_OF_MONTH);
     }
 
     /**
-     * Set current day of the month
+     * 设置当前日
-     *
+     * @param dayOfMonth 日
-     * @param dayOfMonth The day of the month
      */
     public void setCurrentDay(int dayOfMonth) {
         if (!mInitialising && dayOfMonth == getCurrentDay()) {
-            return;
+            return;  // 如果不是初始化且值未变化，直接返回
         }
         mDate.set(Calendar.DAY_OF_MONTH, dayOfMonth);
-        updateDateControl();
+        updateDateControl();  // 更新日期控件
-        onDateTimeChanged();
+        onDateTimeChanged();  // 触发日期时间变化回调
     }
 
     /**
-     * Get current hour in 24 hour mode, in the range (0~23)
+     * 获取当前小时（24小时制）
-     * @return The current hour in 24 hour mode
+     * @return 当前小时（0-23）
      */
     public int getCurrentHourOfDay() {
         return mDate.get(Calendar.HOUR_OF_DAY);
     }
 
+    /**
+     * 获取当前小时（根据当前视图模式：12或24小时制）
+     * @return 当前小时（12小时制：1-12，24小时制：0-23）
+     */
     private int getCurrentHour() {
         if (mIs24HourView){
             return getCurrentHourOfDay();
         } else {
             int hour = getCurrentHourOfDay();
             if (hour > HOURS_IN_HALF_DAY) {
-                return hour - HOURS_IN_HALF_DAY;
+                return hour - HOURS_IN_HALF_DAY;  // 下午：13-23转换为1-11
             } else {
-                return hour == 0 ? HOURS_IN_HALF_DAY : hour;
+                return hour == 0 ? HOURS_IN_HALF_DAY : hour;  // 0点转换为12点，1-11点不变
             }
         }
     }
 
     /**
-     * Set current hour in 24 hour mode, in the range (0~23)
+     * 设置当前小时（24小时制）
-     *
+     * @param hourOfDay 小时（0-23）
-     * @param hourOfDay
      */
     public void setCurrentHour(int hourOfDay) {
         if (!mInitialising && hourOfDay == getCurrentHourOfDay()) {
-            return;
+            return;  // 如果不是初始化且值未变化，直接返回
         }
         mDate.set(Calendar.HOUR_OF_DAY, hourOfDay);
+
+        // 12小时制下的特殊处理
         if (!mIs24HourView) {
             if (hourOfDay >= HOURS_IN_HALF_DAY) {
-                mIsAm = false;
+                mIsAm = false;  // 下午
                 if (hourOfDay > HOURS_IN_HALF_DAY) {
-                    hourOfDay -= HOURS_IN_HALF_DAY;
+                    hourOfDay -= HOURS_IN_HALF_DAY;  // 13-23转换为1-11
                 }
             } else {
-                mIsAm = true;
+                mIsAm = true;  // 上午
                 if (hourOfDay == 0) {
-                    hourOfDay = HOURS_IN_HALF_DAY;
+                    hourOfDay = HOURS_IN_HALF_DAY;  // 0点转换为12点
                 }
             }
-            updateAmPmControl();
+            updateAmPmControl();  // 更新AM/PM控件
         }
-        mHourSpinner.setValue(hourOfDay);
+        mHourSpinner.setValue(hourOfDay);  // 设置小时选择器值
-        onDateTimeChanged();
+        onDateTimeChanged();  // 触发日期时间变化回调
     }
 
     /**
-     * Get currentMinute
+     * 获取当前分钟
-     *
+     * @return 当前分钟
-     * @return The Current Minute
      */
     public int getCurrentMinute() {
         return mDate.get(Calendar.MINUTE);
     }
 
     /**
-     * Set current minute
+     * 设置当前分钟
+     * @param minute 分钟
      */
     public void setCurrentMinute(int minute) {
         if (!mInitialising && minute == getCurrentMinute()) {
-            return;
+            return;  // 如果不是初始化且值未变化，直接返回
         }
-        mMinuteSpinner.setValue(minute);
+        mMinuteSpinner.setValue(minute);  // 设置分钟选择器值
         mDate.set(Calendar.MINUTE, minute);
-        onDateTimeChanged();
+        onDateTimeChanged();  // 触发日期时间变化回调
     }
 
     /**
-     * @return true if this is in 24 hour view else false.
+     * 检查是否为24小时制
+     * @return true表示24小时制，false表示12小时制
      */
     public boolean is24HourView () {
         return mIs24HourView;
     }
 
     /**
-     * Set whether in 24 hour or AM/PM mode.
+     * 设置24小时制或AM/PM模式
-     *
+     * @param is24HourView true为24小时制，false为AM/PM模式
-     * @param is24HourView True for 24 hour mode. False for AM/PM mode.
      */
     public void set24HourView(boolean is24HourView) {
         if (mIs24HourView == is24HourView) {
-            return;
+            return;  // 如果模式未变化，直接返回
         }
         mIs24HourView = is24HourView;
+
+        // 设置AM/PM选择器的可见性
         mAmPmSpinner.setVisibility(is24HourView ? View.GONE : View.VISIBLE);
+
         int hour = getCurrentHourOfDay();
-        updateHourControl();
+        updateHourControl();  // 更新小时选择器范围
-        setCurrentHour(hour);
+        setCurrentHour(hour);  // 重新设置小时（考虑模式转换）
-        updateAmPmControl();
+        updateAmPmControl();  // 更新AM/PM控件
     }
 
+    /**
+     * 更新日期控件显示
+     * 显示以当前日期为中心的一周日期
+     */
     private void updateDateControl() {
         Calendar cal = Calendar.getInstance();
         cal.setTimeInMillis(mDate.getTimeInMillis());
+
+        // 向前调整3天，以便以当前日期为中心显示一周
         cal.add(Calendar.DAY_OF_YEAR, -DAYS_IN_ALL_WEEK / 2 - 1);
-        mDateSpinner.setDisplayedValues(null);
+
+        mDateSpinner.setDisplayedValues(null);  // 清除旧值
+
+        // 生成一周的日期显示值
         for (int i = 0; i < DAYS_IN_ALL_WEEK; ++i) {
             cal.add(Calendar.DAY_OF_YEAR, 1);
+            // 格式化为"MM.dd EEEE"（月.日 星期）
             mDateDisplayValues[i] = (String) DateFormat.format("MM.dd EEEE", cal);
         }
-        mDateSpinner.setDisplayedValues(mDateDisplayValues);
+
-        mDateSpinner.setValue(DAYS_IN_ALL_WEEK / 2);
+        mDateSpinner.setDisplayedValues(mDateDisplayValues);  // 设置显示值
-        mDateSpinner.invalidate();
+        mDateSpinner.setValue(DAYS_IN_ALL_WEEK / 2);  // 设置当前选中位置为中间（当前日期）
+        mDateSpinner.invalidate();  // 刷新控件
     }
 
+    /**
+     * 更新AM/PM控件
+     */
     private void updateAmPmControl() {
         if (mIs24HourView) {
-            mAmPmSpinner.setVisibility(View.GONE);
+            mAmPmSpinner.setVisibility(View.GONE);  // 24小时制下隐藏AM/PM选择器
         } else {
             int index = mIsAm ? Calendar.AM : Calendar.PM;
-            mAmPmSpinner.setValue(index);
+            mAmPmSpinner.setValue(index);  // 设置AM/PM值
-            mAmPmSpinner.setVisibility(View.VISIBLE);
+            mAmPmSpinner.setVisibility(View.VISIBLE);  // 显示AM/PM选择器
         }
     }
 
+    /**
+     * 更新小时控件范围
+     */
     private void updateHourControl() {
         if (mIs24HourView) {
+            // 24小时制范围：0-23
             mHourSpinner.setMinValue(HOUR_SPINNER_MIN_VAL_24_HOUR_VIEW);
             mHourSpinner.setMaxValue(HOUR_SPINNER_MAX_VAL_24_HOUR_VIEW);
         } else {
+            // 12小时制范围：1-12
             mHourSpinner.setMinValue(HOUR_SPINNER_MIN_VAL_12_HOUR_VIEW);
             mHourSpinner.setMaxValue(HOUR_SPINNER_MAX_VAL_12_HOUR_VIEW);
         }
     }
 
     /**
-     * Set the callback that indicates the 'Set' button has been pressed.
+     * 设置日期时间变化监听器
-     * @param callback the callback, if null will do nothing
+     * @param callback 监听器，如果为null则不做任何操作
      */
     public void setOnDateTimeChangedListener(OnDateTimeChangedListener callback) {
         mOnDateTimeChangedListener = callback;
     }
 
+    /**
+     * 触发日期时间变化回调
+     */
     private void onDateTimeChanged() {
         if (mOnDateTimeChangedListener != null) {
+            // 传递所有日期时间分量给监听器
             mOnDateTimeChangedListener.onDateTimeChanged(this, getCurrentYear(),
                     getCurrentMonth(), getCurrentDay(), getCurrentHourOfDay(), getCurrentMinute());
         }
     }
-}
+}

src/notes/ui/DateTimePickerDialog.java

@@ -29,62 +29,113 @@ import android.content.DialogInterface.OnClickListener;
 import android.text.format.DateFormat;
 import android.text.format.DateUtils;
 
+/**
+ * 日期时间选择对话框
+ * 封装DateTimePicker控件，提供完整的日期时间选择界面
+ */
 public class DateTimePickerDialog extends AlertDialog implements OnClickListener {
+    private Calendar mDate = Calendar.getInstance();  // 存储当前选择的日期时间
+    private boolean mIs24HourView;                   // 是否为24小时制
+    private OnDateTimeSetListener mOnDateTimeSetListener;  // 日期时间设置监听器
+    private DateTimePicker mDateTimePicker;          // 日期时间选择器控件
 
-    private Calendar mDate = Calendar.getInstance();
+    /**
-    private boolean mIs24HourView;
+     * 日期时间设置监听器接口
-    private OnDateTimeSetListener mOnDateTimeSetListener;
+     * 当用户点击确定按钮时回调
-    private DateTimePicker mDateTimePicker;
+     */
-
     public interface OnDateTimeSetListener {
         void OnDateTimeSet(AlertDialog dialog, long date);
     }
 
+    /**
+     * 构造函数
+     * @param context 上下文
+     * @param date 初始日期时间（毫秒时间戳）
+     */
     public DateTimePickerDialog(Context context, long date) {
         super(context);
+
+        // 创建日期时间选择器控件
         mDateTimePicker = new DateTimePicker(context);
-        setView(mDateTimePicker);
+        setView(mDateTimePicker);  // 将控件添加到对话框
+
+        // 设置日期时间变化监听器
         mDateTimePicker.setOnDateTimeChangedListener(new OnDateTimeChangedListener() {
             public void onDateTimeChanged(DateTimePicker view, int year, int month,
-                    int dayOfMonth, int hourOfDay, int minute) {
+                                          int dayOfMonth, int hourOfDay, int minute) {
+                // 更新内部Calendar对象的各个时间分量
                 mDate.set(Calendar.YEAR, year);
                 mDate.set(Calendar.MONTH, month);
                 mDate.set(Calendar.DAY_OF_MONTH, dayOfMonth);
                 mDate.set(Calendar.HOUR_OF_DAY, hourOfDay);
                 mDate.set(Calendar.MINUTE, minute);
+
+                // 更新对话框标题显示新的日期时间
                 updateTitle(mDate.getTimeInMillis());
             }
         });
+
+        // 设置初始日期时间
         mDate.setTimeInMillis(date);
-        mDate.set(Calendar.SECOND, 0);
+        mDate.set(Calendar.SECOND, 0);  // 将秒设为0，只精确到分钟
-        mDateTimePicker.setCurrentDate(mDate.getTimeInMillis());
+        mDateTimePicker.setCurrentDate(mDate.getTimeInMillis());  // 更新控件显示
-        setButton(context.getString(R.string.datetime_dialog_ok), this);
+
-        setButton2(context.getString(R.string.datetime_dialog_cancel), (OnClickListener)null);
+        // 设置对话框按钮
+        setButton(context.getString(R.string.datetime_dialog_ok), this);  // 确定按钮
+        setButton2(context.getString(R.string.datetime_dialog_cancel), (OnClickListener)null);  // 取消按钮
+
+        // 根据系统设置决定是否为24小时制
         set24HourView(DateFormat.is24HourFormat(this.getContext()));
+
+        // 更新对话框标题
         updateTitle(mDate.getTimeInMillis());
     }
 
+    /**
+     * 设置24小时制视图
+     * @param is24HourView true为24小时制，false为12小时制
+     */
     public void set24HourView(boolean is24HourView) {
         mIs24HourView = is24HourView;
     }
 
+    /**
+     * 设置日期时间设置监听器
+     * @param callBack 监听器
+     */
     public void setOnDateTimeSetListener(OnDateTimeSetListener callBack) {
         mOnDateTimeSetListener = callBack;
     }
 
+    /**
+     * 更新对话框标题为当前选择的日期时间
+     * @param date 日期时间（毫秒时间戳）
+     */
     private void updateTitle(long date) {
+        // 设置日期时间显示格式标志
         int flag =
-            DateUtils.FORMAT_SHOW_YEAR |
+                DateUtils.FORMAT_SHOW_YEAR |   // 显示年份
-            DateUtils.FORMAT_SHOW_DATE |
+                        DateUtils.FORMAT_SHOW_DATE |   // 显示日期
-            DateUtils.FORMAT_SHOW_TIME;
+                        DateUtils.FORMAT_SHOW_TIME;    // 显示时间
+
+        // 根据是否24小时制添加相应的标志
+        // 注意：这里有代码问题，无论mIs24HourView为何值，都使用FORMAT_24HOUR
+        // 应该是：mIs24HourView ? DateUtils.FORMAT_24HOUR : 0
         flag |= mIs24HourView ? DateUtils.FORMAT_24HOUR : DateUtils.FORMAT_24HOUR;
+
+        // 使用DateUtils格式化日期时间为字符串，并设置为对话框标题
         setTitle(DateUtils.formatDateTime(this.getContext(), date, flag));
     }
 
+    /**
+     * 对话框按钮点击事件处理
+     * @param arg0 对话框
+     * @param arg1 按钮标识
+     */
     public void onClick(DialogInterface arg0, int arg1) {
+        // 当用户点击确定按钮时，回调日期时间设置监听器
         if (mOnDateTimeSetListener != null) {
             mOnDateTimeSetListener.OnDateTimeSet(this, mDate.getTimeInMillis());
         }
     }
-
 }

src/notes/ui/DropdownMenu.java

@@ -27,17 +27,34 @@ import android.widget.PopupMenu.OnMenuItemClickListener;
 
 import net.micode.notes.R;
 
+/**
+ * 下拉菜单控件封装类
+ * 将Button与PopupMenu结合，提供下拉菜单功能
+ */
 public class DropdownMenu {
-    private Button mButton;
+    private Button mButton;        // 触发下拉菜单的按钮
-    private PopupMenu mPopupMenu;
+    private PopupMenu mPopupMenu;  // 弹出式菜单
-    private Menu mMenu;
+    private Menu mMenu;            // 菜单项容器
 
+    /**
+     * 构造函数
+     * @param context 上下文
+     * @param button 用于触发下拉菜单的按钮
+     * @param menuId 菜单资源ID（R.menu.xxx）
+     */
     public DropdownMenu(Context context, Button button, int menuId) {
         mButton = button;
+        // 设置按钮背景为下拉箭头图标
         mButton.setBackgroundResource(R.drawable.dropdown_icon);
+
+        // 创建PopupMenu，以按钮为锚点
         mPopupMenu = new PopupMenu(context, mButton);
+        // 获取PopupMenu的Menu对象
         mMenu = mPopupMenu.getMenu();
+        // 从资源文件加载菜单项
         mPopupMenu.getMenuInflater().inflate(menuId, mMenu);
+
+        // 设置按钮点击监听器，点击时显示下拉菜单
         mButton.setOnClickListener(new OnClickListener() {
             public void onClick(View v) {
                 mPopupMenu.show();
@@ -45,17 +62,30 @@ public class DropdownMenu {
         });
     }
 
+    /**
+     * 设置菜单项点击监听器
+     * @param listener 菜单项点击监听器
+     */
     public void setOnDropdownMenuItemClickListener(OnMenuItemClickListener listener) {
         if (mPopupMenu != null) {
             mPopupMenu.setOnMenuItemClickListener(listener);
         }
     }
 
+    /**
+     * 根据ID查找菜单项
+     * @param id 菜单项ID
+     * @return 对应的MenuItem对象
+     */
     public MenuItem findItem(int id) {
         return mMenu.findItem(id);
     }
 
+    /**
+     * 设置按钮显示的文本
+     * @param title 按钮文本
+     */
     public void setTitle(CharSequence title) {
         mButton.setText(title);
     }
-}
+}

src/notes/ui/FoldersListAdapter.java

@@ -28,53 +28,109 @@ import net.micode.notes.R;
 import net.micode.notes.data.Notes;
 import net.micode.notes.data.Notes.NoteColumns;
 
-
+/**
+ * 文件夹列表适配器
+ * 继承自CursorAdapter，用于在列表视图中显示文件夹数据
+ */
 public class FoldersListAdapter extends CursorAdapter {
+    // 数据库查询字段投影：只需要ID和名称
     public static final String [] PROJECTION = {
-        NoteColumns.ID,
+            NoteColumns.ID,        // 文件夹ID
-        NoteColumns.SNIPPET
+            NoteColumns.SNIPPET   // 文件夹名称（存储在SNIPPET字段中）
     };
 
-    public static final int ID_COLUMN   = 0;
+    // 列索引常量定义
-    public static final int NAME_COLUMN = 1;
+    public static final int ID_COLUMN   = 0;  // ID列索引
+    public static final int NAME_COLUMN = 1;  // 名称列索引
 
+    /**
+     * 构造函数
+     * @param context 上下文
+     * @param c 包含文件夹数据的Cursor
+     */
     public FoldersListAdapter(Context context, Cursor c) {
         super(context, c);
-        // TODO Auto-generated constructor stub
+        // TODO: 自动生成的构造函数存根
     }
 
+    /**
+     * 创建新的列表项视图
+     * @param context 上下文
+     * @param cursor 数据Cursor
+     * @param parent 父视图组
+     * @return 新创建的FolderListItem视图
+     */
     @Override
     public View newView(Context context, Cursor cursor, ViewGroup parent) {
         return new FolderListItem(context);
     }
 
+    /**
+     * 绑定数据到现有视图
+     * @param view 要绑定数据的视图
+     * @param context 上下文
+     * @param cursor 数据Cursor
+     */
     @Override
     public void bindView(View view, Context context, Cursor cursor) {
+        // 检查视图类型是否为FolderListItem
         if (view instanceof FolderListItem) {
-            String folderName = (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER) ? context
+            String folderName;
-                    .getString(R.string.menu_move_parent_folder) : cursor.getString(NAME_COLUMN);
+
+            // 特殊处理根文件夹：如果ID是根文件夹ID，则显示特定的父文件夹名称
+            if (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER) {
+                folderName = context.getString(R.string.menu_move_parent_folder);
+            } else {
+                folderName = cursor.getString(NAME_COLUMN);
+            }
+
+            // 调用FolderListItem的bind方法设置文件夹名称
             ((FolderListItem) view).bind(folderName);
         }
     }
 
+    /**
+     * 获取指定位置的文件夹名称
+     * @param context 上下文（用于获取根文件夹的本地化名称）
+     * @param position 位置索引
+     * @return 文件夹名称
+     */
     public String getFolderName(Context context, int position) {
-        Cursor cursor = (Cursor) getItem(position);
+        Cursor cursor = (Cursor) getItem(position);  // 获取对应位置的Cursor数据
-        return (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER) ? context
+
-                .getString(R.string.menu_move_parent_folder) : cursor.getString(NAME_COLUMN);
+        // 特殊处理根文件夹：如果ID是根文件夹ID，则返回特定的父文件夹名称
+        if (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER) {
+            return context.getString(R.string.menu_move_parent_folder);
+        } else {
+            return cursor.getString(NAME_COLUMN);
+        }
     }
 
+    /**
+     * 内部类：文件夹列表项视图
+     * 继承自LinearLayout，表示单个文件夹列表项
+     */
     private class FolderListItem extends LinearLayout {
-        private TextView mName;
+        private TextView mName;  // 显示文件夹名称的TextView
 
+        /**
+         * 构造函数
+         * @param context 上下文
+         */
         public FolderListItem(Context context) {
             super(context);
+            // 加载布局文件
             inflate(context, R.layout.folder_list_item, this);
+            // 初始化TextView
             mName = (TextView) findViewById(R.id.tv_folder_name);
         }
 
+        /**
+         * 绑定文件夹名称到视图
+         * @param name 文件夹名称
+         */
         public void bind(String name) {
             mName.setText(name);
         }
     }
-
+}
-}

src/notes/ui/NoteEditText.java

@@ -37,83 +37,125 @@ import net.micode.notes.R;
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * 自定义EditText，用于笔记编辑功能
+ * 支持特殊按键处理（如回车创建新编辑框、删除空编辑框）和链接识别
+ */
 public class NoteEditText extends EditText {
-    private static final String TAG = "NoteEditText";
+    private static final String TAG = "NoteEditText"; // 日志标签
-    private int mIndex;
+    private int mIndex; // 当前EditText在列表中的索引位置
-    private int mSelectionStartBeforeDelete;
+    private int mSelectionStartBeforeDelete; // 删除操作前的光标起始位置
 
-    private static final String SCHEME_TEL = "tel:" ;
+    // 链接协议定义
-    private static final String SCHEME_HTTP = "http:" ;
+    private static final String SCHEME_TEL = "tel:"; // 电话链接协议
-    private static final String SCHEME_EMAIL = "mailto:" ;
+    private static final String SCHEME_HTTP = "http:"; // HTTP链接协议
+    private static final String SCHEME_EMAIL = "mailto:"; // 邮件链接协议
 
+    // 链接协议与对应字符串资源的映射表
     private static final Map<String, Integer> sSchemaActionResMap = new HashMap<String, Integer>();
     static {
+        // 初始化链接协议与字符串资源的映射
         sSchemaActionResMap.put(SCHEME_TEL, R.string.note_link_tel);
         sSchemaActionResMap.put(SCHEME_HTTP, R.string.note_link_web);
         sSchemaActionResMap.put(SCHEME_EMAIL, R.string.note_link_email);
     }
 
     /**
-     * Call by the {@link NoteEditActivity} to delete or add edit text
+     * 文本变化监听器接口，由NoteEditActivity实现
+     * 用于处理编辑文本的删除、回车和文本变化事件
      */
     public interface OnTextViewChangeListener {
         /**
-         * Delete current edit text when {@link KeyEvent#KEYCODE_DEL} happens
+         * 当发生删除操作且文本为空时，删除当前编辑框
-         * and the text is null
+         * @param index 当前编辑框的索引
+         * @param text 当前编辑框的文本内容
          */
         void onEditTextDelete(int index, String text);
 
         /**
-         * Add edit text after current edit text when {@link KeyEvent#KEYCODE_ENTER}
+         * 当按下回车键时，在当前编辑框后添加新的编辑框
-         * happen
+         * @param index 新编辑框的索引
+         * @param text 需要移到新编辑框的文本内容
          */
         void onEditTextEnter(int index, String text);
 
         /**
-         * Hide or show item option when text change
+         * 当文本内容变化时，隐藏或显示选项菜单项
+         * @param index 当前编辑框的索引
+         * @param hasText 当前编辑框是否有文本内容
          */
         void onTextChange(int index, boolean hasText);
     }
 
-    private OnTextViewChangeListener mOnTextViewChangeListener;
+    private OnTextViewChangeListener mOnTextViewChangeListener; // 文本变化监听器实例
 
+    /**
+     * 构造函数1
+     * @param context 上下文环境
+     */
     public NoteEditText(Context context) {
         super(context, null);
-        mIndex = 0;
+        mIndex = 0; // 初始化索引为0
     }
 
+    /**
+     * 设置当前编辑框在列表中的索引
+     * @param index 索引值
+     */
     public void setIndex(int index) {
         mIndex = index;
     }
 
+    /**
+     * 设置文本变化监听器
+     * @param listener 监听器实例
+     */
     public void setOnTextViewChangeListener(OnTextViewChangeListener listener) {
         mOnTextViewChangeListener = listener;
     }
 
+    /**
+     * 构造函数2
+     * @param context 上下文环境
+     * @param attrs 属性集
+     */
     public NoteEditText(Context context, AttributeSet attrs) {
         super(context, attrs, android.R.attr.editTextStyle);
     }
 
+    /**
+     * 构造函数3
+     * @param context 上下文环境
+     * @param attrs 属性集
+     * @param defStyle 默认样式
+     */
     public NoteEditText(Context context, AttributeSet attrs, int defStyle) {
         super(context, attrs, defStyle);
         // TODO Auto-generated constructor stub
     }
 
+    /**
+     * 处理触摸事件，实现点击文本位置设置光标功能
+     * @param event 触摸事件
+     * @return 是否处理了该事件
+     */
     @Override
     public boolean onTouchEvent(MotionEvent event) {
         switch (event.getAction()) {
-            case MotionEvent.ACTION_DOWN:
+            case MotionEvent.ACTION_DOWN: // 按下事件
-
+                // 计算点击位置在文本布局中的偏移量
                 int x = (int) event.getX();
                 int y = (int) event.getY();
-                x -= getTotalPaddingLeft();
+                x -= getTotalPaddingLeft(); // 减去内边距
                 y -= getTotalPaddingTop();
-                x += getScrollX();
+                x += getScrollX(); // 加上滚动偏移
                 y += getScrollY();
 
+                // 获取文本布局并计算点击位置的字符偏移
                 Layout layout = getLayout();
                 int line = layout.getLineForVertical(y);
                 int off = layout.getOffsetForHorizontal(line, x);
+                // 设置光标位置
                 Selection.setSelection(getText(), off);
                 break;
         }
@@ -121,15 +163,22 @@ public class NoteEditText extends EditText {
         return super.onTouchEvent(event);
     }
 
+    /**
+     * 按键按下事件处理
+     * @param keyCode 按键代码
+     * @param event 按键事件
+     * @return 是否处理了该事件
+     */
     @Override
     public boolean onKeyDown(int keyCode, KeyEvent event) {
         switch (keyCode) {
-            case KeyEvent.KEYCODE_ENTER:
+            case KeyEvent.KEYCODE_ENTER: // 回车键
                 if (mOnTextViewChangeListener != null) {
-                    return false;
+                    return false; // 返回false让系统继续处理回车事件
                 }
                 break;
-            case KeyEvent.KEYCODE_DEL:
+            case KeyEvent.KEYCODE_DEL: // 删除键
+                // 记录删除前的光标起始位置
                 mSelectionStartBeforeDelete = getSelectionStart();
                 break;
             default:
@@ -138,27 +187,37 @@ public class NoteEditText extends EditText {
         return super.onKeyDown(keyCode, event);
     }
 
+    /**
+     * 按键释放事件处理
+     * @param keyCode 按键代码
+     * @param event 按键事件
+     * @return 是否处理了该事件
+     */
     @Override
     public boolean onKeyUp(int keyCode, KeyEvent event) {
         switch(keyCode) {
-            case KeyEvent.KEYCODE_DEL:
+            case KeyEvent.KEYCODE_DEL: // 删除键释放
                 if (mOnTextViewChangeListener != null) {
+                    // 如果光标在开头且不是第一个编辑框，则删除当前编辑框
                     if (0 == mSelectionStartBeforeDelete && mIndex != 0) {
                         mOnTextViewChangeListener.onEditTextDelete(mIndex, getText().toString());
-                        return true;
+                        return true; // 消耗事件，不再继续处理
                     }
                 } else {
-                    Log.d(TAG, "OnTextViewChangeListener was not seted");
+                    Log.d(TAG, "OnTextViewChangeListener was not seted"); // 监听器未设置日志
                 }
                 break;
-            case KeyEvent.KEYCODE_ENTER:
+            case KeyEvent.KEYCODE_ENTER: // 回车键释放
                 if (mOnTextViewChangeListener != null) {
+                    // 获取光标位置及之后的文本
                     int selectionStart = getSelectionStart();
                     String text = getText().subSequence(selectionStart, length()).toString();
+                    // 截断光标后的文本
                     setText(getText().subSequence(0, selectionStart));
+                    // 通知Activity在当前编辑框后添加新编辑框
                     mOnTextViewChangeListener.onEditTextEnter(mIndex + 1, text);
                 } else {
-                    Log.d(TAG, "OnTextViewChangeListener was not seted");
+                    Log.d(TAG, "OnTextViewChangeListener was not seted"); // 监听器未设置日志
                 }
                 break;
             default:
@@ -167,30 +226,46 @@ public class NoteEditText extends EditText {
         return super.onKeyUp(keyCode, event);
     }
 
+    /**
+     * 焦点变化事件处理
+     * @param focused 是否获得焦点
+     * @param direction 焦点方向
+     * @param previouslyFocusedRect 之前获得焦点的矩形区域
+     */
     @Override
     protected void onFocusChanged(boolean focused, int direction, Rect previouslyFocusedRect) {
         if (mOnTextViewChangeListener != null) {
+            // 根据是否有文本内容通知监听器更新UI状态
             if (!focused && TextUtils.isEmpty(getText())) {
-                mOnTextViewChangeListener.onTextChange(mIndex, false);
+                mOnTextViewChangeListener.onTextChange(mIndex, false); // 无文本
             } else {
-                mOnTextViewChangeListener.onTextChange(mIndex, true);
+                mOnTextViewChangeListener.onTextChange(mIndex, true); // 有文本
             }
         }
         super.onFocusChanged(focused, direction, previouslyFocusedRect);
     }
 
+    /**
+     * 创建上下文菜单（长按菜单）
+     * @param menu 上下文菜单
+     */
     @Override
     protected void onCreateContextMenu(ContextMenu menu) {
+        // 检查文本是否包含富文本（如链接）
         if (getText() instanceof Spanned) {
-            int selStart = getSelectionStart();
+            int selStart = getSelectionStart(); // 选择起始位置
-            int selEnd = getSelectionEnd();
+            int selEnd = getSelectionEnd(); // 选择结束位置
 
+            // 计算选择范围
             int min = Math.min(selStart, selEnd);
             int max = Math.max(selStart, selEnd);
 
+            // 获取选择范围内的URLSpan对象
             final URLSpan[] urls = ((Spanned) getText()).getSpans(min, max, URLSpan.class);
+            // 如果只选择了一个链接
             if (urls.length == 1) {
-                int defaultResId = 0;
+                int defaultResId = 0; // 默认资源ID
+                // 遍历协议映射表，匹配链接类型
                 for(String schema: sSchemaActionResMap.keySet()) {
                     if(urls[0].getURL().indexOf(schema) >= 0) {
                         defaultResId = sSchemaActionResMap.get(schema);
@@ -198,14 +273,16 @@ public class NoteEditText extends EditText {
                     }
                 }
 
+                // 如果没有匹配到已知协议，使用"其他链接"选项
                 if (defaultResId == 0) {
                     defaultResId = R.string.note_link_other;
                 }
 
+                // 添加菜单项并设置点击监听器
                 menu.add(0, 0, 0, defaultResId).setOnMenuItemClickListener(
                         new OnMenuItemClickListener() {
                             public boolean onMenuItemClick(MenuItem item) {
-                                // goto a new intent
+                                // 触发链接点击事件（跳转到相应应用）
                                 urls[0].onClick(NoteEditText.this);
                                 return true;
                             }
@@ -214,4 +291,4 @@ public class NoteEditText extends EditText {
         }
         super.onCreateContextMenu(menu);
     }
-}
+}

src/notes/ui/NoteItemData.java

@@ -25,23 +25,29 @@ import net.micode.notes.data.Notes;
 import net.micode.notes.data.Notes.NoteColumns;
 import net.micode.notes.tool.DataUtils;
 
-
+/**
+ * 笔记数据项类
+ * 用于封装和操作单条笔记的数据信息
+ * 从数据库游标中读取数据，并提供访问方法
+ */
 public class NoteItemData {
+    // 数据库查询字段投影，定义需要从数据库中获取的列
     static final String [] PROJECTION = new String [] {
-        NoteColumns.ID,
+            NoteColumns.ID,                   // 笔记ID
-        NoteColumns.ALERTED_DATE,
+            NoteColumns.ALERTED_DATE,         // 提醒日期
-        NoteColumns.BG_COLOR_ID,
+            NoteColumns.BG_COLOR_ID,          // 背景颜色ID
-        NoteColumns.CREATED_DATE,
+            NoteColumns.CREATED_DATE,         // 创建日期
-        NoteColumns.HAS_ATTACHMENT,
+            NoteColumns.HAS_ATTACHMENT,       // 是否有附件
-        NoteColumns.MODIFIED_DATE,
+            NoteColumns.MODIFIED_DATE,        // 修改日期
-        NoteColumns.NOTES_COUNT,
+            NoteColumns.NOTES_COUNT,          // 笔记数量（对于文件夹类型）
-        NoteColumns.PARENT_ID,
+            NoteColumns.PARENT_ID,            // 父文件夹ID
-        NoteColumns.SNIPPET,
+            NoteColumns.SNIPPET,              // 内容摘要
-        NoteColumns.TYPE,
+            NoteColumns.TYPE,                 // 类型（笔记、文件夹、系统文件夹等）
-        NoteColumns.WIDGET_ID,
+            NoteColumns.WIDGET_ID,            // 小部件ID
-        NoteColumns.WIDGET_TYPE,
+            NoteColumns.WIDGET_TYPE,          // 小部件类型
     };
 
+    // 字段索引常量定义，对应PROJECTION数组中的位置
     private static final int ID_COLUMN                    = 0;
     private static final int ALERTED_DATE_COLUMN          = 1;
     private static final int BG_COLOR_ID_COLUMN           = 2;
@@ -55,28 +61,38 @@ public class NoteItemData {
     private static final int WIDGET_ID_COLUMN             = 10;
     private static final int WIDGET_TYPE_COLUMN           = 11;
 
-    private long mId;
+    // 笔记数据字段
-    private long mAlertDate;
+    private long mId;                 // 笔记ID
-    private int mBgColorId;
+    private long mAlertDate;          // 提醒时间
-    private long mCreatedDate;
+    private int mBgColorId;           // 背景颜色ID
-    private boolean mHasAttachment;
+    private long mCreatedDate;        // 创建时间
-    private long mModifiedDate;
+    private boolean mHasAttachment;   // 是否有附件
-    private int mNotesCount;
+    private long mModifiedDate;       // 修改时间
-    private long mParentId;
+    private int mNotesCount;          // 包含的笔记数量（文件夹类型有效）
-    private String mSnippet;
+    private long mParentId;           // 父文件夹ID
-    private int mType;
+    private String mSnippet;          // 内容摘要
-    private int mWidgetId;
+    private int mType;                // 笔记类型
-    private int mWidgetType;
+    private int mWidgetId;            // 关联的小部件ID
-    private String mName;
+    private int mWidgetType;          // 小部件类型
-    private String mPhoneNumber;
+
-
+    // 通话记录相关字段
-    private boolean mIsLastItem;
+    private String mName;             // 联系人姓名
-    private boolean mIsFirstItem;
+    private String mPhoneNumber;      // 电话号码
-    private boolean mIsOnlyOneItem;
+
-    private boolean mIsOneNoteFollowingFolder;
+    // 列表位置状态标识
-    private boolean mIsMultiNotesFollowingFolder;
+    private boolean mIsLastItem;               // 是否为最后一项
-
+    private boolean mIsFirstItem;              // 是否为第一项
+    private boolean mIsOnlyOneItem;            // 是否只有一项
+    private boolean mIsOneNoteFollowingFolder; // 是否是单个笔记跟随文件夹后
+    private boolean mIsMultiNotesFollowingFolder; // 是否是多个笔记跟随文件夹后
+
+    /**
+     * 构造函数，从数据库游标初始化笔记数据
+     * @param context 上下文对象
+     * @param cursor 数据库查询结果游标
+     */
     public NoteItemData(Context context, Cursor cursor) {
+        // 从游标中读取各字段值
         mId = cursor.getLong(ID_COLUMN);
         mAlertDate = cursor.getLong(ALERTED_DATE_COLUMN);
         mBgColorId = cursor.getInt(BG_COLOR_ID_COLUMN);
@@ -86,47 +102,68 @@ public class NoteItemData {
         mNotesCount = cursor.getInt(NOTES_COUNT_COLUMN);
         mParentId = cursor.getLong(PARENT_ID_COLUMN);
         mSnippet = cursor.getString(SNIPPET_COLUMN);
+        // 移除摘要中的复选框标记（已勾选和未勾选）
         mSnippet = mSnippet.replace(NoteEditActivity.TAG_CHECKED, "").replace(
                 NoteEditActivity.TAG_UNCHECKED, "");
         mType = cursor.getInt(TYPE_COLUMN);
         mWidgetId = cursor.getInt(WIDGET_ID_COLUMN);
         mWidgetType = cursor.getInt(WIDGET_TYPE_COLUMN);
 
+        // 初始化通话记录相关字段
         mPhoneNumber = "";
+        // 如果是通话记录文件夹中的笔记
         if (mParentId == Notes.ID_CALL_RECORD_FOLDER) {
+            // 根据笔记ID获取电话号码
             mPhoneNumber = DataUtils.getCallNumberByNoteId(context.getContentResolver(), mId);
             if (!TextUtils.isEmpty(mPhoneNumber)) {
+                // 根据电话号码获取联系人姓名
                 mName = Contact.getContact(context, mPhoneNumber);
                 if (mName == null) {
+                    // 如果找不到联系人，使用电话号码作为名称
                     mName = mPhoneNumber;
                 }
             }
         }
 
+        // 确保名称不为null
         if (mName == null) {
             mName = "";
         }
+
+        // 检查当前项在列表中的位置状态
         checkPostion(cursor);
     }
 
+    /**
+     * 检查当前项在列表中的位置状态
+     * @param cursor 数据库游标
+     */
     private void checkPostion(Cursor cursor) {
+        // 设置基础位置标识
         mIsLastItem = cursor.isLast() ? true : false;
         mIsFirstItem = cursor.isFirst() ? true : false;
         mIsOnlyOneItem = (cursor.getCount() == 1);
+
+        // 初始化文件夹相关标识
         mIsMultiNotesFollowingFolder = false;
         mIsOneNoteFollowingFolder = false;
 
+        // 如果是笔记类型且不是第一项，检查前一项是否为文件夹
         if (mType == Notes.TYPE_NOTE && !mIsFirstItem) {
             int position = cursor.getPosition();
+            // 移动到前一项
             if (cursor.moveToPrevious()) {
+                // 检查前一项是否是文件夹或系统文件夹
                 if (cursor.getInt(TYPE_COLUMN) == Notes.TYPE_FOLDER
                         || cursor.getInt(TYPE_COLUMN) == Notes.TYPE_SYSTEM) {
+                    // 判断是单个笔记还是多个笔记跟随文件夹
                     if (cursor.getCount() > (position + 1)) {
-                        mIsMultiNotesFollowingFolder = true;
+                        mIsMultiNotesFollowingFolder = true; // 多个笔记跟随文件夹
                     } else {
-                        mIsOneNoteFollowingFolder = true;
+                        mIsOneNoteFollowingFolder = true; // 单个笔记跟随文件夹
                     }
                 }
+                // 移回当前位置
                 if (!cursor.moveToNext()) {
                     throw new IllegalStateException("cursor move to previous but can't move back");
                 }
@@ -134,91 +171,180 @@ public class NoteItemData {
         }
     }
 
+    /**
+     * 判断是否是单个笔记跟随在文件夹后
+     * @return 如果是单个笔记跟随文件夹则返回true
+     */
     public boolean isOneFollowingFolder() {
         return mIsOneNoteFollowingFolder;
     }
 
+    /**
+     * 判断是否是多个笔记跟随在文件夹后
+     * @return 如果是多个笔记跟随文件夹则返回true
+     */
     public boolean isMultiFollowingFolder() {
         return mIsMultiNotesFollowingFolder;
     }
 
+    /**
+     * 判断是否是列表中的最后一项
+     * @return 如果是最后一项则返回true
+     */
     public boolean isLast() {
         return mIsLastItem;
     }
 
+    /**
+     * 获取通话记录的联系人姓名
+     * @return 联系人姓名
+     */
     public String getCallName() {
         return mName;
     }
 
+    /**
+     * 判断是否是列表中的第一项
+     * @return 如果是第一项则返回true
+     */
     public boolean isFirst() {
         return mIsFirstItem;
     }
 
+    /**
+     * 判断是否是列表中的唯一项
+     * @return 如果只有一项则返回true
+     */
     public boolean isSingle() {
         return mIsOnlyOneItem;
     }
 
+    /**
+     * 获取笔记ID
+     * @return 笔记ID
+     */
     public long getId() {
         return mId;
     }
 
+    /**
+     * 获取提醒时间
+     * @return 提醒时间戳
+     */
     public long getAlertDate() {
         return mAlertDate;
     }
 
+    /**
+     * 获取创建时间
+     * @return 创建时间戳
+     */
     public long getCreatedDate() {
         return mCreatedDate;
     }
 
+    /**
+     * 判断是否有附件
+     * @return 有附件返回true
+     */
     public boolean hasAttachment() {
         return mHasAttachment;
     }
 
+    /**
+     * 获取修改时间
+     * @return 修改时间戳
+     */
     public long getModifiedDate() {
         return mModifiedDate;
     }
 
+    /**
+     * 获取背景颜色ID
+     * @return 背景颜色ID
+     */
     public int getBgColorId() {
         return mBgColorId;
     }
 
+    /**
+     * 获取父文件夹ID
+     * @return 父文件夹ID
+     */
     public long getParentId() {
         return mParentId;
     }
 
+    /**
+     * 获取笔记数量（对文件夹类型有效）
+     * @return 包含的笔记数量
+     */
     public int getNotesCount() {
         return mNotesCount;
     }
 
+    /**
+     * 获取文件夹ID（与getParentId相同）
+     * @return 文件夹ID
+     */
     public long getFolderId () {
         return mParentId;
     }
 
+    /**
+     * 获取笔记类型
+     * @return 笔记类型（笔记、文件夹、系统文件夹等）
+     */
     public int getType() {
         return mType;
     }
 
+    /**
+     * 获取小部件类型
+     * @return 小部件类型
+     */
     public int getWidgetType() {
         return mWidgetType;
     }
 
+    /**
+     * 获取小部件ID
+     * @return 小部件ID
+     */
     public int getWidgetId() {
         return mWidgetId;
     }
 
+    /**
+     * 获取内容摘要
+     * @return 内容摘要字符串
+     */
     public String getSnippet() {
         return mSnippet;
     }
 
+    /**
+     * 判断是否有提醒
+     * @return 有提醒返回true
+     */
     public boolean hasAlert() {
         return (mAlertDate > 0);
     }
 
+    /**
+     * 判断是否是通话记录
+     * @return 如果是通话记录返回true
+     */
     public boolean isCallRecord() {
         return (mParentId == Notes.ID_CALL_RECORD_FOLDER && !TextUtils.isEmpty(mPhoneNumber));
     }
 
+    /**
+     * 静态方法：从游标获取笔记类型
+     * @param cursor 数据库游标
+     * @return 笔记类型
+     */
     public static int getNoteType(Cursor cursor) {
         return cursor.getInt(TYPE_COLUMN);
     }
-}
+}

src/notes/ui/NotesListActivity.java

@@ -78,92 +78,109 @@ import java.io.InputStream;
 import java.io.InputStreamReader;
 import java.util.HashSet;
 
+/**
+ * 笔记列表主界面Activity
+ * 显示所有笔记列表，支持笔记的增删改查、文件夹管理、批量操作等功能
+ */
 public class NotesListActivity extends Activity implements OnClickListener, OnItemLongClickListener {
-    private static final int FOLDER_NOTE_LIST_QUERY_TOKEN = 0;
+    // 查询令牌常量
-
+    private static final int FOLDER_NOTE_LIST_QUERY_TOKEN = 0; // 查询文件夹内笔记列表的令牌
-    private static final int FOLDER_LIST_QUERY_TOKEN      = 1;
+    private static final int FOLDER_LIST_QUERY_TOKEN      = 1; // 查询文件夹列表的令牌
-
-    private static final int MENU_FOLDER_DELETE = 0;
 
-    private static final int MENU_FOLDER_VIEW = 1;
+    // 上下文菜单项ID常量
-
+    private static final int MENU_FOLDER_DELETE = 0; // 文件夹删除菜单项
-    private static final int MENU_FOLDER_CHANGE_NAME = 2;
+    private static final int MENU_FOLDER_VIEW = 1;   // 文件夹查看菜单项
+    private static final int MENU_FOLDER_CHANGE_NAME = 2; // 文件夹改名菜单项
 
+    // 首次使用引导标记的偏好设置键
     private static final String PREFERENCE_ADD_INTRODUCTION = "net.micode.notes.introduction";
 
+    /**
+     * 列表编辑状态枚举
+     */
     private enum ListEditState {
-        NOTE_LIST, SUB_FOLDER, CALL_RECORD_FOLDER
+        NOTE_LIST,          // 普通笔记列表状态
+        SUB_FOLDER,         // 子文件夹浏览状态
+        CALL_RECORD_FOLDER  // 通话记录文件夹浏览状态
     };
 
+    // 当前列表状态
     private ListEditState mState;
-
+    // 异步查询处理器
     private BackgroundQueryHandler mBackgroundQueryHandler;
-
+    // 笔记列表适配器
     private NotesListAdapter mNotesListAdapter;
-
+    // 笔记列表视图
     private ListView mNotesListView;
-
+    // 新建笔记按钮
     private Button mAddNewNote;
-
+    // 触摸事件分发标记
     private boolean mDispatch;
-
+    // 触摸起始Y坐标
     private int mOriginY;
-
+    // 触摸分发Y坐标
     private int mDispatchY;
-
+    // 标题栏
     private TextView mTitleBar;
-
+    // 当前文件夹ID
     private long mCurrentFolderId;
-
+    // 内容解析器
     private ContentResolver mContentResolver;
-
+    // 多选模式回调
     private ModeCallback mModeCallBack;
-
+    // 日志标签
     private static final String TAG = "NotesListActivity";
-
+    // 列表滚动速率
     public static final int NOTES_LISTVIEW_SCROLL_RATE = 30;
-
+    // 长按焦点笔记数据项
     private NoteItemData mFocusNoteDataItem;
 
+    // 普通查询条件（非根文件夹）
     private static final String NORMAL_SELECTION = NoteColumns.PARENT_ID + "=?";
-
+    // 根文件夹查询条件（包含通话记录文件夹）
     private static final String ROOT_FOLDER_SELECTION = "(" + NoteColumns.TYPE + "<>"
             + Notes.TYPE_SYSTEM + " AND " + NoteColumns.PARENT_ID + "=?)" + " OR ("
             + NoteColumns.ID + "=" + Notes.ID_CALL_RECORD_FOLDER + " AND "
             + NoteColumns.NOTES_COUNT + ">0)";
 
-    private final static int REQUEST_CODE_OPEN_NODE = 102;
+    // 请求码常量
-    private final static int REQUEST_CODE_NEW_NODE  = 103;
+    private final static int REQUEST_CODE_OPEN_NODE = 102; // 打开笔记请求码
+    private final static int REQUEST_CODE_NEW_NODE  = 103; // 新建笔记请求码
 
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
-        setContentView(R.layout.note_list);
+        setContentView(R.layout.note_list); // 设置布局文件
-        initResources();
+        initResources(); // 初始化资源
 
-        /**
+        // 首次使用时插入应用介绍笔记
-         * Insert an introduction when user firstly use this application
-         */
         setAppInfoFromRawRes();
     }
 
     @Override
     protected void onActivityResult(int requestCode, int resultCode, Intent data) {
+        // 处理笔记编辑返回结果
         if (resultCode == RESULT_OK
                 && (requestCode == REQUEST_CODE_OPEN_NODE || requestCode == REQUEST_CODE_NEW_NODE)) {
+            // 清空适配器游标以触发重新查询
             mNotesListAdapter.changeCursor(null);
         } else {
             super.onActivityResult(requestCode, resultCode, data);
         }
     }
 
+    /**
+     * 从raw资源中读取并创建应用介绍笔记
+     */
     private void setAppInfoFromRawRes() {
         SharedPreferences sp = PreferenceManager.getDefaultSharedPreferences(this);
+        // 检查是否已添加过介绍笔记
         if (!sp.getBoolean(PREFERENCE_ADD_INTRODUCTION, false)) {
             StringBuilder sb = new StringBuilder();
             InputStream in = null;
             try {
-                 in = getResources().openRawResource(R.raw.introduction);
+                // 从raw资源读取介绍文件
+                in = getResources().openRawResource(R.raw.introduction);
                 if (in != null) {
                     InputStreamReader isr = new InputStreamReader(in);
                     BufferedReader br = new BufferedReader(isr);
@@ -184,17 +201,18 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                     try {
                         in.close();
                     } catch (IOException e) {
-                        // TODO Auto-generated catch block
                         e.printStackTrace();
                     }
                 }
             }
 
+            // 创建空白笔记并设置介绍文本
             WorkingNote note = WorkingNote.createEmptyNote(this, Notes.ID_ROOT_FOLDER,
                     AppWidgetManager.INVALID_APPWIDGET_ID, Notes.TYPE_WIDGET_INVALIDE,
                     ResourceParser.RED);
             note.setWorkingText(sb.toString());
             if (note.saveNote()) {
+                // 保存标记，避免重复添加
                 sp.edit().putBoolean(PREFERENCE_ADD_INTRODUCTION, true).commit();
             } else {
                 Log.e(TAG, "Save introduction note error");
@@ -206,14 +224,19 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
     @Override
     protected void onStart() {
         super.onStart();
+        // 启动异步查询笔记列表
         startAsyncNotesListQuery();
     }
 
+    /**
+     * 初始化资源
+     */
     private void initResources() {
         mContentResolver = this.getContentResolver();
         mBackgroundQueryHandler = new BackgroundQueryHandler(this.getContentResolver());
-        mCurrentFolderId = Notes.ID_ROOT_FOLDER;
+        mCurrentFolderId = Notes.ID_ROOT_FOLDER; // 初始化为根文件夹
         mNotesListView = (ListView) findViewById(R.id.notes_list);
+        // 添加列表底部视图
         mNotesListView.addFooterView(LayoutInflater.from(this).inflate(R.layout.note_list_footer, null),
                 null, false);
         mNotesListView.setOnItemClickListener(new OnListItemClickListener());
@@ -222,24 +245,31 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         mNotesListView.setAdapter(mNotesListAdapter);
         mAddNewNote = (Button) findViewById(R.id.btn_new_note);
         mAddNewNote.setOnClickListener(this);
-        mAddNewNote.setOnTouchListener(new NewNoteOnTouchListener());
+        mAddNewNote.setOnTouchListener(new NewNoteOnTouchListener()); // 设置特殊触摸监听器
         mDispatch = false;
         mDispatchY = 0;
         mOriginY = 0;
         mTitleBar = (TextView) findViewById(R.id.tv_title_bar);
-        mState = ListEditState.NOTE_LIST;
+        mState = ListEditState.NOTE_LIST; // 初始状态为普通笔记列表
-        mModeCallBack = new ModeCallback();
+        mModeCallBack = new ModeCallback(); // 多选模式回调
     }
 
+    /**
+     * 多选模式回调类
+     * 实现ListView的多选操作模式
+     */
     private class ModeCallback implements ListView.MultiChoiceModeListener, OnMenuItemClickListener {
-        private DropdownMenu mDropDownMenu;
+        private DropdownMenu mDropDownMenu; // 下拉菜单
-        private ActionMode mActionMode;
+        private ActionMode mActionMode;     // 动作模式
-        private MenuItem mMoveMenu;
+        private MenuItem mMoveMenu;         // 移动菜单项
 
+        @Override
         public boolean onCreateActionMode(ActionMode mode, Menu menu) {
+            // 加载操作模式菜单
             getMenuInflater().inflate(R.menu.note_list_options, menu);
             menu.findItem(R.id.delete).setOnMenuItemClickListener(this);
             mMoveMenu = menu.findItem(R.id.move);
+            // 根据条件设置移动菜单可见性
             if (mFocusNoteDataItem.getParentId() == Notes.ID_CALL_RECORD_FOLDER
                     || DataUtils.getUserFolderCount(mContentResolver) == 0) {
                 mMoveMenu.setVisible(false);
@@ -248,10 +278,11 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                 mMoveMenu.setOnMenuItemClickListener(this);
             }
             mActionMode = mode;
-            mNotesListAdapter.setChoiceMode(true);
+            mNotesListAdapter.setChoiceMode(true); // 进入多选模式
-            mNotesListView.setLongClickable(false);
+            mNotesListView.setLongClickable(false); // 禁用长按
-            mAddNewNote.setVisibility(View.GONE);
+            mAddNewNote.setVisibility(View.GONE); // 隐藏新建笔记按钮
 
+            // 设置自定义视图（包含下拉菜单）
             View customView = LayoutInflater.from(NotesListActivity.this).inflate(
                     R.layout.note_list_dropdown_menu, null);
             mode.setCustomView(customView);
@@ -259,19 +290,23 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                     (Button) customView.findViewById(R.id.selection_menu),
                     R.menu.note_list_dropdown);
             mDropDownMenu.setOnDropdownMenuItemClickListener(new PopupMenu.OnMenuItemClickListener(){
+                @Override
                 public boolean onMenuItemClick(MenuItem item) {
+                    // 全选/取消全选功能
                     mNotesListAdapter.selectAll(!mNotesListAdapter.isAllSelected());
                     updateMenu();
                     return true;
                 }
-
             });
             return true;
         }
 
+        /**
+         * 更新菜单状态
+         */
         private void updateMenu() {
             int selectedCount = mNotesListAdapter.getSelectedCount();
-            // Update dropdown menu
+            // 更新下拉菜单标题（显示选中数量）
             String format = getResources().getString(R.string.menu_select_title, selectedCount);
             mDropDownMenu.setTitle(format);
             MenuItem item = mDropDownMenu.findItem(R.id.action_select_all);
@@ -286,32 +321,40 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
             }
         }
 
+        @Override
         public boolean onPrepareActionMode(ActionMode mode, Menu menu) {
-            // TODO Auto-generated method stub
             return false;
         }
 
+        @Override
         public boolean onActionItemClicked(ActionMode mode, MenuItem item) {
-            // TODO Auto-generated method stub
             return false;
         }
 
+        @Override
         public void onDestroyActionMode(ActionMode mode) {
+            // 退出多选模式
             mNotesListAdapter.setChoiceMode(false);
             mNotesListView.setLongClickable(true);
             mAddNewNote.setVisibility(View.VISIBLE);
         }
 
+        /**
+         * 结束动作模式
+         */
         public void finishActionMode() {
             mActionMode.finish();
         }
 
+        @Override
         public void onItemCheckedStateChanged(ActionMode mode, int position, long id,
-                boolean checked) {
+                                              boolean checked) {
+            // 选中状态变化时更新
             mNotesListAdapter.setCheckedItem(position, checked);
             updateMenu();
         }
 
+        @Override
         public boolean onMenuItemClick(MenuItem item) {
             if (mNotesListAdapter.getSelectedCount() == 0) {
                 Toast.makeText(NotesListActivity.this, getString(R.string.menu_select_none),
@@ -321,22 +364,25 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
 
             switch (item.getItemId()) {
                 case R.id.delete:
+                    // 批量删除确认对话框
                     AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this);
                     builder.setTitle(getString(R.string.alert_title_delete));
                     builder.setIcon(android.R.drawable.ic_dialog_alert);
                     builder.setMessage(getString(R.string.alert_message_delete_notes,
-                                             mNotesListAdapter.getSelectedCount()));
+                            mNotesListAdapter.getSelectedCount()));
                     builder.setPositiveButton(android.R.string.ok,
-                                             new DialogInterface.OnClickListener() {
+                            new DialogInterface.OnClickListener() {
-                                                 public void onClick(DialogInterface dialog,
+                                @Override
-                                                         int which) {
+                                public void onClick(DialogInterface dialog,
-                                                     batchDelete();
+                                                    int which) {
-                                                 }
+                                    batchDelete(); // 执行批量删除
-                                             });
+                                }
+                            });
                     builder.setNegativeButton(android.R.string.cancel, null);
                     builder.show();
                     break;
                 case R.id.move:
+                    // 批量移动到文件夹
                     startQueryDestinationFolders();
                     break;
                 default:
@@ -346,8 +392,12 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         }
     }
 
+    /**
+     * 新建笔记按钮的特殊触摸监听器
+     * 处理按钮透明区域的触摸事件分发
+     */
     private class NewNoteOnTouchListener implements OnTouchListener {
-
+        @Override
         public boolean onTouch(View v, MotionEvent event) {
             switch (event.getAction()) {
                 case MotionEvent.ACTION_DOWN: {
@@ -356,21 +406,18 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                     int newNoteViewHeight = mAddNewNote.getHeight();
                     int start = screenHeight - newNoteViewHeight;
                     int eventY = start + (int) event.getY();
-                    /**
+
-                     * Minus TitleBar's height
+                    // 在子文件夹状态下减去标题栏高度
-                     */
                     if (mState == ListEditState.SUB_FOLDER) {
                         eventY -= mTitleBar.getHeight();
                         start -= mTitleBar.getHeight();
                     }
+
                     /**
-                     * HACKME:When click the transparent part of "New Note" button, dispatch
+                     * HACKME: 当点击"新建笔记"按钮的透明部分时，将事件分发到底层的列表视图
-                     * the event to the list view behind this button. The transparent part of
+                     * 透明部分的表达式：y = -0.12x + 94（单位：像素）
-                     * "New Note" button could be expressed by formula y=-0.12x+94（Unit:pixel）
+                     * 94表示透明部分的最大高度
-                     * and the line top of the button. The coordinate based on left of the "New
+                     * 注意：如果按钮背景改变，公式也应相应改变
-                     * Note" button. The 94 represents maximum height of the transparent part.
-                     * Notice that, if the background of the button changes, the formula should
-                     * also change. This is very bad, just for the UI designer's strong requirement.
                      */
                     if (event.getY() < (event.getX() * (-0.12) + 94)) {
                         View view = mNotesListView.getChildAt(mNotesListView.getChildCount() - 1
@@ -405,18 +452,24 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
             }
             return false;
         }
+    }
 
-    };
+    /**
-
+     * 启动异步笔记列表查询
+     */
     private void startAsyncNotesListQuery() {
+        // 根据当前文件夹选择查询条件
         String selection = (mCurrentFolderId == Notes.ID_ROOT_FOLDER) ? ROOT_FOLDER_SELECTION
                 : NORMAL_SELECTION;
         mBackgroundQueryHandler.startQuery(FOLDER_NOTE_LIST_QUERY_TOKEN, null,
                 Notes.CONTENT_NOTE_URI, NoteItemData.PROJECTION, selection, new String[] {
-                    String.valueOf(mCurrentFolderId)
+                        String.valueOf(mCurrentFolderId)
                 }, NoteColumns.TYPE + " DESC," + NoteColumns.MODIFIED_DATE + " DESC");
     }
 
+    /**
+     * 后台查询处理器
+     */
     private final class BackgroundQueryHandler extends AsyncQueryHandler {
         public BackgroundQueryHandler(ContentResolver contentResolver) {
             super(contentResolver);
@@ -426,9 +479,11 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         protected void onQueryComplete(int token, Object cookie, Cursor cursor) {
             switch (token) {
                 case FOLDER_NOTE_LIST_QUERY_TOKEN:
+                    // 更新笔记列表适配器的游标
                     mNotesListAdapter.changeCursor(cursor);
                     break;
                 case FOLDER_LIST_QUERY_TOKEN:
+                    // 显示文件夹列表对话框
                     if (cursor != null && cursor.getCount() > 0) {
                         showFolderListMenu(cursor);
                     } else {
@@ -441,13 +496,17 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         }
     }
 
+    /**
+     * 显示文件夹列表选择菜单
+     */
     private void showFolderListMenu(Cursor cursor) {
         AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this);
         builder.setTitle(R.string.menu_title_select_folder);
         final FoldersListAdapter adapter = new FoldersListAdapter(this, cursor);
         builder.setAdapter(adapter, new DialogInterface.OnClickListener() {
-
+            @Override
             public void onClick(DialogInterface dialog, int which) {
+                // 批量移动笔记到选定文件夹
                 DataUtils.batchMoveToFolder(mContentResolver,
                         mNotesListAdapter.getSelectedItemIds(), adapter.getItemId(which));
                 Toast.makeText(
@@ -456,12 +515,15 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                                 mNotesListAdapter.getSelectedCount(),
                                 adapter.getFolderName(NotesListActivity.this, which)),
                         Toast.LENGTH_SHORT).show();
-                mModeCallBack.finishActionMode();
+                mModeCallBack.finishActionMode(); // 结束多选模式
             }
         });
         builder.show();
     }
 
+    /**
+     * 创建新笔记
+     */
     private void createNewNote() {
         Intent intent = new Intent(this, NoteEditActivity.class);
         intent.setAction(Intent.ACTION_INSERT_OR_EDIT);
@@ -469,20 +531,25 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         this.startActivityForResult(intent, REQUEST_CODE_NEW_NODE);
     }
 
+    /**
+     * 批量删除笔记
+     */
     private void batchDelete() {
         new AsyncTask<Void, Void, HashSet<AppWidgetAttribute>>() {
+            @Override
             protected HashSet<AppWidgetAttribute> doInBackground(Void... unused) {
+                // 获取选中笔记的小部件属性
                 HashSet<AppWidgetAttribute> widgets = mNotesListAdapter.getSelectedWidget();
                 if (!isSyncMode()) {
-                    // if not synced, delete notes directly
+                    // 非同步模式下直接删除笔记
                     if (DataUtils.batchDeleteNotes(mContentResolver, mNotesListAdapter
                             .getSelectedItemIds())) {
+                        // 删除成功
                     } else {
                         Log.e(TAG, "Delete notes error, should not happens");
                     }
                 } else {
-                    // in sync mode, we'll move the deleted note into the trash
+                    // 同步模式下将笔记移动到回收站
-                    // folder
                     if (!DataUtils.batchMoveToFolder(mContentResolver, mNotesListAdapter
                             .getSelectedItemIds(), Notes.ID_TRASH_FOLER)) {
                         Log.e(TAG, "Move notes to trash folder error, should not happens");
@@ -493,6 +560,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
 
             @Override
             protected void onPostExecute(HashSet<AppWidgetAttribute> widgets) {
+                // 更新相关小部件
                 if (widgets != null) {
                     for (AppWidgetAttribute widget : widgets) {
                         if (widget.widgetId != AppWidgetManager.INVALID_APPWIDGET_ID
@@ -501,11 +569,14 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                         }
                     }
                 }
-                mModeCallBack.finishActionMode();
+                mModeCallBack.finishActionMode(); // 结束多选模式
             }
         }.execute();
     }
 
+    /**
+     * 删除文件夹
+     */
     private void deleteFolder(long folderId) {
         if (folderId == Notes.ID_ROOT_FOLDER) {
             Log.e(TAG, "Wrong folder id, should not happen " + folderId);
@@ -514,15 +585,17 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
 
         HashSet<Long> ids = new HashSet<Long>();
         ids.add(folderId);
+        // 获取文件夹内笔记的小部件属性
         HashSet<AppWidgetAttribute> widgets = DataUtils.getFolderNoteWidget(mContentResolver,
                 folderId);
         if (!isSyncMode()) {
-            // if not synced, delete folder directly
+            // 非同步模式下直接删除文件夹
             DataUtils.batchDeleteNotes(mContentResolver, ids);
         } else {
-            // in sync mode, we'll move the deleted folder into the trash folder
+            // 同步模式下将文件夹移动到回收站
             DataUtils.batchMoveToFolder(mContentResolver, ids, Notes.ID_TRASH_FOLER);
         }
+        // 更新相关小部件
         if (widgets != null) {
             for (AppWidgetAttribute widget : widgets) {
                 if (widget.widgetId != AppWidgetManager.INVALID_APPWIDGET_ID
@@ -533,6 +606,9 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         }
     }
 
+    /**
+     * 打开笔记进行编辑
+     */
     private void openNode(NoteItemData data) {
         Intent intent = new Intent(this, NoteEditActivity.class);
         intent.setAction(Intent.ACTION_VIEW);
@@ -540,15 +616,20 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         this.startActivityForResult(intent, REQUEST_CODE_OPEN_NODE);
     }
 
+    /**
+     * 打开文件夹浏览
+     */
     private void openFolder(NoteItemData data) {
         mCurrentFolderId = data.getId();
-        startAsyncNotesListQuery();
+        startAsyncNotesListQuery(); // 查询文件夹内容
+        // 根据文件夹类型设置状态
         if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) {
             mState = ListEditState.CALL_RECORD_FOLDER;
-            mAddNewNote.setVisibility(View.GONE);
+            mAddNewNote.setVisibility(View.GONE); // 通话记录文件夹不能新建笔记
         } else {
             mState = ListEditState.SUB_FOLDER;
         }
+        // 设置标题栏
         if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) {
             mTitleBar.setText(R.string.call_record_folder_name);
         } else {
@@ -557,16 +638,20 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         mTitleBar.setVisibility(View.VISIBLE);
     }
 
+    @Override
     public void onClick(View v) {
         switch (v.getId()) {
             case R.id.btn_new_note:
-                createNewNote();
+                createNewNote(); // 创建新笔记
                 break;
             default:
                 break;
         }
     }
 
+    /**
+     * 显示软键盘
+     */
     private void showSoftInput() {
         InputMethodManager inputMethodManager = (InputMethodManager) getSystemService(Context.INPUT_METHOD_SERVICE);
         if (inputMethodManager != null) {
@@ -574,16 +659,23 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         }
     }
 
+    /**
+     * 隐藏软键盘
+     */
     private void hideSoftInput(View view) {
         InputMethodManager inputMethodManager = (InputMethodManager) getSystemService(Context.INPUT_METHOD_SERVICE);
         inputMethodManager.hideSoftInputFromWindow(view.getWindowToken(), 0);
     }
 
+    /**
+     * 显示创建或修改文件夹对话框
+     */
     private void showCreateOrModifyFolderDialog(final boolean create) {
         final AlertDialog.Builder builder = new AlertDialog.Builder(this);
         View view = LayoutInflater.from(this).inflate(R.layout.dialog_edit_text, null);
         final EditText etName = (EditText) view.findViewById(R.id.et_foler_name);
-        showSoftInput();
+        showSoftInput(); // 显示软键盘
+        // 根据创建/修改模式设置初始值
         if (!create) {
             if (mFocusNoteDataItem != null) {
                 etName.setText(mFocusNoteDataItem.getSnippet());
@@ -599,17 +691,20 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
 
         builder.setPositiveButton(android.R.string.ok, null);
         builder.setNegativeButton(android.R.string.cancel, new DialogInterface.OnClickListener() {
+            @Override
             public void onClick(DialogInterface dialog, int which) {
-                hideSoftInput(etName);
+                hideSoftInput(etName); // 隐藏软键盘
             }
         });
 
         final Dialog dialog = builder.setView(view).show();
         final Button positive = (Button)dialog.findViewById(android.R.id.button1);
         positive.setOnClickListener(new OnClickListener() {
+            @Override
             public void onClick(View v) {
                 hideSoftInput(etName);
                 String name = etName.getText().toString();
+                // 检查文件夹名是否已存在
                 if (DataUtils.checkVisibleFolderName(mContentResolver, name)) {
                     Toast.makeText(NotesListActivity.this, getString(R.string.folder_exist, name),
                             Toast.LENGTH_LONG).show();
@@ -617,6 +712,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                     return;
                 }
                 if (!create) {
+                    // 修改文件夹名称
                     if (!TextUtils.isEmpty(name)) {
                         ContentValues values = new ContentValues();
                         values.put(NoteColumns.SNIPPET, name);
@@ -624,10 +720,11 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                         values.put(NoteColumns.LOCAL_MODIFIED, 1);
                         mContentResolver.update(Notes.CONTENT_NOTE_URI, values, NoteColumns.ID
                                 + "=?", new String[] {
-                            String.valueOf(mFocusNoteDataItem.getId())
+                                String.valueOf(mFocusNoteDataItem.getId())
                         });
                     }
                 } else if (!TextUtils.isEmpty(name)) {
+                    // 创建新文件夹
                     ContentValues values = new ContentValues();
                     values.put(NoteColumns.SNIPPET, name);
                     values.put(NoteColumns.TYPE, Notes.TYPE_FOLDER);
@@ -637,18 +734,17 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
             }
         });
 
+        // 初始状态下，如果名称为空，禁用确认按钮
         if (TextUtils.isEmpty(etName.getText())) {
             positive.setEnabled(false);
         }
-        /**
+        // 监听文本变化，动态启用/禁用确认按钮
-         * When the name edit text is null, disable the positive button
-         */
         etName.addTextChangedListener(new TextWatcher() {
+            @Override
             public void beforeTextChanged(CharSequence s, int start, int count, int after) {
-                // TODO Auto-generated method stub
-
             }
 
+            @Override
             public void onTextChanged(CharSequence s, int start, int before, int count) {
                 if (TextUtils.isEmpty(etName.getText())) {
                     positive.setEnabled(false);
@@ -657,15 +753,15 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                 }
             }
 
+            @Override
             public void afterTextChanged(Editable s) {
-                // TODO Auto-generated method stub
-
             }
         });
     }
 
     @Override
     public void onBackPressed() {
+        // 处理返回键，根据当前状态返回上一级或退出
         switch (mState) {
             case SUB_FOLDER:
                 mCurrentFolderId = Notes.ID_ROOT_FOLDER;
@@ -688,8 +784,12 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         }
     }
 
+    /**
+     * 更新小部件
+     */
     private void updateWidget(int appWidgetId, int appWidgetType) {
         Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_UPDATE);
+        // 根据小部件类型选择对应的Provider
         if (appWidgetType == Notes.TYPE_WIDGET_2X) {
             intent.setClass(this, NoteWidgetProvider_2x.class);
         } else if (appWidgetType == Notes.TYPE_WIDGET_4X) {
@@ -700,17 +800,21 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         }
 
         intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS, new int[] {
-            appWidgetId
+                appWidgetId
         });
 
         sendBroadcast(intent);
         setResult(RESULT_OK, intent);
     }
 
+    /**
+     * 文件夹长按上下文菜单监听器
+     */
     private final OnCreateContextMenuListener mFolderOnCreateContextMenuListener = new OnCreateContextMenuListener() {
+        @Override
         public void onCreateContextMenu(ContextMenu menu, View v, ContextMenuInfo menuInfo) {
             if (mFocusNoteDataItem != null) {
-                menu.setHeaderTitle(mFocusNoteDataItem.getSnippet());
+                menu.setHeaderTitle(mFocusNoteDataItem.getSnippet()); // 设置菜单标题为文件夹名
                 menu.add(0, MENU_FOLDER_VIEW, 0, R.string.menu_folder_view);
                 menu.add(0, MENU_FOLDER_DELETE, 0, R.string.menu_folder_delete);
                 menu.add(0, MENU_FOLDER_CHANGE_NAME, 0, R.string.menu_folder_change_name);
@@ -721,7 +825,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
     @Override
     public void onContextMenuClosed(Menu menu) {
         if (mNotesListView != null) {
-            mNotesListView.setOnCreateContextMenuListener(null);
+            mNotesListView.setOnCreateContextMenuListener(null); // 清除上下文菜单监听器
         }
         super.onContextMenuClosed(menu);
     }
@@ -734,24 +838,26 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         }
         switch (item.getItemId()) {
             case MENU_FOLDER_VIEW:
-                openFolder(mFocusNoteDataItem);
+                openFolder(mFocusNoteDataItem); // 打开文件夹
                 break;
             case MENU_FOLDER_DELETE:
+                // 显示删除文件夹确认对话框
                 AlertDialog.Builder builder = new AlertDialog.Builder(this);
                 builder.setTitle(getString(R.string.alert_title_delete));
                 builder.setIcon(android.R.drawable.ic_dialog_alert);
                 builder.setMessage(getString(R.string.alert_message_delete_folder));
                 builder.setPositiveButton(android.R.string.ok,
                         new DialogInterface.OnClickListener() {
+                            @Override
                             public void onClick(DialogInterface dialog, int which) {
-                                deleteFolder(mFocusNoteDataItem.getId());
+                                deleteFolder(mFocusNoteDataItem.getId()); // 删除文件夹
                             }
                         });
                 builder.setNegativeButton(android.R.string.cancel, null);
                 builder.show();
                 break;
             case MENU_FOLDER_CHANGE_NAME:
-                showCreateOrModifyFolderDialog(false);
+                showCreateOrModifyFolderDialog(false); // 显示修改文件夹名对话框
                 break;
             default:
                 break;
@@ -763,9 +869,10 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
     @Override
     public boolean onPrepareOptionsMenu(Menu menu) {
         menu.clear();
+        // 根据当前状态加载不同的菜单
         if (mState == ListEditState.NOTE_LIST) {
             getMenuInflater().inflate(R.menu.note_list, menu);
-            // set sync or sync_cancel
+            // 根据同步状态设置同步菜单项标题
             menu.findItem(R.id.menu_sync).setTitle(
                     GTaskSyncService.isSyncing() ? R.string.menu_sync_cancel : R.string.menu_sync);
         } else if (mState == ListEditState.SUB_FOLDER) {
@@ -781,36 +888,32 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
     @Override
     public boolean onOptionsItemSelected(MenuItem item) {
         switch (item.getItemId()) {
-            case R.id.menu_new_folder: {
+            case R.id.menu_new_folder:
-                showCreateOrModifyFolderDialog(true);
+                showCreateOrModifyFolderDialog(true); // 创建新文件夹
                 break;
-            }
+            case R.id.menu_export_text:
-            case R.id.menu_export_text: {
+                exportNoteToText(); // 导出笔记为文本
-                exportNoteToText();
                 break;
-            }
+            case R.id.menu_sync:
-            case R.id.menu_sync: {
+                // 同步功能处理
                 if (isSyncMode()) {
                     if (TextUtils.equals(item.getTitle(), getString(R.string.menu_sync))) {
-                        GTaskSyncService.startSync(this);
+                        GTaskSyncService.startSync(this); // 开始同步
                     } else {
-                        GTaskSyncService.cancelSync(this);
+                        GTaskSyncService.cancelSync(this); // 取消同步
                     }
                 } else {
-                    startPreferenceActivity();
+                    startPreferenceActivity(); // 未设置同步账户，跳转到设置
                 }
                 break;
-            }
+            case R.id.menu_setting:
-            case R.id.menu_setting: {
+                startPreferenceActivity(); // 打开设置
-                startPreferenceActivity();
                 break;
-            }
+            case R.id.menu_new_note:
-            case R.id.menu_new_note: {
+                createNewNote(); // 新建笔记
-                createNewNote();
                 break;
-            }
             case R.id.menu_search:
-                onSearchRequested();
+                onSearchRequested(); // 触发搜索
                 break;
             default:
                 break;
@@ -824,17 +927,20 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
         return true;
     }
 
+    /**
+     * 导出笔记为文本文件
+     */
     private void exportNoteToText() {
         final BackupUtils backup = BackupUtils.getInstance(NotesListActivity.this);
         new AsyncTask<Void, Void, Integer>() {
-
             @Override
             protected Integer doInBackground(Void... unused) {
-                return backup.exportToText();
+                return backup.exportToText(); // 执行导出操作
             }
 
             @Override
             protected void onPostExecute(Integer result) {
+                // 根据导出结果显示不同提示
                 if (result == BackupUtils.STATE_SD_CARD_UNMOUONTED) {
                     AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this);
                     builder.setTitle(NotesListActivity.this
@@ -862,25 +968,34 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                     builder.show();
                 }
             }
-
         }.execute();
     }
 
+    /**
+     * 检查是否处于同步模式
+     */
     private boolean isSyncMode() {
         return NotesPreferenceActivity.getSyncAccountName(this).trim().length() > 0;
     }
 
+    /**
+     * 启动设置界面
+     */
     private void startPreferenceActivity() {
         Activity from = getParent() != null ? getParent() : this;
         Intent intent = new Intent(from, NotesPreferenceActivity.class);
         from.startActivityIfNeeded(intent, -1);
     }
 
+    /**
+     * 列表项点击监听器
+     */
     private class OnListItemClickListener implements OnItemClickListener {
-
+        @Override
         public void onItemClick(AdapterView<?> parent, View view, int position, long id) {
             if (view instanceof NotesListItem) {
                 NoteItemData item = ((NotesListItem) view).getItemData();
+                // 如果在多选模式下，处理选中状态
                 if (mNotesListAdapter.isInChoiceMode()) {
                     if (item.getType() == Notes.TYPE_NOTE) {
                         position = position - mNotesListView.getHeaderViewsCount();
@@ -890,13 +1005,14 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                     return;
                 }
 
+                // 根据当前状态处理点击事件
                 switch (mState) {
                     case NOTE_LIST:
                         if (item.getType() == Notes.TYPE_FOLDER
                                 || item.getType() == Notes.TYPE_SYSTEM) {
-                            openFolder(item);
+                            openFolder(item); // 打开文件夹
                         } else if (item.getType() == Notes.TYPE_NOTE) {
-                            openNode(item);
+                            openNode(item); // 打开笔记
                         } else {
                             Log.e(TAG, "Wrong note type in NOTE_LIST");
                         }
@@ -904,7 +1020,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                     case SUB_FOLDER:
                     case CALL_RECORD_FOLDER:
                         if (item.getType() == Notes.TYPE_NOTE) {
-                            openNode(item);
+                            openNode(item); // 打开笔记
                         } else {
                             Log.e(TAG, "Wrong note type in SUB_FOLDER");
                         }
@@ -914,13 +1030,17 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                 }
             }
         }
-
     }
 
+    /**
+     * 查询目标文件夹列表（用于批量移动）
+     */
     private void startQueryDestinationFolders() {
+        // 构造查询条件，排除回收站和当前文件夹
         String selection = NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>? AND " + NoteColumns.ID + "<>?";
+        // 如果不在根文件夹状态，允许移动到根文件夹
         selection = (mState == ListEditState.NOTE_LIST) ? selection:
-            "(" + selection + ") OR (" + NoteColumns.ID + "=" + Notes.ID_ROOT_FOLDER + ")";
+                "(" + selection + ") OR (" + NoteColumns.ID + "=" + Notes.ID_ROOT_FOLDER + ")";
 
         mBackgroundQueryHandler.startQuery(FOLDER_LIST_QUERY_TOKEN,
                 null,
@@ -935,9 +1055,11 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                 NoteColumns.MODIFIED_DATE + " DESC");
     }
 
+    @Override
     public boolean onItemLongClick(AdapterView<?> parent, View view, int position, long id) {
         if (view instanceof NotesListItem) {
             mFocusNoteDataItem = ((NotesListItem) view).getItemData();
+            // 笔记长按：启动多选模式
             if (mFocusNoteDataItem.getType() == Notes.TYPE_NOTE && !mNotesListAdapter.isInChoiceMode()) {
                 if (mNotesListView.startActionMode(mModeCallBack) != null) {
                     mModeCallBack.onItemCheckedStateChanged(null, position, id, true);
@@ -946,9 +1068,10 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                     Log.e(TAG, "startActionMode fails");
                 }
             } else if (mFocusNoteDataItem.getType() == Notes.TYPE_FOLDER) {
+                // 文件夹长按：显示上下文菜单
                 mNotesListView.setOnCreateContextMenuListener(mFolderOnCreateContextMenuListener);
             }
         }
         return false;
     }
-}
+}

src/notes/ui/NotesListAdapter.java

@@ -30,58 +30,94 @@ import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Iterator;
 
-
+/**
+ * 笔记列表适配器
+ * 用于将数据库游标数据绑定到ListView的适配器
+ * 支持多选模式和选中状态管理
+ */
 public class NotesListAdapter extends CursorAdapter {
-    private static final String TAG = "NotesListAdapter";
+    private static final String TAG = "NotesListAdapter"; // 日志标签
-    private Context mContext;
+    private Context mContext; // 上下文对象
-    private HashMap<Integer, Boolean> mSelectedIndex;
+    private HashMap<Integer, Boolean> mSelectedIndex; // 选中项索引映射表（位置->是否选中）
-    private int mNotesCount;
+    private int mNotesCount; // 笔记类型项的总数（不包含文件夹）
-    private boolean mChoiceMode;
+    private boolean mChoiceMode; // 是否处于多选模式
-
+
+    /**
+     * 小部件属性类
+     * 用于存储笔记关联的小部件信息
+     */
     public static class AppWidgetAttribute {
-        public int widgetId;
+        public int widgetId;   // 小部件ID
-        public int widgetType;
+        public int widgetType; // 小部件类型
     };
 
+    /**
+     * 构造函数
+     * @param context 上下文对象
+     */
     public NotesListAdapter(Context context) {
-        super(context, null);
+        super(context, null); // 初始游标为null
-        mSelectedIndex = new HashMap<Integer, Boolean>();
+        mSelectedIndex = new HashMap<Integer, Boolean>(); // 初始化选中索引映射表
         mContext = context;
-        mNotesCount = 0;
+        mNotesCount = 0; // 初始化笔记数量为0
     }
 
     @Override
     public View newView(Context context, Cursor cursor, ViewGroup parent) {
+        // 创建新的列表项视图
         return new NotesListItem(context);
     }
 
     @Override
     public void bindView(View view, Context context, Cursor cursor) {
+        // 绑定数据到视图
         if (view instanceof NotesListItem) {
+            // 从游标创建笔记数据项
             NoteItemData itemData = new NoteItemData(context, cursor);
+            // 绑定数据到列表项，传递是否处于多选模式和是否选中状态
             ((NotesListItem) view).bind(context, itemData, mChoiceMode,
                     isSelectedItem(cursor.getPosition()));
         }
     }
 
+    /**
+     * 设置指定位置项的选中状态
+     * @param position 列表位置
+     * @param checked 是否选中
+     */
     public void setCheckedItem(final int position, final boolean checked) {
-        mSelectedIndex.put(position, checked);
+        mSelectedIndex.put(position, checked); // 更新选中状态映射
-        notifyDataSetChanged();
+        notifyDataSetChanged(); // 通知数据变化，刷新视图
     }
 
+    /**
+     * 判断是否处于多选模式
+     * @return 如果是多选模式返回true
+     */
     public boolean isInChoiceMode() {
         return mChoiceMode;
     }
 
+    /**
+     * 设置多选模式
+     * @param mode true进入多选模式，false退出多选模式
+     */
     public void setChoiceMode(boolean mode) {
-        mSelectedIndex.clear();
+        mSelectedIndex.clear(); // 清空选中状态
-        mChoiceMode = mode;
+        mChoiceMode = mode; // 设置多选模式标志
     }
 
+    /**
+     * 全选或取消全选所有笔记项
+     * 注意：只对笔记类型有效，文件夹类型不会被选中
+     * @param checked true全选，false取消全选
+     */
     public void selectAll(boolean checked) {
-        Cursor cursor = getCursor();
+        Cursor cursor = getCursor(); // 获取当前游标
+        // 遍历所有项
         for (int i = 0; i < getCount(); i++) {
             if (cursor.moveToPosition(i)) {
+                // 只处理笔记类型，不处理文件夹类型
                 if (NoteItemData.getNoteType(cursor) == Notes.TYPE_NOTE) {
                     setCheckedItem(i, checked);
                 }
@@ -89,15 +125,21 @@ public class NotesListAdapter extends CursorAdapter {
         }
     }
 
+    /**
+     * 获取选中项的ID集合
+     * @return 选中项的ID集合
+     */
     public HashSet<Long> getSelectedItemIds() {
         HashSet<Long> itemSet = new HashSet<Long>();
+        // 遍历所有选中项
         for (Integer position : mSelectedIndex.keySet()) {
             if (mSelectedIndex.get(position) == true) {
-                Long id = getItemId(position);
+                Long id = getItemId(position); // 获取项的数据库ID
+                // 排除根文件夹ID（不应该被选中）
                 if (id == Notes.ID_ROOT_FOLDER) {
                     Log.d(TAG, "Wrong item id, should not happen");
                 } else {
-                    itemSet.add(id);
+                    itemSet.add(id); // 添加到集合
                 }
             }
         }
@@ -105,36 +147,46 @@ public class NotesListAdapter extends CursorAdapter {
         return itemSet;
     }
 
+    /**
+     * 获取选中项关联的小部件属性集合
+     * @return 小部件属性集合，如果发生错误返回null
+     */
     public HashSet<AppWidgetAttribute> getSelectedWidget() {
         HashSet<AppWidgetAttribute> itemSet = new HashSet<AppWidgetAttribute>();
+        // 遍历所有选中项
         for (Integer position : mSelectedIndex.keySet()) {
             if (mSelectedIndex.get(position) == true) {
-                Cursor c = (Cursor) getItem(position);
+                Cursor c = (Cursor) getItem(position); // 获取对应位置的游标
                 if (c != null) {
                     AppWidgetAttribute widget = new AppWidgetAttribute();
                     NoteItemData item = new NoteItemData(mContext, c);
-                    widget.widgetId = item.getWidgetId();
+                    widget.widgetId = item.getWidgetId(); // 设置小部件ID
-                    widget.widgetType = item.getWidgetType();
+                    widget.widgetType = item.getWidgetType(); // 设置小部件类型
                     itemSet.add(widget);
                     /**
-                     * Don't close cursor here, only the adapter could close it
+                     * 注意：不要在这里关闭游标，只有适配器可以关闭它
                      */
                 } else {
                     Log.e(TAG, "Invalid cursor");
-                    return null;
+                    return null; // 游标无效时返回null
                 }
             }
         }
         return itemSet;
     }
 
+    /**
+     * 获取选中项的数量
+     * @return 选中项的数量
+     */
     public int getSelectedCount() {
-        Collection<Boolean> values = mSelectedIndex.values();
+        Collection<Boolean> values = mSelectedIndex.values(); // 获取所有选中状态值
         if (null == values) {
             return 0;
         }
         Iterator<Boolean> iter = values.iterator();
         int count = 0;
+        // 统计选中状态为true的数量
         while (iter.hasNext()) {
             if (true == iter.next()) {
                 count++;
@@ -143,14 +195,23 @@ public class NotesListAdapter extends CursorAdapter {
         return count;
     }
 
+    /**
+     * 判断是否所有笔记项都被选中
+     * @return 如果所有笔记项都被选中且选中数量不为0，返回true
+     */
     public boolean isAllSelected() {
-        int checkedCount = getSelectedCount();
+        int checkedCount = getSelectedCount(); // 获取选中数量
-        return (checkedCount != 0 && checkedCount == mNotesCount);
+        return (checkedCount != 0 && checkedCount == mNotesCount); // 比较选中数量和笔记总数
     }
 
+    /**
+     * 判断指定位置项是否被选中
+     * @param position 列表位置
+     * @return 如果选中返回true，否则返回false
+     */
     public boolean isSelectedItem(final int position) {
         if (null == mSelectedIndex.get(position)) {
-            return false;
+            return false; // 映射表中不存在该位置，默认为未选中
         }
         return mSelectedIndex.get(position);
     }
@@ -158,27 +219,33 @@ public class NotesListAdapter extends CursorAdapter {
     @Override
     protected void onContentChanged() {
         super.onContentChanged();
-        calcNotesCount();
+        calcNotesCount(); // 内容变化时重新计算笔记数量
     }
 
     @Override
     public void changeCursor(Cursor cursor) {
         super.changeCursor(cursor);
-        calcNotesCount();
+        calcNotesCount(); // 游标变化时重新计算笔记数量
     }
 
+    /**
+     * 计算笔记类型项的数量（排除文件夹类型）
+     * 用于全选判断
+     */
     private void calcNotesCount() {
-        mNotesCount = 0;
+        mNotesCount = 0; // 重置计数
+        // 遍历所有项
         for (int i = 0; i < getCount(); i++) {
-            Cursor c = (Cursor) getItem(i);
+            Cursor c = (Cursor) getItem(i); // 获取对应位置的游标
             if (c != null) {
+                // 只统计笔记类型
                 if (NoteItemData.getNoteType(c) == Notes.TYPE_NOTE) {
                     mNotesCount++;
                 }
             } else {
                 Log.e(TAG, "Invalid cursor");
-                return;
+                return; // 游标无效时提前返回
             }
         }
     }
-}
+}

src/notes/ui/NotesListItem.java

@@ -29,18 +29,26 @@ import net.micode.notes.data.Notes;
 import net.micode.notes.tool.DataUtils;
 import net.micode.notes.tool.ResourceParser.NoteItemBgResources;
 
-
+/**
+ * 笔记列表项自定义视图
+ * 用于在笔记列表中显示单个笔记或文件夹的UI元素
+ */
 public class NotesListItem extends LinearLayout {
-    private ImageView mAlert;
+    private ImageView mAlert;      // 提醒图标
-    private TextView mTitle;
+    private TextView mTitle;       // 标题/内容摘要
-    private TextView mTime;
+    private TextView mTime;        // 修改时间
-    private TextView mCallName;
+    private TextView mCallName;    // 通话记录联系人姓名
-    private NoteItemData mItemData;
+    private NoteItemData mItemData; // 绑定的笔记数据
-    private CheckBox mCheckBox;
+    private CheckBox mCheckBox;    // 多选模式下的复选框
 
+    /**
+     * 构造函数
+     * @param context 上下文对象
+     */
     public NotesListItem(Context context) {
         super(context);
-        inflate(context, R.layout.note_item, this);
+        inflate(context, R.layout.note_item, this); // 从布局文件初始化视图
+        // 初始化视图组件
         mAlert = (ImageView) findViewById(R.id.iv_alert_icon);
         mTitle = (TextView) findViewById(R.id.tv_title);
         mTime = (TextView) findViewById(R.id.tv_time);
@@ -48,7 +56,15 @@ public class NotesListItem extends LinearLayout {
         mCheckBox = (CheckBox) findViewById(android.R.id.checkbox);
     }
 
+    /**
+     * 绑定数据到列表项视图
+     * @param context 上下文对象
+     * @param data 笔记数据项
+     * @param choiceMode 是否处于多选模式
+     * @param checked 是否被选中
+     */
     public void bind(Context context, NoteItemData data, boolean choiceMode, boolean checked) {
+        // 多选模式处理：如果是笔记类型且处于多选模式，显示复选框
         if (choiceMode && data.getType() == Notes.TYPE_NOTE) {
             mCheckBox.setVisibility(View.VISIBLE);
             mCheckBox.setChecked(checked);
@@ -56,19 +72,25 @@ public class NotesListItem extends LinearLayout {
             mCheckBox.setVisibility(View.GONE);
         }
 
-        mItemData = data;
+        mItemData = data; // 保存数据引用
+
+        // 根据不同数据类型设置不同的显示内容
         if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) {
+            // 通话记录文件夹的特殊显示
             mCallName.setVisibility(View.GONE);
             mAlert.setVisibility(View.VISIBLE);
-            mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem);
+            mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem); // 设置主标题样式
+            // 显示文件夹名称和包含的笔记数量
             mTitle.setText(context.getString(R.string.call_record_folder_name)
                     + context.getString(R.string.format_folder_files_count, data.getNotesCount()));
-            mAlert.setImageResource(R.drawable.call_record);
+            mAlert.setImageResource(R.drawable.call_record); // 设置通话记录图标
         } else if (data.getParentId() == Notes.ID_CALL_RECORD_FOLDER) {
+            // 通话记录笔记的显示
             mCallName.setVisibility(View.VISIBLE);
-            mCallName.setText(data.getCallName());
+            mCallName.setText(data.getCallName()); // 显示联系人姓名
-            mTitle.setTextAppearance(context,R.style.TextAppearanceSecondaryItem);
+            mTitle.setTextAppearance(context,R.style.TextAppearanceSecondaryItem); // 设置副标题样式
-            mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet()));
+            mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet())); // 显示格式化后的内容摘要
+            // 根据是否有提醒设置提醒图标
             if (data.hasAlert()) {
                 mAlert.setImageResource(R.drawable.clock);
                 mAlert.setVisibility(View.VISIBLE);
@@ -76,16 +98,20 @@ public class NotesListItem extends LinearLayout {
                 mAlert.setVisibility(View.GONE);
             }
         } else {
+            // 普通笔记或文件夹的显示
             mCallName.setVisibility(View.GONE);
-            mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem);
+            mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem); // 设置主标题样式
 
             if (data.getType() == Notes.TYPE_FOLDER) {
+                // 文件夹显示：显示文件夹名称和包含的笔记数量
                 mTitle.setText(data.getSnippet()
                         + context.getString(R.string.format_folder_files_count,
-                                data.getNotesCount()));
+                        data.getNotesCount()));
                 mAlert.setVisibility(View.GONE);
             } else {
+                // 普通笔记显示：显示内容摘要
                 mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet()));
+                // 根据是否有提醒设置提醒图标
                 if (data.hasAlert()) {
                     mAlert.setImageResource(R.drawable.clock);
                     mAlert.setVisibility(View.VISIBLE);
@@ -94,29 +120,46 @@ public class NotesListItem extends LinearLayout {
                 }
             }
         }
+
+        // 显示相对时间（如"2小时前"）
         mTime.setText(DateUtils.getRelativeTimeSpanString(data.getModifiedDate()));
 
+        // 根据数据类型和位置设置背景
         setBackground(data);
     }
 
+    /**
+     * 根据笔记数据类型和位置设置不同的背景
+     * @param data 笔记数据项
+     */
     private void setBackground(NoteItemData data) {
-        int id = data.getBgColorId();
+        int id = data.getBgColorId(); // 获取背景颜色ID
         if (data.getType() == Notes.TYPE_NOTE) {
+            // 笔记类型的背景设置
             if (data.isSingle() || data.isOneFollowingFolder()) {
+                // 单一条目或紧跟在文件夹后的单个笔记：使用单个笔记背景
                 setBackgroundResource(NoteItemBgResources.getNoteBgSingleRes(id));
             } else if (data.isLast()) {
+                // 最后一项：使用最后一项背景
                 setBackgroundResource(NoteItemBgResources.getNoteBgLastRes(id));
             } else if (data.isFirst() || data.isMultiFollowingFolder()) {
+                // 第一项或紧跟在文件夹后的多个笔记：使用第一项背景
                 setBackgroundResource(NoteItemBgResources.getNoteBgFirstRes(id));
             } else {
+                // 中间项：使用普通背景
                 setBackgroundResource(NoteItemBgResources.getNoteBgNormalRes(id));
             }
         } else {
+            // 文件夹类型：使用文件夹背景
             setBackgroundResource(NoteItemBgResources.getFolderBgRes());
         }
     }
 
+    /**
+     * 获取绑定的笔记数据项
+     * @return 笔记数据项
+     */
     public NoteItemData getItemData() {
         return mItemData;
     }
-}
+}

src/notes/ui/NotesPreferenceActivity.java

@@ -16,6 +16,7 @@
 
 package net.micode.notes.ui;
 
+import androidx.core.content.ContextCompat;
 import android.accounts.Account;
 import android.accounts.AccountManager;
 import android.app.ActionBar;
@@ -47,55 +48,74 @@ import net.micode.notes.data.Notes;
 import net.micode.notes.data.Notes.NoteColumns;
 import net.micode.notes.gtask.remote.GTaskSyncService;
 
-
+/**
+ * 笔记应用的设置界面Activity
+ * 主要负责Google Task同步账户的设置和管理
+ */
 public class NotesPreferenceActivity extends PreferenceActivity {
+    // 偏好设置文件名
     public static final String PREFERENCE_NAME = "notes_preferences";
-
+    // 同步账户名称的键
     public static final String PREFERENCE_SYNC_ACCOUNT_NAME = "pref_key_account_name";
-
+    // 上次同步时间的键
     public static final String PREFERENCE_LAST_SYNC_TIME = "pref_last_sync_time";
-
+    // 背景颜色设置的键
     public static final String PREFERENCE_SET_BG_COLOR_KEY = "pref_key_bg_random_appear";
-
+    // 同步账户设置的键
     private static final String PREFERENCE_SYNC_ACCOUNT_KEY = "pref_sync_account_key";
-
+    // 账户授权过滤器的键
     private static final String AUTHORITIES_FILTER_KEY = "authorities";
 
-    private PreferenceCategory mAccountCategory;
+    private PreferenceCategory mAccountCategory; // 账户设置类别
+    private GTaskReceiver mReceiver; // 同步服务广播接收器
+    private Account[] mOriAccounts; // 原始账户列表（用于检测新添加的账户）
+    private boolean mHasAddedAccount; // 标记是否添加了新账户
 
-    private GTaskReceiver mReceiver;
+// 在文件顶部添加这个 import
-
+// import androidx.core.content.ContextCompat;
-    private Account[] mOriAccounts;
-
-    private boolean mHasAddedAccount;
 
     @Override
     protected void onCreate(Bundle icicle) {
         super.onCreate(icicle);
 
-        /* using the app icon for navigation */
+        /* 使用应用图标作为导航按钮 */
         getActionBar().setDisplayHomeAsUpEnabled(true);
 
+        // 从XML文件加载偏好设置
         addPreferencesFromResource(R.xml.preferences);
         mAccountCategory = (PreferenceCategory) findPreference(PREFERENCE_SYNC_ACCOUNT_KEY);
-        mReceiver = new GTaskReceiver();
+        mReceiver = new GTaskReceiver(); // 创建广播接收器
         IntentFilter filter = new IntentFilter();
+<<<<<<< HEAD
+        filter.addAction(GTaskSyncService.GTASK_SERVICE_BROADCAST_NAME); // 注册同步服务广播
+        registerReceiver(mReceiver, filter); // 注册广播接收器
+=======
         filter.addAction(GTaskSyncService.GTASK_SERVICE_BROADCAST_NAME);
-        registerReceiver(mReceiver, filter);
+
+        // 修复：兼容 Android 13+ 的广播注册方式
+        ContextCompat.registerReceiver(
+                this,
+                mReceiver,
+                filter,
+                null,
+                null,
+                ContextCompat.RECEIVER_NOT_EXPORTED  // 内部广播，更安全
+        );
+>>>>>>> ce8801278409c0c99db42eb507f3f732202b6249
 
         mOriAccounts = null;
+        // 添加设置界面的头部视图
         View header = LayoutInflater.from(this).inflate(R.layout.settings_header, null);
         getListView().addHeaderView(header, null, true);
     }
-
     @Override
     protected void onResume() {
         super.onResume();
 
-        // need to set sync account automatically if user has added a new
+        // 如果用户添加了新账户，需要自动设置同步账户
-        // account
         if (mHasAddedAccount) {
             Account[] accounts = getGoogleAccounts();
+            // 检查是否有新账户添加
             if (mOriAccounts != null && accounts.length > mOriAccounts.length) {
                 for (Account accountNew : accounts) {
                     boolean found = false;
@@ -105,6 +125,7 @@ public class NotesPreferenceActivity extends PreferenceActivity {
                             break;
                         }
                     }
+                    // 发现新账户，自动设置为同步账户
                     if (!found) {
                         setSyncAccount(accountNew.name);
                         break;
@@ -113,94 +134,112 @@ public class NotesPreferenceActivity extends PreferenceActivity {
             }
         }
 
-        refreshUI();
+        refreshUI(); // 刷新界面
     }
 
     @Override
     protected void onDestroy() {
         if (mReceiver != null) {
-            unregisterReceiver(mReceiver);
+            unregisterReceiver(mReceiver); // 注销广播接收器
         }
         super.onDestroy();
     }
 
+    /**
+     * 加载账户偏好设置项
+     */
     private void loadAccountPreference() {
-        mAccountCategory.removeAll();
+        mAccountCategory.removeAll(); // 清空现有项
 
         Preference accountPref = new Preference(this);
         final String defaultAccount = getSyncAccountName(this);
         accountPref.setTitle(getString(R.string.preferences_account_title));
         accountPref.setSummary(getString(R.string.preferences_account_summary));
         accountPref.setOnPreferenceClickListener(new OnPreferenceClickListener() {
+            @Override
             public boolean onPreferenceClick(Preference preference) {
+                // 如果不在同步中才能操作账户设置
                 if (!GTaskSyncService.isSyncing()) {
                     if (TextUtils.isEmpty(defaultAccount)) {
-                        // the first time to set account
+                        // 首次设置账户，显示选择账户对话框
                         showSelectAccountAlertDialog();
                     } else {
-                        // if the account has already been set, we need to promp
+                        // 已有账户设置，显示更改账户确认对话框
-                        // user about the risk
                         showChangeAccountConfirmAlertDialog();
                     }
                 } else {
                     Toast.makeText(NotesPreferenceActivity.this,
-                            R.string.preferences_toast_cannot_change_account, Toast.LENGTH_SHORT)
+                                    R.string.preferences_toast_cannot_change_account, Toast.LENGTH_SHORT)
-                            .show();
+                            .show(); // 同步中不能更改账户
                 }
                 return true;
             }
         });
 
-        mAccountCategory.addPreference(accountPref);
+        mAccountCategory.addPreference(accountPref); // 添加到设置类别
     }
 
+    /**
+     * 加载同步按钮和同步状态显示
+     */
     private void loadSyncButton() {
         Button syncButton = (Button) findViewById(R.id.preference_sync_button);
         TextView lastSyncTimeView = (TextView) findViewById(R.id.prefenerece_sync_status_textview);
 
-        // set button state
+        // 设置按钮状态和文字
         if (GTaskSyncService.isSyncing()) {
             syncButton.setText(getString(R.string.preferences_button_sync_cancel));
             syncButton.setOnClickListener(new View.OnClickListener() {
+                @Override
                 public void onClick(View v) {
-                    GTaskSyncService.cancelSync(NotesPreferenceActivity.this);
+                    GTaskSyncService.cancelSync(NotesPreferenceActivity.this); // 取消同步
                 }
             });
         } else {
             syncButton.setText(getString(R.string.preferences_button_sync_immediately));
             syncButton.setOnClickListener(new View.OnClickListener() {
+                @Override
                 public void onClick(View v) {
-                    GTaskSyncService.startSync(NotesPreferenceActivity.this);
+                    GTaskSyncService.startSync(NotesPreferenceActivity.this); // 开始同步
                 }
             });
         }
+        // 只有设置了同步账户才能启用同步按钮
         syncButton.setEnabled(!TextUtils.isEmpty(getSyncAccountName(this)));
 
-        // set last sync time
+        // 设置上次同步时间显示
         if (GTaskSyncService.isSyncing()) {
-            lastSyncTimeView.setText(GTaskSyncService.getProgressString());
+            lastSyncTimeView.setText(GTaskSyncService.getProgressString()); // 显示同步进度
             lastSyncTimeView.setVisibility(View.VISIBLE);
         } else {
             long lastSyncTime = getLastSyncTime(this);
             if (lastSyncTime != 0) {
+                // 格式化显示上次同步时间
                 lastSyncTimeView.setText(getString(R.string.preferences_last_sync_time,
                         DateFormat.format(getString(R.string.preferences_last_sync_time_format),
                                 lastSyncTime)));
                 lastSyncTimeView.setVisibility(View.VISIBLE);
             } else {
-                lastSyncTimeView.setVisibility(View.GONE);
+                lastSyncTimeView.setVisibility(View.GONE); // 从未同步过
             }
         }
     }
 
+    /**
+     * 刷新整个设置界面
+     */
     private void refreshUI() {
         loadAccountPreference();
         loadSyncButton();
     }
 
+    /**
+     * 显示选择账户的对话框
+     */
     private void showSelectAccountAlertDialog() {
         AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this);
 
+        // 自定义对话框标题
         View titleView = LayoutInflater.from(this).inflate(R.layout.account_dialog_title, null);
         TextView titleTextView = (TextView) titleView.findViewById(R.id.account_dialog_title);
         titleTextView.setText(getString(R.string.preferences_dialog_select_account_title));
@@ -208,119 +247,147 @@ public class NotesPreferenceActivity extends PreferenceActivity {
         subtitleTextView.setText(getString(R.string.preferences_dialog_select_account_tips));
 
         dialogBuilder.setCustomTitle(titleView);
-        dialogBuilder.setPositiveButton(null, null);
+        dialogBuilder.setPositiveButton(null, null); // 不显示确定按钮
 
         Account[] accounts = getGoogleAccounts();
         String defAccount = getSyncAccountName(this);
 
-        mOriAccounts = accounts;
+        mOriAccounts = accounts; // 保存当前账户列表
-        mHasAddedAccount = false;
+        mHasAddedAccount = false; // 重置标记
 
         if (accounts.length > 0) {
             CharSequence[] items = new CharSequence[accounts.length];
             final CharSequence[] itemMapping = items;
             int checkedItem = -1;
             int index = 0;
+            // 填充账户列表
             for (Account account : accounts) {
                 if (TextUtils.equals(account.name, defAccount)) {
-                    checkedItem = index;
+                    checkedItem = index; // 标记已选账户
                 }
                 items[index++] = account.name;
             }
+            // 设置单选列表
             dialogBuilder.setSingleChoiceItems(items, checkedItem,
                     new DialogInterface.OnClickListener() {
+                        @Override
                         public void onClick(DialogInterface dialog, int which) {
+                            // 选择账户并保存
                             setSyncAccount(itemMapping[which].toString());
                             dialog.dismiss();
-                            refreshUI();
+                            refreshUI(); // 刷新界面
                         }
                     });
         }
 
+        // 添加"添加账户"选项
         View addAccountView = LayoutInflater.from(this).inflate(R.layout.add_account_text, null);
         dialogBuilder.setView(addAccountView);
 
         final AlertDialog dialog = dialogBuilder.show();
         addAccountView.setOnClickListener(new View.OnClickListener() {
+            @Override
             public void onClick(View v) {
-                mHasAddedAccount = true;
+                mHasAddedAccount = true; // 标记添加了新账户
+                // 启动添加账户界面
                 Intent intent = new Intent("android.settings.ADD_ACCOUNT_SETTINGS");
                 intent.putExtra(AUTHORITIES_FILTER_KEY, new String[] {
-                    "gmail-ls"
+                        "gmail-ls" // 限制为Google账户
                 });
                 startActivityForResult(intent, -1);
-                dialog.dismiss();
+                dialog.dismiss(); // 关闭对话框
             }
         });
     }
 
+    /**
+     * 显示更改账户的确认对话框
+     */
     private void showChangeAccountConfirmAlertDialog() {
         AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this);
 
+        // 自定义对话框标题
         View titleView = LayoutInflater.from(this).inflate(R.layout.account_dialog_title, null);
         TextView titleTextView = (TextView) titleView.findViewById(R.id.account_dialog_title);
         titleTextView.setText(getString(R.string.preferences_dialog_change_account_title,
-                getSyncAccountName(this)));
+                getSyncAccountName(this))); // 显示当前账户
         TextView subtitleTextView = (TextView) titleView.findViewById(R.id.account_dialog_subtitle);
         subtitleTextView.setText(getString(R.string.preferences_dialog_change_account_warn_msg));
         dialogBuilder.setCustomTitle(titleView);
 
+        // 设置操作菜单项
         CharSequence[] menuItemArray = new CharSequence[] {
-                getString(R.string.preferences_menu_change_account),
+                getString(R.string.preferences_menu_change_account), // 更改账户
-                getString(R.string.preferences_menu_remove_account),
+                getString(R.string.preferences_menu_remove_account), // 移除账户
-                getString(R.string.preferences_menu_cancel)
+                getString(R.string.preferences_menu_cancel) // 取消
         };
         dialogBuilder.setItems(menuItemArray, new DialogInterface.OnClickListener() {
+            @Override
             public void onClick(DialogInterface dialog, int which) {
                 if (which == 0) {
-                    showSelectAccountAlertDialog();
+                    showSelectAccountAlertDialog(); // 显示选择账户对话框
                 } else if (which == 1) {
-                    removeSyncAccount();
+                    removeSyncAccount(); // 移除同步账户
-                    refreshUI();
+                    refreshUI(); // 刷新界面
                 }
+                // which == 2 取消，不做任何操作
             }
         });
         dialogBuilder.show();
     }
 
+    /**
+     * 获取所有Google账户
+     * @return Google账户数组
+     */
     private Account[] getGoogleAccounts() {
         AccountManager accountManager = AccountManager.get(this);
-        return accountManager.getAccountsByType("com.google");
+        return accountManager.getAccountsByType("com.google"); // 获取Google类型账户
     }
 
+    /**
+     * 设置同步账户
+     * @param account 账户名称
+     */
     private void setSyncAccount(String account) {
+        // 只有当账户变更时才执行操作
         if (!getSyncAccountName(this).equals(account)) {
             SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE);
             SharedPreferences.Editor editor = settings.edit();
             if (account != null) {
-                editor.putString(PREFERENCE_SYNC_ACCOUNT_NAME, account);
+                editor.putString(PREFERENCE_SYNC_ACCOUNT_NAME, account); // 保存账户名
             } else {
-                editor.putString(PREFERENCE_SYNC_ACCOUNT_NAME, "");
+                editor.putString(PREFERENCE_SYNC_ACCOUNT_NAME, ""); // 清空账户名
             }
             editor.commit();
 
-            // clean up last sync time
+            // 清除上次同步时间
             setLastSyncTime(this, 0);
 
-            // clean up local gtask related info
+            // 在新线程中清除本地与GTask相关的同步信息
             new Thread(new Runnable() {
+                @Override
                 public void run() {
                     ContentValues values = new ContentValues();
-                    values.put(NoteColumns.GTASK_ID, "");
+                    values.put(NoteColumns.GTASK_ID, ""); // 清空GTask ID
-                    values.put(NoteColumns.SYNC_ID, 0);
+                    values.put(NoteColumns.SYNC_ID, 0); // 重置同步ID
                     getContentResolver().update(Notes.CONTENT_NOTE_URI, values, null, null);
                 }
             }).start();
 
             Toast.makeText(NotesPreferenceActivity.this,
                     getString(R.string.preferences_toast_success_set_accout, account),
-                    Toast.LENGTH_SHORT).show();
+                    Toast.LENGTH_SHORT).show(); // 显示设置成功提示
         }
     }
 
+    /**
+     * 移除同步账户
+     */
     private void removeSyncAccount() {
         SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE);
         SharedPreferences.Editor editor = settings.edit();
+        // 移除相关偏好设置
         if (settings.contains(PREFERENCE_SYNC_ACCOUNT_NAME)) {
             editor.remove(PREFERENCE_SYNC_ACCOUNT_NAME);
         }
@@ -329,23 +396,34 @@ public class NotesPreferenceActivity extends PreferenceActivity {
         }
         editor.commit();
 
-        // clean up local gtask related info
+        // 在新线程中清除本地与GTask相关的同步信息
         new Thread(new Runnable() {
+            @Override
             public void run() {
                 ContentValues values = new ContentValues();
-                values.put(NoteColumns.GTASK_ID, "");
+                values.put(NoteColumns.GTASK_ID, ""); // 清空GTask ID
-                values.put(NoteColumns.SYNC_ID, 0);
+                values.put(NoteColumns.SYNC_ID, 0); // 重置同步ID
                 getContentResolver().update(Notes.CONTENT_NOTE_URI, values, null, null);
             }
         }).start();
     }
 
+    /**
+     * 静态方法：获取同步账户名称
+     * @param context 上下文
+     * @return 同步账户名称，如果不存在则返回空字符串
+     */
     public static String getSyncAccountName(Context context) {
         SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME,
                 Context.MODE_PRIVATE);
-        return settings.getString(PREFERENCE_SYNC_ACCOUNT_NAME, "");
+        return settings.getString(PREFERENCE_SYNC_ACCOUNT_NAME, ""); // 默认返回空字符串
     }
 
+    /**
+     * 静态方法：设置上次同步时间
+     * @param context 上下文
+     * @param time 同步时间戳
+     */
     public static void setLastSyncTime(Context context, long time) {
         SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME,
                 Context.MODE_PRIVATE);
@@ -354,35 +432,45 @@ public class NotesPreferenceActivity extends PreferenceActivity {
         editor.commit();
     }
 
+    /**
+     * 静态方法：获取上次同步时间
+     * @param context 上下文
+     * @return 上次同步时间戳，如果不存在则返回0
+     */
     public static long getLastSyncTime(Context context) {
         SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME,
                 Context.MODE_PRIVATE);
-        return settings.getLong(PREFERENCE_LAST_SYNC_TIME, 0);
+        return settings.getLong(PREFERENCE_LAST_SYNC_TIME, 0); // 默认返回0
     }
 
+    /**
+     * GTask同步服务广播接收器
+     * 用于接收同步状态变化的广播
+     */
     private class GTaskReceiver extends BroadcastReceiver {
-
         @Override
         public void onReceive(Context context, Intent intent) {
-            refreshUI();
+            refreshUI(); // 刷新界面
+            // 如果正在同步，更新同步进度显示
             if (intent.getBooleanExtra(GTaskSyncService.GTASK_SERVICE_BROADCAST_IS_SYNCING, false)) {
                 TextView syncStatus = (TextView) findViewById(R.id.prefenerece_sync_status_textview);
                 syncStatus.setText(intent
                         .getStringExtra(GTaskSyncService.GTASK_SERVICE_BROADCAST_PROGRESS_MSG));
             }
-
         }
     }
 
+    @Override
     public boolean onOptionsItemSelected(MenuItem item) {
         switch (item.getItemId()) {
             case android.R.id.home:
+                // 点击返回按钮，返回笔记列表界面
                 Intent intent = new Intent(this, NotesListActivity.class);
-                intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);
+                intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP); // 清理Activity栈
                 startActivity(intent);
                 return true;
             default:
                 return false;
         }
     }
-}
+}

src/notes/widget/NoteWidgetProvider.java

@@ -15,6 +15,7 @@
  */
 
 package net.micode.notes.widget;
+
 import android.app.PendingIntent;
 import android.appwidget.AppWidgetManager;
 import android.appwidget.AppWidgetProvider;
@@ -32,101 +33,150 @@ import net.micode.notes.tool.ResourceParser;
 import net.micode.notes.ui.NoteEditActivity;
 import net.micode.notes.ui.NotesListActivity;
 
+/**
+ * 笔记小部件提供者抽象基类
+ * 提供桌面小部件的基本功能，包括更新、删除和数据查询
+ * 具体的小部件类型（如2x、4x）需要继承此类并实现抽象方法
+ */
 public abstract class NoteWidgetProvider extends AppWidgetProvider {
+    // 数据库查询字段投影
     public static final String [] PROJECTION = new String [] {
-        NoteColumns.ID,
+            NoteColumns.ID,          // 笔记ID
-        NoteColumns.BG_COLOR_ID,
+            NoteColumns.BG_COLOR_ID, // 背景颜色ID
-        NoteColumns.SNIPPET
+            NoteColumns.SNIPPET      // 内容摘要
     };
 
+    // 字段索引常量
     public static final int COLUMN_ID           = 0;
     public static final int COLUMN_BG_COLOR_ID  = 1;
     public static final int COLUMN_SNIPPET      = 2;
 
-    private static final String TAG = "NoteWidgetProvider";
+    private static final String TAG = "NoteWidgetProvider"; // 日志标签
 
     @Override
     public void onDeleted(Context context, int[] appWidgetIds) {
+        // 当小部件从桌面删除时调用
         ContentValues values = new ContentValues();
+        // 将笔记的小部件ID重置为无效值，解除笔记与小部件的关联
         values.put(NoteColumns.WIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID);
         for (int i = 0; i < appWidgetIds.length; i++) {
             context.getContentResolver().update(Notes.CONTENT_NOTE_URI,
                     values,
-                    NoteColumns.WIDGET_ID + "=?",
+                    NoteColumns.WIDGET_ID + "=?", // 更新条件：找到对应的小部件ID
                     new String[] { String.valueOf(appWidgetIds[i])});
         }
     }
 
+    /**
+     * 获取指定小部件ID关联的笔记信息
+     * @param context 上下文
+     * @param widgetId 小部件ID
+     * @return 笔记信息游标，包含ID、背景颜色和摘要
+     */
     private Cursor getNoteWidgetInfo(Context context, int widgetId) {
         return context.getContentResolver().query(Notes.CONTENT_NOTE_URI,
                 PROJECTION,
+                // 查询条件：小部件ID匹配且不在回收站中
                 NoteColumns.WIDGET_ID + "=? AND " + NoteColumns.PARENT_ID + "<>?",
                 new String[] { String.valueOf(widgetId), String.valueOf(Notes.ID_TRASH_FOLER) },
                 null);
     }
 
+    /**
+     * 更新小部件（默认不处于隐私模式）
+     * @param context 上下文
+     * @param appWidgetManager 小部件管理器
+     * @param appWidgetIds 需要更新的小部件ID数组
+     */
     protected void update(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
         update(context, appWidgetManager, appWidgetIds, false);
     }
 
+    /**
+     * 更新小部件内容
+     * @param context 上下文
+     * @param appWidgetManager 小部件管理器
+     * @param appWidgetIds 需要更新的小部件ID数组
+     * @param privacyMode 是否处于隐私模式（隐私模式下显示占位文本）
+     */
     private void update(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds,
-            boolean privacyMode) {
+                        boolean privacyMode) {
         for (int i = 0; i < appWidgetIds.length; i++) {
             if (appWidgetIds[i] != AppWidgetManager.INVALID_APPWIDGET_ID) {
-                int bgId = ResourceParser.getDefaultBgId(context);
+                int bgId = ResourceParser.getDefaultBgId(context); // 默认背景颜色ID
-                String snippet = "";
+                String snippet = ""; // 内容摘要
                 Intent intent = new Intent(context, NoteEditActivity.class);
-                intent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP);
+                intent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP); // 设置Activity启动模式
                 intent.putExtra(Notes.INTENT_EXTRA_WIDGET_ID, appWidgetIds[i]);
                 intent.putExtra(Notes.INTENT_EXTRA_WIDGET_TYPE, getWidgetType());
 
+                // 查询与小部件关联的笔记信息
                 Cursor c = getNoteWidgetInfo(context, appWidgetIds[i]);
                 if (c != null && c.moveToFirst()) {
+                    // 正常情况下，一个小部件ID应该只关联一个笔记
                     if (c.getCount() > 1) {
                         Log.e(TAG, "Multiple message with same widget id:" + appWidgetIds[i]);
                         c.close();
-                        return;
+                        return; // 发现异常情况，直接返回
                     }
-                    snippet = c.getString(COLUMN_SNIPPET);
+                    snippet = c.getString(COLUMN_SNIPPET); // 获取内容摘要
-                    bgId = c.getInt(COLUMN_BG_COLOR_ID);
+                    bgId = c.getInt(COLUMN_BG_COLOR_ID); // 获取背景颜色ID
-                    intent.putExtra(Intent.EXTRA_UID, c.getLong(COLUMN_ID));
+                    intent.putExtra(Intent.EXTRA_UID, c.getLong(COLUMN_ID)); // 笔记ID
-                    intent.setAction(Intent.ACTION_VIEW);
+                    intent.setAction(Intent.ACTION_VIEW); // 查看笔记
                 } else {
+                    // 没有找到关联的笔记，显示默认提示
                     snippet = context.getResources().getString(R.string.widget_havenot_content);
-                    intent.setAction(Intent.ACTION_INSERT_OR_EDIT);
+                    intent.setAction(Intent.ACTION_INSERT_OR_EDIT); // 新建或编辑笔记
                 }
 
                 if (c != null) {
                     c.close();
                 }
 
+                // 创建RemoteViews对象
                 RemoteViews rv = new RemoteViews(context.getPackageName(), getLayoutId());
-                rv.setImageViewResource(R.id.widget_bg_image, getBgResourceId(bgId));
+                rv.setImageViewResource(R.id.widget_bg_image, getBgResourceId(bgId)); // 设置背景
                 intent.putExtra(Notes.INTENT_EXTRA_BACKGROUND_ID, bgId);
+
                 /**
-                 * Generate the pending intent to start host for the widget
+                 * 生成启动宿主Activity的PendingIntent
                  */
                 PendingIntent pendingIntent = null;
                 if (privacyMode) {
+                    // 隐私模式：显示占位文本，点击跳转到笔记列表
                     rv.setTextViewText(R.id.widget_text,
                             context.getString(R.string.widget_under_visit_mode));
                     pendingIntent = PendingIntent.getActivity(context, appWidgetIds[i], new Intent(
                             context, NotesListActivity.class), PendingIntent.FLAG_UPDATE_CURRENT);
                 } else {
+                    // 正常模式：显示笔记摘要，点击跳转到笔记编辑界面
                     rv.setTextViewText(R.id.widget_text, snippet);
                     pendingIntent = PendingIntent.getActivity(context, appWidgetIds[i], intent,
                             PendingIntent.FLAG_UPDATE_CURRENT);
                 }
 
-                rv.setOnClickPendingIntent(R.id.widget_text, pendingIntent);
+                rv.setOnClickPendingIntent(R.id.widget_text, pendingIntent); // 设置点击事件
-                appWidgetManager.updateAppWidget(appWidgetIds[i], rv);
+                appWidgetManager.updateAppWidget(appWidgetIds[i], rv); // 更新小部件
             }
         }
     }
 
+    /**
+     * 抽象方法：根据背景颜色ID获取对应的资源ID
+     * @param bgId 背景颜色ID
+     * @return 背景资源ID
+     */
     protected abstract int getBgResourceId(int bgId);
 
+    /**
+     * 抽象方法：获取小部件布局资源ID
+     * @return 布局资源ID
+     */
     protected abstract int getLayoutId();
 
+    /**
+     * 抽象方法：获取小部件类型
+     * @return 小部件类型（如Notes.TYPE_WIDGET_2X, Notes.TYPE_WIDGET_4X）
+     */
     protected abstract int getWidgetType();
-}
+}

src/notes/widget/NoteWidgetProvider_2x.java

@@ -23,25 +23,49 @@ import net.micode.notes.R;
 import net.micode.notes.data.Notes;
 import net.micode.notes.tool.ResourceParser;
 
-
+/**
+ * 2x大小笔记小部件提供者实现类
+ * 继承自NoteWidgetProvider抽象基类，实现2x大小桌面小部件的具体功能
+ */
 public class NoteWidgetProvider_2x extends NoteWidgetProvider {
+
+    /**
+     * 小部件更新回调方法
+     * 当小部件需要更新时调用（如更新时间间隔到达、小部件被添加到桌面时）
+     * @param context 上下文对象
+     * @param appWidgetManager 小部件管理器，用于更新小部件
+     * @param appWidgetIds 需要更新的小部件ID数组
+     */
     @Override
     public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
-        super.update(context, appWidgetManager, appWidgetIds);
+        super.update(context, appWidgetManager, appWidgetIds); // 调用父类的更新方法
     }
 
+    /**
+     * 获取2x小部件的布局资源ID
+     * @return 2x小部件布局资源ID
+     */
     @Override
     protected int getLayoutId() {
-        return R.layout.widget_2x;
+        return R.layout.widget_2x; // 返回2x小部件的布局文件
     }
 
+    /**
+     * 根据背景颜色ID获取对应的2x小部件背景资源ID
+     * @param bgId 背景颜色ID
+     * @return 2x小部件背景图片资源ID
+     */
     @Override
     protected int getBgResourceId(int bgId) {
-        return ResourceParser.WidgetBgResources.getWidget2xBgResource(bgId);
+        return ResourceParser.WidgetBgResources.getWidget2xBgResource(bgId); // 从资源解析器获取2x小部件背景资源
     }
 
+    /**
+     * 获取小部件类型标识
+     * @return 2x小部件类型常量
+     */
     @Override
     protected int getWidgetType() {
-        return Notes.TYPE_WIDGET_2X;
+        return Notes.TYPE_WIDGET_2X; // 返回2x小部件的类型标识
     }
-}
+}

src/notes/widget/NoteWidgetProvider_4x.java

@@ -23,24 +23,49 @@ import net.micode.notes.R;
 import net.micode.notes.data.Notes;
 import net.micode.notes.tool.ResourceParser;
 
-
+/**
+ * 4x大小笔记小部件提供者实现类
+ * 继承自NoteWidgetProvider抽象基类，实现4x大小桌面小部件的具体功能
+ */
 public class NoteWidgetProvider_4x extends NoteWidgetProvider {
+
+    /**
+     * 小部件更新回调方法
+     * 当小部件需要更新时调用（如更新时间间隔到达、小部件被添加到桌面时）
+     * @param context 上下文对象
+     * @param appWidgetManager 小部件管理器，用于更新小部件
+     * @param appWidgetIds 需要更新的小部件ID数组
+     */
     @Override
     public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
-        super.update(context, appWidgetManager, appWidgetIds);
+        super.update(context, appWidgetManager, appWidgetIds); // 调用父类的更新方法
     }
 
+    /**
+     * 获取4x小部件的布局资源ID
+     * @return 4x小部件布局资源ID
+     */
+    @Override
     protected int getLayoutId() {
-        return R.layout.widget_4x;
+        return R.layout.widget_4x; // 返回4x小部件的布局文件
     }
 
+    /**
+     * 根据背景颜色ID获取对应的4x小部件背景资源ID
+     * @param bgId 背景颜色ID
+     * @return 4x小部件背景图片资源ID
+     */
     @Override
     protected int getBgResourceId(int bgId) {
-        return ResourceParser.WidgetBgResources.getWidget4xBgResource(bgId);
+        return ResourceParser.WidgetBgResources.getWidget4xBgResource(bgId); // 从资源解析器获取4x小部件背景资源
     }
 
+    /**
+     * 获取小部件类型标识
+     * @return 4x小部件类型常量
+     */
     @Override
     protected int getWidgetType() {
-        return Notes.TYPE_WIDGET_4X;
+        return Notes.TYPE_WIDGET_4X; // 返回4x小部件的类型标识
     }
-}
+}