src/main/java/net/micode/notes/gtask/data/MetaData.java

@@ -24,37 +24,64 @@ import net.micode.notes.tool.GTaskStringUtils;
 import org.json.JSONException;
 import org.json.JSONObject;
 
-
+/**
+ * 元数据管理类，用于处理与Google Task同步相关的元数据信息
+ * 继承自Task类，主要管理关联任务ID和元数据的存储与解析
+ */
 public class MetaData extends Task {
+    // 日志标签
     private final static String TAG = MetaData.class.getSimpleName();
 
+    // 关联的Google Task服务器ID
     private String mRelatedGid = null;
 
+    /**
+     * 设置元数据信息
+     * @param gid 关联的Google Task服务器ID
+     * @param metaInfo 需要存储的元数据JSON对象
+     * 将gid存入metaInfo后，序列化为字符串存储到notes字段
+     * 并设置固定名称标识为元数据笔记
+     */
     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");
         }
+        // 序列化元数据到笔记内容字段
         setNotes(metaInfo.toString());
+        // 设置固定名称标识为元数据笔记
         setName(GTaskStringUtils.META_NOTE_NAME);
     }
 
+    /**
+     * 获取关联的GTask ID
+     */
     public String getRelatedGid() {
         return mRelatedGid;
     }
 
+    /**
+     * 判断是否需要保存（当notes字段有内容时需保存）
+     */
     @Override
     public boolean isWorthSaving() {
         return getNotes() != null;
     }
 
