第五次提交

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

@@ -24,37 +24,71 @@ import net.micode.notes.tool.GTaskStringUtils;
 import org.json.JSONException;
 import org.json.JSONObject;
 
-
+/**
+ * MetaData类用于管理与Google Tasks同步相关的元数据信息
+ * 继承自Task类，专用于处理任务的元数据存储
+ */
 public class MetaData extends Task {
     private final static String TAG = MetaData.class.getSimpleName();
 
+    // 关联的Google Tasks ID
     private String mRelatedGid = null;
 
+    /**
+     * 设置元数据信息
+     * 将关联的gid和元数据信息存入JSON对象，并设置为任务的notes字段
+     *
+     * @param gid 关联的Google Tasks ID
+     * @param metaInfo 包含元数据的JSON对象
+     */
     public void setMeta(String gid, JSONObject metaInfo) {
         try {
+            // 将关联的gid添加到元数据JSON对象中
             metaInfo.put(GTaskStringUtils.META_HEAD_GTASK_ID, gid);
         } catch (JSONException e) {
             Log.e(TAG, "failed to put related gid");
         }
+        // 将JSON对象转换为字符串存储到notes字段
         setNotes(metaInfo.toString());
+        // 设置任务名称为元数据专用名称
         setName(GTaskStringUtils.META_NOTE_NAME);
     }
 
+    /**
+     * 获取关联的Google Tasks ID
+     *
+     * @return 关联的gid，如果不存在则返回null
+     */
     public String getRelatedGid() {
         return mRelatedGid;
     }
 
+    /**
+     * 判断该元数据是否值得保存
+     * 当notes字段不为空时认为值得保存
+     *
+     * @return 如果notes不为空返回true，否则返回false
+     */
     @Override
     public boolean isWorthSaving() {
         return getNotes() != null;
     }
 
+    /**
+     * 根据远程JSON数据设置元数据内容
+     * 从notes字段解析JSON对象并提取关联的gid
+     *
+     * @param js 包含远程数据的JSON对象
+     */
     @Override
     public void setContentByRemoteJSON(JSONObject js) {
+        // 调用父类方法设置通用内容
         super.setContentByRemoteJSON(js);
         if (getNotes() != null) {
             try {
+                // 解析notes字段中的JSON字符串
                 JSONObject metaInfo = new JSONObject(getNotes().trim());
+                // 提取关联的gid
                 mRelatedGid = metaInfo.getString(GTaskStringUtils.META_HEAD_GTASK_ID);
             } catch (JSONException e) {
                 Log.w(TAG, "failed to get related gid");
@@ -63,20 +97,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 无返回值
+     * @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/net/micode/notes/gtask/data/SqlData.java

@@ -34,43 +34,51 @@ import net.micode.notes.gtask.exception.ActionFailureException;
 import org.json.JSONException;
 import org.json.JSONObject;
 
-
+/**
+ * SqlData类用于管理与数据库交互的笔记数据
+ * 提供从JSON对象加载数据、将数据保存到JSON对象、以及将数据提交到数据库的功能
+ */
 public class SqlData {
     private static final String TAG = SqlData.class.getSimpleName();
 
+    // 无效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
     };
 
+    // 各列在查询结果中的索引位置
     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;
-
+    // 数据ID
     private long mDataId;
-
+    // 数据MIME类型
     private String mDataMimeType;
-
+    // 数据内容
     private String mDataContent;
-
+    // 数据附加信息1
     private long mDataContentData1;
-
+    // 数据附加信息3
     private String mDataContentData3;
-
+    // 存储有变化的数据值
     private ContentValues mDiffDataValues;
 
+    /**
+     * 构造函数 - 用于创建新的SQL数据对象
+     *
+     * @param context 应用上下文，用于获取ContentResolver
+     */
     public SqlData(Context context) {
         mContentResolver = context.getContentResolver();
         mIsCreate = true;
@@ -82,6 +90,12 @@ public class SqlData {
         mDiffDataValues = new ContentValues();
     }
 
+    /**
+     * 构造函数 - 用于从数据库游标创建SQL数据对象
+     *
+     * @param context 应用上下文
+     * @param c 包含数据的数据库游标
+     */
     public SqlData(Context context, Cursor c) {
         mContentResolver = context.getContentResolver();
         mIsCreate = false;
@@ -89,6 +103,11 @@ 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,7 +116,15 @@ 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 {
+        // 从JSON对象获取各字段值，不存在时使用默认值
         long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID;
         if (mIsCreate || mDataId != dataId) {
             mDiffDataValues.put(DataColumns.ID, dataId);
@@ -130,6 +157,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,30 +177,43 @@ public class SqlData {
         return js;
     }
 
+    /**
+     * 将数据提交到数据库
+     * 新建或更新数据库中的笔记数据记录
+     *
+     * @param noteId 关联的笔记ID
+     * @param validateVersion 是否验证版本
+     * @param version 版本号，用于验证
+     */
     public void commit(long noteId, boolean validateVersion, long version) {
-
         if (mIsCreate) {
+            // 新建数据时，如果ID无效且已设置ID字段，则移除ID设置
             if (mDataId == INVALID_ID && mDiffDataValues.containsKey(DataColumns.ID)) {
                 mDiffDataValues.remove(DataColumns.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);
                 } else {
+                    // 验证版本时，确保更新的是正确版本的数据
                     result = mContentResolver.update(ContentUris.withAppendedId(
-                            Notes.CONTENT_DATA_URI, mDataId), mDiffDataValues,
+                                    Notes.CONTENT_DATA_URI, mDataId), mDiffDataValues,
                             " ? in (SELECT " + NoteColumns.ID + " FROM " + TABLE.NOTE
                                     + " WHERE " + NoteColumns.VERSION + "=?)", new String[] {
                                     String.valueOf(noteId), String.valueOf(version)
@@ -179,11 +225,17 @@ public class SqlData {
             }
         }
 
+        // 提交后清除差异值并标记为非新建状态
         mDiffDataValues.clear();
         mIsCreate = false;
     }
 
+    /**
+     * 获取数据ID
+     *
+     * @return 数据ID
+     */
     public long getId() {
         return mDataId;
     }
-}
+}

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

@@ -1,17 +1,5 @@
 /*
- * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net)
+ * 版权声明及许可协议（同上）
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *        http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
  */
 
 package net.micode.notes.gtask.data;
@@ -21,9 +9,6 @@ import android.text.TextUtils;
 import android.util.Log;
 
 import net.micode.notes.data.Notes;
-import net.micode.notes.data.Notes.DataColumns;
-import net.micode.notes.data.Notes.DataConstants;
-import net.micode.notes.data.Notes.NoteColumns;
 import net.micode.notes.gtask.exception.ActionFailureException;
 import net.micode.notes.tool.GTaskStringUtils;
 
@@ -31,19 +16,17 @@ import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 
-
+/**
+ * 表示Google Tasks中的任务项，处理任务数据与JSON/数据库的转换
+ */
 public class Task extends Node {
     private static final String TAG = Task.class.getSimpleName();
 
-    private boolean mCompleted;
+    private boolean mCompleted;      // 任务完成状态
-
+    private String mNotes;           // 任务备注信息
-    private String mNotes;
+    private JSONObject mMetaInfo;    // 任务元数据（本地存储格式）
-
+    private Task mPriorSibling;      // 排序用：前一个兄弟任务
-    private JSONObject mMetaInfo;
+    private TaskList mParent;        // 所属任务列表
-
-    private Task mPriorSibling;
-
-    private TaskList mParent;
 
     public Task() {
         super();
@@ -54,142 +37,108 @@ public class Task extends Node {
         mMetaInfo = null;
     }
 
+    /**
+     * 生成创建任务的JSON请求
+     * @param actionId 操作ID
+     * @return 创建任务的JSON对象
+     */
     public JSONObject getCreateAction(int actionId) {
+        // 构建创建任务所需的JSON结构
         JSONObject js = new JSONObject();
-
         try {
-            // action_type
+            js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE, GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);
-            js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
-                    GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);
-
-            // action_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");
-            entity.put(GTaskStringUtils.GTASK_JSON_ENTITY_TYPE,
+            entity.put(GTaskStringUtils.GTASK_JSON_ENTITY_TYPE, GTaskStringUtils.GTASK_JSON_TYPE_TASK);
-                    GTaskStringUtils.GTASK_JSON_TYPE_TASK);
+            if (getNotes() != null) entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes());
-            if (getNotes() != null) {
-                entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes());
-            }
             js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
 
-            // parent_id
+            // 设置任务的父级和排序信息
             js.put(GTaskStringUtils.GTASK_JSON_PARENT_ID, mParent.getGid());
-
+            js.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT_TYPE, GTaskStringUtils.GTASK_JSON_TYPE_GROUP);
-            // dest_parent_type
-            js.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT_TYPE,
-                    GTaskStringUtils.GTASK_JSON_TYPE_GROUP);
-
-            // list_id
             js.put(GTaskStringUtils.GTASK_JSON_LIST_ID, mParent.getGid());
-
-            // prior_sibling_id
             if (mPriorSibling != null) {
                 js.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, mPriorSibling.getGid());
             }
-
         } catch (JSONException e) {
-            Log.e(TAG, e.toString());
+            Log.e(TAG, "生成创建任务JSON失败", e);
-            e.printStackTrace();
             throw new ActionFailureException("fail to generate task-create jsonobject");
         }
-
         return js;
     }
 
+    /**
+     * 生成更新任务的JSON请求
+     * @param actionId 操作ID
+     * @return 更新任务的JSON对象
+     */
     public JSONObject getUpdateAction(int actionId) {
+        // 构建更新任务所需的JSON结构
         JSONObject js = new JSONObject();
-
         try {
-            // action_type
+            js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE, GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
-            js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
-                    GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
-
-            // action_id
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
-
-            // id
             js.put(GTaskStringUtils.GTASK_JSON_ID, getGid());
 
-            // entity_delta
+            // 设置要更新的任务属性
             JSONObject entity = new JSONObject();
             entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
-            if (getNotes() != null) {
+            if (getNotes() != null) entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes());
-                entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes());
-            }
             entity.put(GTaskStringUtils.GTASK_JSON_DELETED, getDeleted());
             js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
-
         } catch (JSONException e) {
-            Log.e(TAG, e.toString());
+            Log.e(TAG, "生成更新任务JSON失败", e);
-            e.printStackTrace();
             throw new ActionFailureException("fail to generate task-update jsonobject");
         }
-
         return js;
     }
 
+    /**
+     * 从远程JSON数据设置任务内容
+     * @param js 远程服务器返回的JSON对象
+     */
     public void setContentByRemoteJSON(JSONObject js) {
         if (js != null) {
             try {
-                // id
+                // 解析远程任务数据并设置本地属性
-                if (js.has(GTaskStringUtils.GTASK_JSON_ID)) {
+                if (js.has(GTaskStringUtils.GTASK_JSON_ID)) setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
-                    setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
+                if (js.has(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED)) setLastModified(js.getLong(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED));
-                }
+                if (js.has(GTaskStringUtils.GTASK_JSON_NAME)) setName(js.getString(GTaskStringUtils.GTASK_JSON_NAME));
-
+                if (js.has(GTaskStringUtils.GTASK_JSON_NOTES)) setNotes(js.getString(GTaskStringUtils.GTASK_JSON_NOTES));
-                // last_modified
+                if (js.has(GTaskStringUtils.GTASK_JSON_DELETED)) setDeleted(js.getBoolean(GTaskStringUtils.GTASK_JSON_DELETED));
-                if (js.has(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED)) {
+                if (js.has(GTaskStringUtils.GTASK_JSON_COMPLETED)) setCompleted(js.getBoolean(GTaskStringUtils.GTASK_JSON_COMPLETED));
-                    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));
-                }
             } catch (JSONException e) {
-                Log.e(TAG, e.toString());
+                Log.e(TAG, "解析远程JSON失败", e);
-                e.printStackTrace();
                 throw new ActionFailureException("fail to get task content from jsonobject");
             }
         }
     }
 
