添加注释

src/Notes-master/app/src/main/java/net/micode/notes/gtask/data/MetaData.java

@@ -24,59 +24,95 @@ import net.micode.notes.tool.GTaskStringUtils;
 import org.json.JSONException;
 import org.json.JSONObject;
 
-
+/**
+ * MetaData 类用于管理与 Google Tasks (GTask) 相关的元数据，
+ * 继承自 Task 类，主要处理 GTask 同步时的元数据存储和解析。
+ */
 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");
+            Log.e(TAG, "failed to put related gid", e); // 记录异常日志
         }
+        // 将元数据 JSON 转为字符串存储到便签内容中
         setNotes(metaInfo.toString());
+        // 设置便签名称为固定值（元数据便签标识）
         setName(GTaskStringUtils.META_NOTE_NAME);
     }
 
+    /**
+     * 获取关联的 GTask ID
+     * @return 关联的 GTask ID，解析失败时返回 null
+     */
     public String getRelatedGid() {
         return mRelatedGid;
     }
 
+    /**
+     * 判断元数据是否值得保存（需包含有效内容）
+     * @return true 如果 notes 字段不为 null，否则 false
+     */
     @Override
     public boolean isWorthSaving() {
-        return getNotes() != null;
+        return getNotes() != null; // 依赖父类 Task 的 getNotes() 方法
     }
 
+    /**
+     * 从远程 JSON 数据中解析并设置内容（用于同步）
+     * @param js 包含远程数据的 JSON 对象
+     */
     @Override
     public void setContentByRemoteJSON(JSONObject js) {
-        super.setContentByRemoteJSON(js);
+        super.setContentByRemoteJSON(js); // 先调用父类解析逻辑
         if (getNotes() != null) {
             try {
+                // 解析 notes 字段为元数据 JSON 对象
                 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");
-                mRelatedGid = null;
+                Log.w(TAG, "failed to get related gid", e); // 记录解析异常
+                mRelatedGid = null; // 解析失败时置空
             }
         }
     }
 
+    /**
+     * 禁止调用本地 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");
     }
-
-}
+}