+    /**
+     * 通过远程JSON数据设置内容
+     * 解析notes字段中的元数据并提取关联的GTask ID
+     */
     @Override
     public void setContentByRemoteJSON(JSONObject js) {
         super.setContentByRemoteJSON(js);
         if (getNotes() != null) {
             try {
+                // 反序列化notes字段内容
                 JSONObject metaInfo = new JSONObject(getNotes().trim());
+                // 提取关联的GTask ID
                 mRelatedGid = metaInfo.getString(GTaskStringUtils.META_HEAD_GTASK_ID);
             } catch (JSONException e) {
                 Log.w(TAG, "failed to get related gid");
@@ -63,20 +90,32 @@ public class MetaData extends Task {
         }
     }
 
+    // 以下方法在元数据管理中不应被调用，直接抛出异常
+
+    /**
+     * 元数据不应通过本地JSON设置内容
+     * @throws IllegalAccessError 始终抛出，标识非法调用
+     */
     @Override
     public void setContentByLocalJSON(JSONObject js) {
-        // this function should not be called
         throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");
     }
 
+    /**
+     * 元数据不需要生成本地JSON内容
+     * @throws IllegalAccessError 始终抛出，标识非法调用
+     */
     @Override
     public JSONObject getLocalJSONFromContent() {
         throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called");
     }
 
+    /**
+     * 元数据不处理本地数据库同步操作
+     * @throws IllegalAccessError 始终抛出，标识非法调用
+     */
     @Override
     public int getSyncAction(Cursor c) {
         throw new IllegalAccessError("MetaData:getSyncAction should not be called");
     }
-
 }

src/main/java/net/micode/notes/gtask/data/Node.java

@@ -17,36 +17,48 @@
 package net.micode.notes.gtask.data;
 
 import android.database.Cursor;
-
 import org.json.JSONObject;
 
+/**
+ * 抽象节点基类，定义同步任务数据节点的通用属性和行为
+ * 作为所有同步实体（如笔记、任务、子任务等）的父类
+ * 包含同步动作类型定义和基础数据字段管理
+ */
 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 Task服务器分配的唯一标识符 */
     private String mGid;
-
+    /** 节点显示名称 */
     private String mName;
-
+    /** 最后修改时间戳（毫秒级） */
     private long mLastModified;
-
+    /** 删除标记（逻辑删除） */
     private boolean mDeleted;
 
+    /**
+     * 节点构造函数
+     * 初始化默认值：gid=null, 名称为空字符串，最后修改时间为0，未删除状态
+     */
     public Node() {
         mGid = null;
         mName = "";
@@ -54,48 +66,86 @@ public abstract class Node {
         mDeleted = false;
     }
 
+    // 抽象方法定义（需子类实现）
+
+    /**
+     * 生成创建动作的JSON数据包
+     * @param actionId 动作标识符（用于保证操作序列）
+     * @return 包含创建指令的JSON对象
+     */
     public abstract JSONObject getCreateAction(int actionId);
 
+    /**
+     * 生成更新动作的JSON数据包
+     * @param actionId 动作标识符
+     * @return 包含更新指令的JSON对象
+     */
     public abstract JSONObject getUpdateAction(int actionId);
 
+    /**
+     * 通过远程JSON数据设置节点内容
+     * @param js 来自服务器的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 Task服务器ID */
     public void setGid(String gid) {
         this.mGid = gid;
     }
 
+    /** 设置节点名称 */
     public void setName(String name) {
         this.mName = name;
     }
 
+    /** 设置最后修改时间戳 */
     public void setLastModified(long lastModified) {
         this.mLastModified = lastModified;
     }
 
+    /** 设置删除标记 */
     public void setDeleted(boolean deleted) {
         this.mDeleted = deleted;
     }
 
+    /** 获取Google Task服务器ID */
     public String getGid() {
         return this.mGid;
     }
 
+    /** 获取节点名称 */
     public String getName() {
         return this.mName;
     }
 
+    /** 获取最后修改时间戳 */
     public long getLastModified() {
         return this.mLastModified;
     }
 
+    /** 获取删除状态 */
     public boolean getDeleted() {
         return this.mDeleted;
     }
-
 }

src/main/java/net/micode/notes/gtask/data/SqlData.java

@@ -34,54 +34,65 @@ import net.micode.notes.gtask.exception.ActionFailureException;
 import org.json.JSONException;
 import org.json.JSONObject;
 
-
+/**
+ * 数据库数据操作封装类
+ * 负责处理与便笺数据表（Data表）的CRUD操作
+ * 封装数据字段的差异更新逻辑，支持事务性提交
+ */
 public class SqlData {
+    // 日志标签
     private static final String TAG = SqlData.class.getSimpleName();
 
+    // 无效ID标识（用于新建条目）
     private static final int INVALID_ID = -99999;
 
+    // 数据表查询字段投影（对应DATA表的列）
     public static final String[] PROJECTION_DATA = new String[] {
-            DataColumns.ID, DataColumns.MIME_TYPE, DataColumns.CONTENT, DataColumns.DATA1,
-            DataColumns.DATA3
+            DataColumns.ID,           // 0:数据ID
+            DataColumns.MIME_TYPE,    // 1:MIME类型
+            DataColumns.CONTENT,      // 2:内容主体（JSON格式）
+            DataColumns.DATA1,        // 3:扩展数据1（长整型）
+            DataColumns.DATA3        // 4:扩展数据3（字符串）
     };
 
+    // 投影字段索引常量
     public static final int DATA_ID_COLUMN = 0;
-
     public static final int DATA_MIME_TYPE_COLUMN = 1;
-
     public static final int DATA_CONTENT_COLUMN = 2;
-
     public static final int DATA_CONTENT_DATA_1_COLUMN = 3;
-
     public static final int DATA_CONTENT_DATA_3_COLUMN = 4;
 
-    private ContentResolver mContentResolver;
-
-    private boolean mIsCreate;
-
-    private long mDataId;
-
-    private String mDataMimeType;
-
-    private String mDataContent;
-
-    private long mDataContentData1;
-
-    private String mDataContentData3;
-
-    private ContentValues mDiffDataValues;
-
+    // 成员变量
+    private ContentResolver mContentResolver; // 内容解析器（用于数据库操作）
+    private boolean mIsCreate;                // 新建数据条目标识
+    private long mDataId;                     // 当前数据ID
+    private String mDataMimeType;             // MIME类型（默认NOTE类型）
+    private String mDataContent;              // 内容主体
+    private long mDataContentData1;           // 扩展数据1（长整型字段）
+    private String mDataContentData3;         // 扩展数据3（字符串字段）
+    private ContentValues mDiffDataValues;    // 差异字段集合（用于批量更新）
+
+    /**
+     * 新建数据构造函数
+     * @param context 上下文对象（用于获取ContentResolver）
+     */
     public SqlData(Context context) {
         mContentResolver = context.getContentResolver();
         mIsCreate = true;
+        // 初始化默认值
         mDataId = INVALID_ID;
-        mDataMimeType = DataConstants.NOTE;
+        mDataMimeType = DataConstants.NOTE; // 默认MIME类型为便笺
         mDataContent = "";
         mDataContentData1 = 0;
         mDataContentData3 = "";
         mDiffDataValues = new ContentValues();
     }
 
+    /**
+     * 从数据库游标构造（用于加载已有数据）
+     * @param context 上下文对象
+     * @param c 数据库查询结果游标
+     */
     public SqlData(Context context, Cursor c) {
         mContentResolver = context.getContentResolver();
         mIsCreate = false;
@@ -89,6 +100,10 @@ public class SqlData {
         mDiffDataValues = new ContentValues();
     }
 
+    /**
+     * 从游标加载数据到成员变量
+     * @param c 已定位到正确位置的数据库游标
+     */
     private void loadFromCursor(Cursor c) {
         mDataId = c.getLong(DATA_ID_COLUMN);
         mDataMimeType = c.getString(DATA_MIME_TYPE_COLUMN);
@@ -97,13 +112,21 @@ 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 {
+        // 处理数据ID字段
         long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID;
         if (mIsCreate || mDataId != dataId) {
             mDiffDataValues.put(DataColumns.ID, dataId);
         }
         mDataId = dataId;
 
+        // 处理MIME类型字段
         String dataMimeType = js.has(DataColumns.MIME_TYPE) ? js.getString(DataColumns.MIME_TYPE)
                 : DataConstants.NOTE;
         if (mIsCreate || !mDataMimeType.equals(dataMimeType)) {
@@ -111,18 +134,21 @@ public class SqlData {
         }
         mDataMimeType = dataMimeType;
 
+        // 处理内容主体字段
         String dataContent = js.has(DataColumns.CONTENT) ? js.getString(DataColumns.CONTENT) : "";
         if (mIsCreate || !mDataContent.equals(dataContent)) {
             mDiffDataValues.put(DataColumns.CONTENT, dataContent);
         }
         mDataContent = dataContent;
 
+        // 处理扩展数据1（长整型）
         long dataContentData1 = js.has(DataColumns.DATA1) ? js.getLong(DataColumns.DATA1) : 0;
         if (mIsCreate || mDataContentData1 != dataContentData1) {
             mDiffDataValues.put(DataColumns.DATA1, dataContentData1);
         }
         mDataContentData1 = dataContentData1;
 
+        // 处理扩展数据3（字符串）
         String dataContentData3 = js.has(DataColumns.DATA3) ? js.getString(DataColumns.DATA3) : "";
         if (mIsCreate || !mDataContentData3.equals(dataContentData3)) {
             mDiffDataValues.put(DataColumns.DATA3, dataContentData3);
@@ -130,6 +156,12 @@ public class SqlData {
         mDataContentData3 = dataContentData3;
     }
 
+    /**
+     * 获取当前数据的JSON表示
+     * @return 包含所有数据字段的JSON对象
+     * @throws JSONException JSON构造异常
+     * 注意：新建对象（未提交）调用此方法将返回null
+     */
     public JSONObject getContent() throws JSONException {
         if (mIsCreate) {
             Log.e(TAG, "it seems that we haven't created this in database yet");
@@ -144,34 +176,59 @@ public class SqlData {
         return js;
     }
 
+    /**
+     * 提交数据变更到数据库
+     * @param noteId 关联的便笺ID
+     * @param validateVersion 是否进行版本验证
+     * @param version 当前数据版本（用于乐观锁）
+     * @throws ActionFailureException 数据库操作失败时抛出
+     *
+     * 执行逻辑：
+     * 1. 新建模式：插入新记录并获取分配的ID
+     * 2. 更新模式：根据差异字段进行更新
+     *    - 带版本验证的更新可防止同步冲突
+     */
     public void commit(long noteId, boolean validateVersion, long version) {
-
         if (mIsCreate) {
+            // 新建数据处理
             if (mDataId == INVALID_ID && mDiffDataValues.containsKey(DataColumns.ID)) {
-                mDiffDataValues.remove(DataColumns.ID);
+                mDiffDataValues.remove(DataColumns.ID); // 移除无效ID
             }
 
+            // 添加关联便笺ID
             mDiffDataValues.put(DataColumns.NOTE_ID, noteId);
+
+            // 执行插入操作
             Uri uri = mContentResolver.insert(Notes.CONTENT_DATA_URI, mDiffDataValues);
             try {
+                // 从返回URI中解析新分配的ID
                 mDataId = Long.valueOf(uri.getPathSegments().get(1));
             } catch (NumberFormatException e) {
                 Log.e(TAG, "Get note id error :" + e.toString());
                 throw new ActionFailureException("create note failed");
             }
         } else {
+            // 更新数据处理
             if (mDiffDataValues.size() > 0) {
                 int result = 0;
                 if (!validateVersion) {
-                    result = mContentResolver.update(ContentUris.withAppendedId(
-                            Notes.CONTENT_DATA_URI, mDataId), mDiffDataValues, null, null);
+                    // 普通更新
+                    result = mContentResolver.update(
+                            ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, mDataId),
+                            mDiffDataValues,
+                            null,
+                            null
+                    );
                 } else {
-                    result = mContentResolver.update(ContentUris.withAppendedId(
-                            Notes.CONTENT_DATA_URI, mDataId), mDiffDataValues,
+                    // 带版本验证的更新（防止同步冲突）
+                    result = mContentResolver.update(
+                            ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, mDataId),
+                            mDiffDataValues,
+                            // 使用子查询确保版本匹配
                             " ? in (SELECT " + NoteColumns.ID + " FROM " + TABLE.NOTE
-                                    + " WHERE " + NoteColumns.VERSION + "=?)", new String[] {
-                                    String.valueOf(noteId), String.valueOf(version)
-                            });
+                                    + " WHERE " + NoteColumns.VERSION + "=?)",
+                            new String[] { String.valueOf(noteId), String.valueOf(version) }
+                    );
                 }
                 if (result == 0) {
                     Log.w(TAG, "there is no update. maybe user updates note when syncing");
@@ -179,10 +236,15 @@ public class SqlData {
             }
         }
 
+        // 重置状态
         mDiffDataValues.clear();
         mIsCreate = false;
     }
 
+    /**
+     * 获取当前数据ID
+     * @return 有效数据ID，新建对象提交前返回INVALID_ID
+     */
     public long getId() {
         return mDataId;
     }

src/main/java/net/micode/notes/gtask/data/SqlNote.java

@@ -37,12 +37,15 @@ import org.json.JSONObject;
 
 import java.util.ArrayList;
 
-
+// SqlNote类用于处理便签数据的存储和操作，包括数据的加载、设置、获取和提交等操作。
 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,76 +55,80 @@ public class SqlNote {
             NoteColumns.VERSION
     };
 
+    // 定义PROJECTION_NOTE中各列的索引
     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;
 
+    // 内容解析器，用于与内容提供器进行交互
     private ContentResolver mContentResolver;
 
+    // 标志位，表示该便签是否是新创建的
     private boolean mIsCreate;
 
+    // 便签的唯一标识符
     private long mId;
 
+    // 便签的提醒日期
     private long mAlertDate;
 
+    // 便签的背景颜色标识符
     private int mBgColorId;
 
+    // 便签的创建日期
     private long mCreatedDate;
 
+    // 标志位，表示便签是否包含附件
     private int mHasAttachment;
 
+    // 便签的最后修改日期
     private long mModifiedDate;
 
+    // 便签的父便签标识符
     private long mParentId;
 
+    // 便签的简短摘要或标题
     private String mSnippet;
 
+    // 便签的类型（如普通便签、文件夹、系统文件夹等）
     private int mType;
 
+    // 与便签关联的小部件标识符
     private int mWidgetId;
 
+    // 便签的小部件类型
     private int mWidgetType;
 
+    // 便签的原始父便签标识符
     private long mOriginParent;
 
+    // 便签的版本号，用于数据同步和冲突检测
     private long mVersion;
 
+    // 用于存储便签属性的更改，以便后续提交到数据库
     private ContentValues mDiffNoteValues;
 
+    // 存储与便签相关的数据内容列表
     private ArrayList<SqlData> mDataList;
 
+    // 构造方法，创建一个新的SqlNote对象，初始化成员变量，并设置默认值
     public SqlNote(Context context) {
         mContext = context;
         mContentResolver = context.getContentResolver();
@@ -143,6 +150,7 @@ public class SqlNote {
         mDataList = new ArrayList<SqlData>();
     }
 
+    // 构造方法，从数据库游标中加载便签数据，初始化SqlNote对象
     public SqlNote(Context context, Cursor c) {
         mContext = context;
         mContentResolver = context.getContentResolver();
@@ -154,6 +162,7 @@ public class SqlNote {
         mDiffNoteValues = new ContentValues();
     }
 
+    // 构造方法，根据便签ID从数据库中加载便签数据，初始化SqlNote对象
     public SqlNote(Context context, long id) {
         mContext = context;
         mContentResolver = context.getContentResolver();
@@ -163,15 +172,15 @@ public class SqlNote {
         if (mType == Notes.TYPE_NOTE)
             loadDataContent();
         mDiffNoteValues = new ContentValues();
-
     }
 
+    // 根据便签ID从数据库中查询便签数据，并加载到当前对象中
     private void loadFromCursor(long id) {
         Cursor c = null;
         try {
             c = mContentResolver.query(Notes.CONTENT_NOTE_URI, PROJECTION_NOTE, "(_id=?)",
                     new String[] {
-                        String.valueOf(id)
+                            String.valueOf(id)
                     }, null);
             if (c != null) {
                 c.moveToNext();
@@ -185,6 +194,7 @@ public class SqlNote {
         }
     }
 
+    // 从数据库游标中加载便签数据到当前对象中
     private void loadFromCursor(Cursor c) {
         mId = c.getLong(ID_COLUMN);
         mAlertDate = c.getLong(ALERTED_DATE_COLUMN);
@@ -200,13 +210,14 @@ public class SqlNote {
         mVersion = c.getLong(VERSION_COLUMN);
     }
 
+    // 加载与当前便签相关的数据内容
     private void loadDataContent() {
         Cursor c = null;
         mDataList.clear();
         try {
             c = mContentResolver.query(Notes.CONTENT_DATA_URI, SqlData.PROJECTION_DATA,
                     "(note_id=?)", new String[] {
-                        String.valueOf(mId)
+                            String.valueOf(mId)
                     }, null);
             if (c != null) {
                 if (c.getCount() == 0) {
@@ -226,13 +237,14 @@ public class SqlNote {
         }
     }
 
+    // 从JSON对象中设置便签的内容和属性
     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)) {
@@ -248,7 +260,8 @@ 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;
+                long id = note.has(NoteColumns.ID) ? note
+                        .getLong(NoteColumns.ID) : INVALID_ID;
                 if (mIsCreate || mId != id) {
                     mDiffNoteValues.put(NoteColumns.ID, id);
                 }
@@ -359,6 +372,7 @@ public class SqlNote {
         return true;
     }
 
+    // 将便签的内容和属性转换为JSON对象
     public JSONObject getContent() {
         try {
             JSONObject js = new JSONObject();
@@ -407,39 +421,48 @@ public class SqlNote {
         return null;
     }
 
+    // 设置便签的父便签标识符
     public void setParentId(long id) {
         mParentId = id;
         mDiffNoteValues.put(NoteColumns.PARENT_ID, id);
     }
 
+    // 设置便签的Gtask ID
     public void setGtaskId(String gid) {
         mDiffNoteValues.put(NoteColumns.GTASK_ID, gid);
     }
 
+    // 设置便签的同步ID
     public void setSyncId(long syncId) {
         mDiffNoteValues.put(NoteColumns.SYNC_ID, syncId);
     }
 
+    // 重置便签的本地修改标志
     public void resetLocalModified() {
         mDiffNoteValues.put(NoteColumns.LOCAL_MODIFIED, 0);
     }
 
+    // 获取便签的唯一标识符
     public long getId() {
         return mId;
     }
 
+    // 获取便签的父便签标识符
     public long getParentId() {
         return mParentId;
     }
 
+    // 获取便签的简短摘要或标题
     public String getSnippet() {
         return mSnippet;
     }
 
+    // 判断便签是否为普通便签类型
     public boolean isNoteType() {
         return mType == Notes.TYPE_NOTE;
     }
 
+    // 将便签的更改提交到数据库，包括插入新便签或更新现有便签，并处理数据同步和冲突检测
     public void commit(boolean validateVersion) {
         if (mIsCreate) {
             if (mId == INVALID_ID && mDiffNoteValues.containsKey(NoteColumns.ID)) {
@@ -468,16 +491,16 @@ public class SqlNote {
                 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[] {
-                        String.valueOf(mId)
+                            String.valueOf(mId)
                     });
                 } else {
                     result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
-                            + NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)",
+                                    + NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)",
                             new String[] {
                                     String.valueOf(mId), String.valueOf(mVersion)
                             });
@@ -494,7 +517,7 @@ public class SqlNote {
             }
         }
 
-        // refresh local info
+        // 刷新本地信息
         loadFromCursor(mId);
         if (mType == Notes.TYPE_NOTE)
             loadDataContent();

src/main/java/net/micode/notes/gtask/data/Task.java

@@ -31,20 +31,27 @@ import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 
-
+// Task类继承自Node类，用于处理任务相关的操作，包括创建、更新、同步等
 public class Task extends Node {
+    // 日志标签，用于调试和日志记录
     private static final String TAG = Task.class.getSimpleName();
 
+    // 标志位，表示任务是否已完成
     private boolean mCompleted;
 
+    // 任务的备注信息
     private String mNotes;
 
+    // 任务的元数据信息
     private JSONObject mMetaInfo;
 
+    // 任务的前一个兄弟任务
     private Task mPriorSibling;
 
+    // 任务所属的任务列表
     private TaskList mParent;
 
+    // 构造方法，初始化任务对象
     public Task() {
         super();
         mCompleted = false;
@@ -54,21 +61,22 @@ public class Task extends Node {
         mMetaInfo = null;
     }
 
+    // 生成创建任务的JSON对象，用于与服务器交互
     public JSONObject getCreateAction(int actionId) {
         JSONObject js = new JSONObject();
 
         try {
-            // action_type
+            // 设置操作类型为创建
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                     GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);
 
-            // action_id
+            // 设置操作ID
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
 
-            // index
+            // 设置任务在父任务列表中的索引
             js.put(GTaskStringUtils.GTASK_JSON_INDEX, mParent.getChildTaskIndex(this));
 
-            // entity_delta
+            // 设置任务的基本信息
             JSONObject entity = new JSONObject();
             entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
             entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null");
@@ -79,17 +87,17 @@ public class Task extends Node {
             }
             js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
 
-            // parent_id
+            // 设置父任务列表的ID
             js.put(GTaskStringUtils.GTASK_JSON_PARENT_ID, mParent.getGid());
 
-            // dest_parent_type
+            // 设置目标父类型
             js.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT_TYPE,
                     GTaskStringUtils.GTASK_JSON_TYPE_GROUP);
 
-            // list_id
+            // 设置列表ID
             js.put(GTaskStringUtils.GTASK_JSON_LIST_ID, mParent.getGid());
 
-            // prior_sibling_id
+            // 设置前一个兄弟任务的ID（如果存在）
             if (mPriorSibling != null) {
                 js.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, mPriorSibling.getGid());
             }
@@ -103,21 +111,22 @@ public class Task extends Node {
         return js;
     }
 
+    // 生成更新任务的JSON对象，用于与服务器交互
     public JSONObject getUpdateAction(int actionId) {
         JSONObject js = new JSONObject();
 
         try {
-            // action_type
+            // 设置操作类型为更新
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                     GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
 
-            // action_id
+            // 设置操作ID
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
 
-            // id
+            // 设置任务ID
             js.put(GTaskStringUtils.GTASK_JSON_ID, getGid());
 
-            // entity_delta
+            // 设置任务的更新信息
             JSONObject entity = new JSONObject();
             entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
             if (getNotes() != null) {
@@ -135,35 +144,36 @@ public class Task extends Node {
         return js;
     }
 
+    // 从远程JSON对象中设置任务内容
     public void setContentByRemoteJSON(JSONObject js) {
         if (js != null) {
             try {
-                // id
+                // 设置任务ID
                 if (js.has(GTaskStringUtils.GTASK_JSON_ID)) {
                     setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
                 }
 
-                // last_modified
+                // 设置最后修改时间
                 if (js.has(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED)) {
                     setLastModified(js.getLong(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED));
                 }
 
-                // name
+                // 设置任务名称
                 if (js.has(GTaskStringUtils.GTASK_JSON_NAME)) {
                     setName(js.getString(GTaskStringUtils.GTASK_JSON_NAME));
                 }
 
-                // notes
+                // 设置任务备注
                 if (js.has(GTaskStringUtils.GTASK_JSON_NOTES)) {
                     setNotes(js.getString(GTaskStringUtils.GTASK_JSON_NOTES));
                 }
 
-                // deleted
+                // 设置任务是否已删除
                 if (js.has(GTaskStringUtils.GTASK_JSON_DELETED)) {
                     setDeleted(js.getBoolean(GTaskStringUtils.GTASK_JSON_DELETED));
                 }
 
-                // completed
+                // 设置任务是否已完成
                 if (js.has(GTaskStringUtils.GTASK_JSON_COMPLETED)) {
                     setCompleted(js.getBoolean(GTaskStringUtils.GTASK_JSON_COMPLETED));
                 }
@@ -175,21 +185,25 @@ public class Task extends Node {
         }
     }
 
+    // 从本地JSON对象中设置任务内容
     public void setContentByLocalJSON(JSONObject js) {
         if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)
                 || !js.has(GTaskStringUtils.META_HEAD_DATA)) {
-            Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
+            Log.w(TAG, "setContentByLocalJSON: nothing is available");
         }
 
         try {
+            // 获取任务的元数据
             JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
             JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
 
+            // 检查任务类型是否为普通任务
             if (note.getInt(NoteColumns.TYPE) != Notes.TYPE_NOTE) {
                 Log.e(TAG, "invalid type");
                 return;
             }
 
+            // 设置任务内容
             for (int i = 0; i < dataArray.length(); i++) {
                 JSONObject data = dataArray.getJSONObject(i);
                 if (TextUtils.equals(data.getString(DataColumns.MIME_TYPE), DataConstants.NOTE)) {
@@ -204,16 +218,18 @@ public class Task extends Node {
         }
     }
 
+    // 从任务内容生成本地JSON对象
     public JSONObject getLocalJSONFromContent() {
         String name = getName();
         try {
             if (mMetaInfo == null) {
-                // new task created from web
+                // 新创建的任务
                 if (name == null) {
                     Log.w(TAG, "the note seems to be an empty one");
                     return null;
                 }
 
+                // 创建JSON对象
                 JSONObject js = new JSONObject();
                 JSONObject note = new JSONObject();
                 JSONArray dataArray = new JSONArray();
@@ -225,10 +241,11 @@ public class Task extends Node {
                 js.put(GTaskStringUtils.META_HEAD_NOTE, note);
                 return js;
             } else {
-                // synced task
+                // 已同步的任务
                 JSONObject note = mMetaInfo.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
                 JSONArray dataArray = mMetaInfo.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
 
+                // 更新任务内容
                 for (int i = 0; i < dataArray.length(); i++) {
                     JSONObject data = dataArray.getJSONObject(i);
                     if (TextUtils.equals(data.getString(DataColumns.MIME_TYPE), DataConstants.NOTE)) {
@@ -247,6 +264,7 @@ public class Task extends Node {
         }
     }
 
+    // 设置任务的元数据信息
     public void setMetaInfo(MetaData metaData) {
         if (metaData != null && metaData.getNotes() != null) {
             try {
@@ -258,6 +276,7 @@ public class Task extends Node {
         }
     }
 
+    // 根据游标数据确定同步操作类型
     public int getSyncAction(Cursor c) {
         try {
             JSONObject noteInfo = null;
@@ -275,31 +294,32 @@ public class Task extends Node {
                 return SYNC_ACTION_UPDATE_LOCAL;
             }
 
-            // validate the note id now
+            // 验证任务ID是否匹配
             if (c.getLong(SqlNote.ID_COLUMN) != noteInfo.getLong(NoteColumns.ID)) {
                 Log.w(TAG, "note id doesn't match");
                 return SYNC_ACTION_UPDATE_LOCAL;
             }
 
             if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
-                // there is no local update
+                // 本地没有修改
                 if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
-                    // no update both side
+                    // 两边都没有更新
                     return SYNC_ACTION_NONE;
                 } else {
-                    // apply remote to local
+                    // 应用远程到本地
                     return SYNC_ACTION_UPDATE_LOCAL;
                 }
             } else {
-                // validate gtask id
+                // 验证Gtask ID是否匹配
                 if (!c.getString(SqlNote.GTASK_ID_COLUMN).equals(getGid())) {
                     Log.e(TAG, "gtask id doesn't match");
                     return SYNC_ACTION_ERROR;
                 }
                 if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
-                    // local modification only
+                    // 只有本地修改
                     return SYNC_ACTION_UPDATE_REMOTE;
                 } else {
+                    // 同步冲突
                     return SYNC_ACTION_UPDATE_CONFLICT;
                 }
             }
@@ -311,41 +331,49 @@ public class Task extends Node {
         return SYNC_ACTION_ERROR;
     }
 
+    // 判断任务是否值得保存
     public boolean isWorthSaving() {
         return mMetaInfo != null || (getName() != null && getName().trim().length() > 0)
                 || (getNotes() != null && getNotes().trim().length() > 0);
     }
 
+    // 设置任务是否已完成
     public void setCompleted(boolean completed) {
         this.mCompleted = completed;
     }
 
+    // 设置任务备注
     public void setNotes(String notes) {
         this.mNotes = notes;
     }
 
+    // 设置任务的前一个兄弟任务
     public void setPriorSibling(Task priorSibling) {
         this.mPriorSibling = priorSibling;
     }
 
+    // 设置任务所属的任务列表
     public void setParent(TaskList parent) {
         this.mParent = parent;
     }
 
+    // 获取任务是否已完成
     public boolean getCompleted() {
         return this.mCompleted;
     }
 
+    // 获取任务备注
     public String getNotes() {
         return this.mNotes;
     }
 
+    // 获取任务的前一个兄弟任务
     public Task getPriorSibling() {
         return this.mPriorSibling;
     }
 
+    // 获取任务所属的任务列表
     public TaskList getParent() {
         return this.mParent;
     }
-
 }

src/main/java/net/micode/notes/gtask/data/TaskList.java

@@ -29,35 +29,40 @@ import org.json.JSONObject;
 
 import java.util.ArrayList;
 
-
+// TaskList类继承自Node类，用于管理任务列表及其子任务
 public class TaskList extends Node {
+    // 日志标签，用于调试和日志记录
     private static final String TAG = TaskList.class.getSimpleName();
 
+    // 任务列表的索引
     private int mIndex;
 
+    // 子任务列表
     private ArrayList<Task> mChildren;
 
+    // 构造方法，初始化任务列表
     public TaskList() {
         super();
         mChildren = new ArrayList<Task>();
         mIndex = 1;
     }
 
+    // 生成创建任务列表的JSON对象，用于与服务器交互
     public JSONObject getCreateAction(int actionId) {
         JSONObject js = new JSONObject();
 
         try {
-            // action_type
+            // 设置操作类型为创建
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                     GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);
 
-            // action_id
+            // 设置操作ID
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
 
-            // index
+            // 设置任务列表的索引
             js.put(GTaskStringUtils.GTASK_JSON_INDEX, mIndex);
 
-            // entity_delta
+            // 设置任务列表的基本信息
             JSONObject entity = new JSONObject();
             entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
             entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null");
@@ -74,21 +79,22 @@ public class TaskList extends Node {
         return js;
     }
 
+    // 生成更新任务列表的JSON对象，用于与服务器交互
     public JSONObject getUpdateAction(int actionId) {
         JSONObject js = new JSONObject();
 
         try {
-            // action_type
+            // 设置操作类型为更新
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                     GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
 
-            // action_id
+            // 设置操作ID
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
 
-            // id
+            // 设置任务列表ID
             js.put(GTaskStringUtils.GTASK_JSON_ID, getGid());
 
-            // entity_delta
+            // 设置任务列表的更新信息
             JSONObject entity = new JSONObject();
             entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
             entity.put(GTaskStringUtils.GTASK_JSON_DELETED, getDeleted());
@@ -103,20 +109,21 @@ public class TaskList extends Node {
         return js;
     }
 
+    // 从远程JSON对象中设置任务列表内容
     public void setContentByRemoteJSON(JSONObject js) {
         if (js != null) {
             try {
-                // id
+                // 设置任务列表ID
                 if (js.has(GTaskStringUtils.GTASK_JSON_ID)) {
                     setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
                 }
 
-                // last_modified
+                // 设置最后修改时间
                 if (js.has(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED)) {
                     setLastModified(js.getLong(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED));
                 }
 
-                // name
+                // 设置任务列表名称
                 if (js.has(GTaskStringUtils.GTASK_JSON_NAME)) {
                     setName(js.getString(GTaskStringUtils.GTASK_JSON_NAME));
                 }
@@ -129,14 +136,17 @@ public class TaskList extends Node {
         }
     }
 
+    // 从本地JSON对象中设置任务列表内容
     public void setContentByLocalJSON(JSONObject js) {
         if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)) {
-            Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
+            Log.w(TAG, "setContentByLocalJSON: nothing is available");
         }
 
         try {
+            // 获取任务列表的元数据
             JSONObject folder = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
 
+            // 根据任务列表类型设置名称
             if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {
                 String name = folder.getString(NoteColumns.SNIPPET);
                 setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + name);
@@ -157,11 +167,13 @@ public class TaskList extends Node {
         }
     }
 
+    // 从任务列表内容生成本地JSON对象
     public JSONObject getLocalJSONFromContent() {
         try {
             JSONObject js = new JSONObject();
             JSONObject folder = new JSONObject();
 
+            // 获取任务列表名称
             String folderName = getName();
             if (getName().startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX))
                 folderName = folderName.substring(GTaskStringUtils.MIUI_FOLDER_PREFFIX.length(),
@@ -183,28 +195,29 @@ public class TaskList extends Node {
         }
     }
 
+    // 根据游标数据确定同步操作类型
     public int getSyncAction(Cursor c) {
         try {
             if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
-                // there is no local update
+                // 本地没有修改
                 if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
-                    // no update both side
+                    // 两边都没有更新
                     return SYNC_ACTION_NONE;
                 } else {
-                    // apply remote to local
+                    // 应用远程到本地
                     return SYNC_ACTION_UPDATE_LOCAL;
                 }
             } else {
-                // validate gtask id
+                // 验证Gtask ID是否匹配
                 if (!c.getString(SqlNote.GTASK_ID_COLUMN).equals(getGid())) {
                     Log.e(TAG, "gtask id doesn't match");
                     return SYNC_ACTION_ERROR;
                 }
                 if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
-                    // local modification only
+                    // 只有本地修改
                     return SYNC_ACTION_UPDATE_REMOTE;
                 } else {
-                    // for folder conflicts, just apply local modification
+                    // 对于文件夹冲突，仅应用本地修改
                     return SYNC_ACTION_UPDATE_REMOTE;
                 }
             }
@@ -216,16 +229,18 @@ public class TaskList extends Node {
         return SYNC_ACTION_ERROR;
     }
 
+    // 获取子任务数量
     public int getChildTaskCount() {
         return mChildren.size();
     }
 
+    // 添加子任务到任务列表
     public boolean addChildTask(Task task) {
         boolean ret = false;
         if (task != null && !mChildren.contains(task)) {
             ret = mChildren.add(task);
             if (ret) {
-                // need to set prior sibling and parent
+                // 设置子任务的前一个兄弟任务和父任务列表
                 task.setPriorSibling(mChildren.isEmpty() ? null : mChildren
                         .get(mChildren.size() - 1));
                 task.setParent(this);
@@ -234,6 +249,7 @@ public class TaskList extends Node {
         return ret;
     }
 
+    // 在指定位置添加子任务
     public boolean addChildTask(Task task, int index) {
         if (index < 0 || index > mChildren.size()) {
             Log.e(TAG, "add child task: invalid index");
@@ -244,7 +260,7 @@ public class TaskList extends Node {
         if (task != null && pos == -1) {
             mChildren.add(index, task);
 
-            // update the task list
+            // 更新子任务列表
             Task preTask = null;
             Task afterTask = null;
             if (index != 0)
@@ -260,6 +276,7 @@ public class TaskList extends Node {
         return true;
     }
 
+    // 从任务列表中移除子任务
     public boolean removeChildTask(Task task) {
         boolean ret = false;
         int index = mChildren.indexOf(task);
@@ -267,11 +284,11 @@ public class TaskList extends Node {
             ret = mChildren.remove(task);
 
             if (ret) {
-                // reset prior sibling and parent
+                // 重置子任务的前一个兄弟任务和父任务列表
                 task.setPriorSibling(null);
                 task.setParent(null);
 
-                // update the task list
+                // 更新子任务列表
                 if (index != mChildren.size()) {
                     mChildren.get(index).setPriorSibling(
                             index == 0 ? null : mChildren.get(index - 1));
@@ -281,6 +298,7 @@ public class TaskList extends Node {
         return ret;
     }
 
+    // 移动子任务到指定位置
     public boolean moveChildTask(Task task, int index) {
 
         if (index < 0 || index >= mChildren.size()) {
@@ -299,6 +317,7 @@ public class TaskList extends Node {
         return (removeChildTask(task) && addChildTask(task, index));
     }
 
+    // 根据GID查找子任务
     public Task findChildTaskByGid(String gid) {
         for (int i = 0; i < mChildren.size(); i++) {
             Task t = mChildren.get(i);
@@ -309,10 +328,12 @@ public class TaskList extends Node {
         return null;
     }
 
+    // 获取子任务在列表中的索引
     public int getChildTaskIndex(Task task) {
         return mChildren.indexOf(task);
     }
 
+    // 根据索引获取子任务
     public Task getChildTaskByIndex(int index) {
         if (index < 0 || index >= mChildren.size()) {
             Log.e(TAG, "getTaskByIndex: invalid index");
@@ -321,6 +342,7 @@ public class TaskList extends Node {
         return mChildren.get(index);
     }
 
+    // 根据GID获取子任务
     public Task getChilTaskByGid(String gid) {
         for (Task task : mChildren) {
             if (task.getGid().equals(gid))
@@ -329,14 +351,17 @@ public class TaskList extends Node {
         return null;
     }
 
+    // 获取子任务列表
     public ArrayList<Task> getChildTaskList() {
         return this.mChildren;
     }
 
+    // 设置任务列表的索引
     public void setIndex(int index) {
         this.mIndex = index;
     }
 
+    // 获取任务列表的索引
     public int getIndex() {
         return this.mIndex;
     }