+    /**
+     * 从本地JSON数据设置任务内容
+     * @param js 本地数据库中的JSON对象
+     */
     public void setContentByLocalJSON(JSONObject js) {
-        if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)
+        if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE) || !js.has(GTaskStringUtils.META_HEAD_DATA)) {
-                || !js.has(GTaskStringUtils.META_HEAD_DATA)) {
+            Log.w(TAG, "本地JSON数据不完整");
-            Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
+            return;
         }
-
         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");
+                Log.e(TAG, "无效的笔记类型");
                 return;
             }
 
+            // 从数据列表中提取任务名称
             for (int i = 0; i < dataArray.length(); i++) {
                 JSONObject data = dataArray.getJSONObject(i);
                 if (TextUtils.equals(data.getString(DataColumns.MIME_TYPE), DataConstants.NOTE)) {
@@ -197,23 +146,20 @@ public class Task extends Node {
                     break;
                 }
             }
-
         } catch (JSONException e) {
-            Log.e(TAG, e.toString());
+            Log.e(TAG, "解析本地JSON失败", e);
-            e.printStackTrace();
         }
     }
 
+    /**
+     * 将任务内容转换为本地存储的JSON格式
+     * @return 本地JSON对象
+     */
     public JSONObject getLocalJSONFromContent() {
         String name = getName();
         try {
             if (mMetaInfo == null) {
-                // new task created from web
+                // 新建任务：创建基础JSON结构
-                if (name == null) {
-                    Log.w(TAG, "the note seems to be an empty one");
-                    return null;
-                }
-
                 JSONObject js = new JSONObject();
                 JSONObject note = new JSONObject();
                 JSONArray dataArray = new JSONArray();
@@ -225,14 +171,15 @@ public class Task extends Node {
                 js.put(GTaskStringUtils.META_HEAD_NOTE, note);
                 return js;
             } else {
-                // synced task
+                // 已有任务：更新现有JSON结构
                 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)) {
-                        data.put(DataColumns.CONTENT, getName());
+                        data.put(DataColumns.CONTENT, name);
                         break;
                     }
                 }
@@ -241,111 +188,82 @@ public class Task extends Node {
                 return mMetaInfo;
             }
         } catch (JSONException e) {
-            Log.e(TAG, e.toString());
+            Log.e(TAG, "生成本地JSON失败", e);
-            e.printStackTrace();
             return null;
         }
     }
 
+    /**
+     * 设置任务元数据信息
+     * @param metaData 元数据对象
+     */
     public void setMetaInfo(MetaData metaData) {
         if (metaData != null && metaData.getNotes() != null) {
             try {
                 mMetaInfo = new JSONObject(metaData.getNotes());
             } catch (JSONException e) {
-                Log.w(TAG, e.toString());
+                Log.w(TAG, "解析元数据失败", e);
                 mMetaInfo = null;
             }
         }
     }
 
+    /**
+     * 判断任务同步操作类型
+     * @param c 数据库游标
+     * @return 同步动作类型（如本地更新、远程更新等）
+     */
     public int getSyncAction(Cursor c) {
         try {
-            JSONObject noteInfo = null;
+            JSONObject noteInfo = mMetaInfo != null ? mMetaInfo.optJSONObject(GTaskStringUtils.META_HEAD_NOTE) : null;
-            if (mMetaInfo != null && mMetaInfo.has(GTaskStringUtils.META_HEAD_NOTE)) {
-                noteInfo = mMetaInfo.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
-            }
 
-            if (noteInfo == null) {
+            // 验证元数据完整性
-                Log.w(TAG, "it seems that note meta has been deleted");
+            if (noteInfo == null) return SYNC_ACTION_UPDATE_REMOTE;
-                return SYNC_ACTION_UPDATE_REMOTE;
+            if (!noteInfo.has(NoteColumns.ID)) return SYNC_ACTION_UPDATE_LOCAL;
-            }
-
-            if (!noteInfo.has(NoteColumns.ID)) {
-                Log.w(TAG, "remote note id seems to be deleted");
-                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
+                return c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified() ?
-                if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
+                        SYNC_ACTION_NONE : SYNC_ACTION_UPDATE_LOCAL;
-                    // no update both side
-                    return SYNC_ACTION_NONE;
-                } else {
-                    // apply remote to local
-                    return SYNC_ACTION_UPDATE_LOCAL;
-                }
             } else {
-                // validate 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()) {
+                return c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified() ?
-                    // local modification only
+                        SYNC_ACTION_UPDATE_REMOTE : SYNC_ACTION_UPDATE_CONFLICT;
-                    return SYNC_ACTION_UPDATE_REMOTE;
-                } else {
-                    return SYNC_ACTION_UPDATE_CONFLICT;
-                }
             }
         } catch (Exception e) {
-            Log.e(TAG, e.toString());
+            Log.e(TAG, "获取同步动作失败", e);
-            e.printStackTrace();
+            return SYNC_ACTION_ERROR;
         }
-
-        return SYNC_ACTION_ERROR;
     }
 
+    /**
+     * 判断任务是否值得保存（非空检查）
+     * @return true/false
+     */
     public boolean isWorthSaving() {
-        return mMetaInfo != null || (getName() != null && getName().trim().length() > 0)
+        return mMetaInfo != null ||
-                || (getNotes() != null && getNotes().trim().length() > 0);
+                (getName() != null && getName().trim().length() > 0) ||
+                (getNotes() != null && getNotes().trim().length() > 0);
     }
 
-    public void setCompleted(boolean completed) {
+    // ------------------------
-        this.mCompleted = completed;
+    // Getters and Setters
-    }
+    // ------------------------
-
-    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() {
+    public void setCompleted(boolean completed) { this.mCompleted = completed; }
-        return this.mCompleted;
+    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 String getNotes() {
-        return this.mNotes;
-    }
-
-    public Task getPriorSibling() {
-        return this.mPriorSibling;
-    }
-
-    public TaskList getParent() {
-        return this.mParent;
-    }
 
-}
+    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/net/micode/notes/gtask/data/TaskList.java

@@ -1,17 +1,5 @@
 /*
- * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net)
+ * 版权声明及许可协议（同上）
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *        http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
  */
 
 package net.micode.notes.gtask.data;
@@ -29,13 +17,14 @@ import org.json.JSONObject;
 
 import java.util.ArrayList;
 
-
+/**
+ * 表示Google Tasks中的任务列表，管理多个任务项
+ */
 public class TaskList extends Node {
     private static final String TAG = TaskList.class.getSimpleName();
 
-    private int mIndex;
+    private int mIndex;                // 任务列表排序索引
-
+    private ArrayList<Task> mChildren; // 子任务列表
-    private ArrayList<Task> mChildren;
 
     public TaskList() {
         super();
@@ -43,200 +32,198 @@ public class TaskList extends Node {
         mIndex = 1;
     }
 
+    /**
+     * 生成创建任务列表的JSON请求
+     * @param actionId 操作ID
+     * @return 创建任务列表的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);
-            js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
-                    GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);
-
-            // action_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");
-            entity.put(GTaskStringUtils.GTASK_JSON_ENTITY_TYPE,
+            entity.put(GTaskStringUtils.GTASK_JSON_ENTITY_TYPE, GTaskStringUtils.GTASK_JSON_TYPE_GROUP);
-                    GTaskStringUtils.GTASK_JSON_TYPE_GROUP);
             js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
-
         } catch (JSONException e) {
-            Log.e(TAG, e.toString());
+            Log.e(TAG, "生成创建任务列表JSON失败", e);
-            e.printStackTrace();
             throw new ActionFailureException("fail to generate tasklist-create jsonobject");
         }
-
         return js;
     }
 
+    /**
+     * 生成更新任务列表的JSON请求
+     * @param actionId 操作ID
+     * @return 更新任务列表的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);
-            js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
-                    GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
-
-            // action_id
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
-
-            // 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());
             js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
-
         } catch (JSONException e) {
-            Log.e(TAG, e.toString());
+            Log.e(TAG, "生成更新任务列表JSON失败", e);
-            e.printStackTrace();
             throw new ActionFailureException("fail to generate tasklist-update jsonobject");
         }
-
         return js;
     }
 
+    /**
+     * 从远程JSON数据设置任务列表内容
+     * @param js 远程服务器返回的JSON对象
+     */
     public void setContentByRemoteJSON(JSONObject js) {
         if (js != null) {
             try {
-                // id
+                // 解析远程任务列表数据并设置本地属性
-                if (js.has(GTaskStringUtils.GTASK_JSON_ID)) {
+                if (js.has(GTaskStringUtils.GTASK_JSON_ID)) setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
-                    setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
+                if (js.has(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED)) setLastModified(js.getLong(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED));
-                }
+                if (js.has(GTaskStringUtils.GTASK_JSON_NAME)) setName(js.getString(GTaskStringUtils.GTASK_JSON_NAME));
-
-                // 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));
-                }
-
             } catch (JSONException e) {
-                Log.e(TAG, e.toString());
+                Log.e(TAG, "解析远程JSON失败", e);
-                e.printStackTrace();
                 throw new ActionFailureException("fail to get tasklist content from jsonobject");
             }
         }
     }
 
+    /**
+     * 从本地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");
+            Log.w(TAG, "本地JSON数据不完整");
+            return;
         }
-
         try {
             JSONObject folder = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
+            int type = folder.getInt(NoteColumns.TYPE);
 
-            if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {
+            // 根据文件夹类型设置名称（添加前缀区分）
-                String name = folder.getString(NoteColumns.SNIPPET);
+            if (type == Notes.TYPE_FOLDER) {
-                setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + name);
+                setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + folder.getString(NoteColumns.SNIPPET));
-            } else if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM) {
+            } else if (type == Notes.TYPE_SYSTEM) {
                 if (folder.getLong(NoteColumns.ID) == Notes.ID_ROOT_FOLDER)
                     setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_DEFAULT);
                 else if (folder.getLong(NoteColumns.ID) == Notes.ID_CALL_RECORD_FOLDER)
-                    setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX
+                    setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_CALL_NOTE);
-                            + GTaskStringUtils.FOLDER_CALL_NOTE);
                 else
-                    Log.e(TAG, "invalid system folder");
+                    Log.e(TAG, "无效的系统文件夹");
             } else {
-                Log.e(TAG, "error type");
+                Log.e(TAG, "错误的文件夹类型");
             }
         } catch (JSONException e) {
-            Log.e(TAG, e.toString());
+            Log.e(TAG, "解析本地JSON失败", e);
-            e.printStackTrace();
         }
     }
 
+    /**
+     * 将任务列表内容转换为本地存储的JSON格式
+     * @return 本地JSON对象
+     */
     public JSONObject getLocalJSONFromContent() {
         try {
             JSONObject js = new JSONObject();
             JSONObject folder = new JSONObject();
 
+            // 移除前缀并设置文件夹名称和类型
             String folderName = getName();
-            if (getName().startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX))
+            if (folderName.startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX))
-                folderName = folderName.substring(GTaskStringUtils.MIUI_FOLDER_PREFFIX.length(),
+                folderName = folderName.substring(GTaskStringUtils.MIUI_FOLDER_PREFFIX.length());
-                        folderName.length());
             folder.put(NoteColumns.SNIPPET, folderName);
-            if (folderName.equals(GTaskStringUtils.FOLDER_DEFAULT)
+
-                    || folderName.equals(GTaskStringUtils.FOLDER_CALL_NOTE))
+            // 根据名称判断文件夹类型（系统文件夹或普通文件夹）
+            if (folderName.equals(GTaskStringUtils.FOLDER_DEFAULT) || folderName.equals(GTaskStringUtils.FOLDER_CALL_NOTE))
                 folder.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
             else
                 folder.put(NoteColumns.TYPE, Notes.TYPE_FOLDER);
 
             js.put(GTaskStringUtils.META_HEAD_NOTE, folder);
-
             return js;
         } catch (JSONException e) {
-            Log.e(TAG, e.toString());
+            Log.e(TAG, "生成本地JSON失败", e);
-            e.printStackTrace();
             return null;
         }
     }
 
+    /**
+     * 判断任务列表同步操作类型
+     * @param c 数据库游标
+     * @return 同步动作类型（如本地更新、远程更新等）
+     */
     public int getSyncAction(Cursor c) {
         try {
+            // 根据本地修改标记和同步时间决定同步方向
             if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
-                // there is no local update
+                return c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified() ?
-                if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
+                        SYNC_ACTION_NONE : SYNC_ACTION_UPDATE_LOCAL;
-                    // 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 c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified() ?
-                    return SYNC_ACTION_UPDATE_REMOTE;
+                        SYNC_ACTION_UPDATE_REMOTE : SYNC_ACTION_UPDATE_REMOTE;
-                } else {
-                    // for folder conflicts, just apply local modification
-                    return SYNC_ACTION_UPDATE_REMOTE;
-                }
             }
         } catch (Exception e) {
-            Log.e(TAG, e.toString());
+            Log.e(TAG, "获取同步动作失败", e);
-            e.printStackTrace();
+            return SYNC_ACTION_ERROR;
         }
-
-        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)) {
             ret = mChildren.add(task);
             if (ret) {
-                // need to set prior sibling and parent
+                // 设置任务的前置兄弟和父列表
-                task.setPriorSibling(mChildren.isEmpty() ? null : mChildren
+                task.setPriorSibling(mChildren.isEmpty() ? null : mChildren.get(mChildren.size() - 1));
-                        .get(mChildren.size() - 1));
                 task.setParent(this);
             }
         }
         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");
+            Log.e(TAG, "添加子任务：无效索引");
             return false;
         }
 
@@ -244,83 +231,107 @@ public class TaskList extends Node {
         if (task != null && pos == -1) {
             mChildren.add(index, task);
 
-            // update the task list
+            // 更新前后任务的前置兄弟关系
-            Task preTask = null;
+            Task preTask = (index != 0) ? mChildren.get(index - 1) : null;
-            Task afterTask = null;
+            Task afterTask = (index != mChildren.size() - 1) ? mChildren.get(index + 1) : null;
-            if (index != 0)
-                preTask = mChildren.get(index - 1);
-            if (index != mChildren.size() - 1)
-                afterTask = mChildren.get(index + 1);
 
             task.setPriorSibling(preTask);
-            if (afterTask != null)
+            if (afterTask != null) afterTask.setPriorSibling(task);
-                afterTask.setPriorSibling(task);
         }
-
         return true;
     }
 
+    /**
+     * 移除子任务
+     * @param task 要移除的任务
+     * @return 移除成功与否
+     */
     public boolean removeChildTask(Task task) {
         boolean ret = false;
         int index = mChildren.indexOf(task);
         if (index != -1) {
             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(
+                    mChildren.get(index).setPriorSibling(index == 0 ? null : mChildren.get(index - 1));
-                            index == 0 ? null : mChildren.get(index - 1));
                 }
             }
         }
         return ret;
     }
 
+    /**
+     * 移动子任务到指定位置
+     * @param task 要移动的任务
+     * @param index 目标位置
+     * @return 移动成功与否
+     */
     public boolean moveChildTask(Task task, int index) {
-
         if (index < 0 || index >= mChildren.size()) {
-            Log.e(TAG, "move child task: invalid index");
+            Log.e(TAG, "移动子任务：无效索引");
             return false;
         }
 
         int pos = mChildren.indexOf(task);
         if (pos == -1) {
-            Log.e(TAG, "move child task: the task should in the list");
+            Log.e(TAG, "移动子任务：任务不在列表中");
             return false;
         }
 
-        if (pos == index)
+        if (pos == index) return true;
-            return true;
         return (removeChildTask(task) && addChildTask(task, index));
     }
 
+    // ------------------------
+    // 任务查找与获取方法
+    // ------------------------
+
+    /**
+     * 通过GID查找子任务
+     * @param gid 任务GID
+     * @return 找到的任务或null
+     */
     public Task findChildTaskByGid(String gid) {
         for (int i = 0; i < mChildren.size(); i++) {
-            Task t = mChildren.get(i);
+            if (mChildren.get(i).getGid().equals(gid)) {
-            if (t.getGid().equals(gid)) {
+                return mChildren.get(i);
-                return t;
             }
         }
         return null;
     }
 
+    /**
+     * 获取子任务在列表中的索引
+     * @param task 任务对象
+     * @return 索引位置
+     */
     public int getChildTaskIndex(Task task) {
         return mChildren.indexOf(task);
     }
 
+    /**
+     * 通过索引获取子任务
+     * @param index 索引位置
+     * @return 任务对象或null
+     */
     public Task getChildTaskByIndex(int index) {
         if (index < 0 || index >= mChildren.size()) {
-            Log.e(TAG, "getTaskByIndex: invalid index");
+            Log.e(TAG, "获取子任务：无效索引");
             return null;
         }
         return mChildren.get(index);
     }
 
+    /**
+     * 通过GID获取子任务（重载方法）
+     * @param gid 任务GID
+     * @return 任务对象或null
+     */
     public Task getChilTaskByGid(String gid) {
         for (Task task : mChildren) {
             if (task.getGid().equals(gid))
@@ -329,15 +340,18 @@ public class TaskList extends Node {
         return null;
     }
 
+    /**
+     * 获取所有子任务列表
+     * @return 子任务列表
+     */
     public ArrayList<Task> getChildTaskList() {
         return this.mChildren;
     }
 
-    public void setIndex(int index) {
+    // ------------------------
-        this.mIndex = index;
+    // Getters and Setters
-    }
+    // ------------------------
 
-    public int getIndex() {
+    public void setIndex(int index) { this.mIndex = index; }
-        return this.mIndex;
+    public int getIndex() { return this.mIndex; }
-    }
+}
-}