Merge branch 'main' of https://bdgit.educoder.net/ps249eph7/MiNotes

src/xiaomi/Notes-master/src/net/micode/notes/gtask/exception/ActionFailureException.java

@@ -15,14 +15,34 @@
  */
 
 package net.micode.notes.gtask.exception;
-
+/**
+ * @aPackage :      net.micode.notes.gtask.exception
+ * @aClassName:     ActionFailureException
+ * @Description:
+ * 该类是一个名为 ActionFailureException的公共类，该类继承自 RuntimeException 类
+ * RuntimeException 是Java中的一个异常类，它是所有运行时异常的父类。
+ * 当程序在运行过程中遇到无法处理的错误或异常情况时，会抛出 RuntimeException 类型的异常
+ * 作用：
+ * 通过继承的方式，ActionFailureException 类可以自定义自己的异常行为和处理方式
+ * 以便更精确地描述和处理这种特定类型的异常
+ * @aAuthor:        Li Qiushi
+ * @createdate:     12/24/2023 19:31 PM
+ */
 public class ActionFailureException extends RuntimeException {
     private static final long serialVersionUID = 4425249765923293627L;
-
+    /*
+     * serialVersionUID相当于java类的身份证。主要用于版本控制。
+     * serialVersionUID作用是序列化时保持版本的兼容性，即在版本升级时反序列化仍保持对象的唯一性。
+    */
     public ActionFailureException() {
         super();
     }
-
+    /*
+     * 在JAVA类中使用super来引用父类的成分，用this来引用当前对象.
+     * 如果一个类从另外一个类继承，我们new这个子类的实例对象的时候，这个子类对象里面会有一个父类对象。
+     * 怎么去引用里面的父类对象呢？使用super来引用
+     * 也就是说，此处super()以及super (paramString)可认为是Exception ()和Exception (paramString)
+     */
     public ActionFailureException(String paramString) {
         super(paramString);
     }

src/xiaomi/Notes-master/src/net/micode/notes/gtask/exception/NetworkFailureException.java

@@ -15,14 +15,30 @@
  */
 
 package net.micode.notes.gtask.exception;
-
+/**
+ * @aPackage :      net.micode.notes.gtask.exception
+ * @aClassName:     NetworkFailureException
+ * @Description:
+ * 该类继承自Java的内置异常类 Exception
+ * 在Java中，异常（Exception）是一种用于处理程序运行时可能出现的错误情况的对象
+ * 当程序在运行过程中遇到无法处理的错误或异常情况时，会抛出 RuntimeException 类型的异常
+ * 作用：
+ * 通过继承Exception类，可以自定义自己的异常类型，以便更好地描述和处理特定类型的错误
+ * @aAuthor:        Li Qiushi
+ * @createdate:     12/24/2023 19:31 PM
+ */
 public class NetworkFailureException extends Exception {
     private static final long serialVersionUID = 2107610287180234136L;
-
+    /*
+     * serialVersionUID相当于java类的身份证。主要用于版本控制。
+     * serialVersionUID作用是序列化时保持版本的兼容性，即在版本升级时反序列化仍保持对象的唯一性。
+     */
     public NetworkFailureException() {
         super();
     }
-
+    /*
+    super()含义与ActionFailureException类的相同
+    */
     public NetworkFailureException(String paramString) {
         super(paramString);
     }

src/xiaomi/Notes-master/src/net/micode/notes/gtask/remote/GTaskASyncTask.java

@@ -27,8 +27,19 @@ import android.os.AsyncTask;
 import net.micode.notes.R;
 import net.micode.notes.ui.NotesListActivity;
 import net.micode.notes.ui.NotesPreferenceActivity;
-
+/**
-
+ * @aPackage :      net.micode.notes.gtask.remote
+ * @aClassName:     GTaskASyncTask
+ * @Description:
+ * 异步操作类，实现GTask的异步操作过程
+ * 主要方法：
+ * showNotification(int tickerId, String content) 向用户提示当前同步的状态，是一个用于交互的方法
+ * doInBackground(Void... unused) 此方法在后台线程执行，完成任务的主要工作，通常需要较长的时间
+ * onProgressUpdate(String... progress)  可以使用进度条增加用户体验度。 此方法在主线程执行，用于显示任务执行的进度。
+ * onPostExecute(Integer result)  相当于Handler 处理UI的方式，在这里面可以使用在doInBackground 得到的结果处理操作UI
+ * @aAuthor:        Li Qiushi
+ * @createdate:     12/24/2023 19:31 PM
+ */
 public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
 
     private static int GTASK_SYNC_NOTIFICATION_ID = 5234235;
@@ -48,6 +59,9 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
     public GTaskASyncTask(Context context, OnCompleteListener listener) {
         mContext = context;
         mOnCompleteListener = listener;
+        /*
+        获取系统服务中的NotificationManager对象，并将其赋值给成员变量mNotifiManager。这个对象用于管理应用程序的通知
+         */
         mNotifiManager = (NotificationManager) mContext
                 .getSystemService(Context.NOTIFICATION_SERVICE);
         mTaskManager = GTaskManager.getInstance();
@@ -57,18 +71,19 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
         mTaskManager.cancelSync();
     }
 
-    public void publishProgess(String message) {
+    public void publishProgess(String message) {//发布进度单位，系统将会调用onProgressUpdate()方法更新这些值
         publishProgress(new String[] {
             message
         });
     }
 
-    private void showNotification(int tickerId, String content) {
+    /**
-        Notification notification = new Notification(R.drawable.notification, mContext
+     * 该函数用于向用户提示当前同步的状态，是一个用于交互的方法
-                .getString(tickerId), System.currentTimeMillis());
+     * 两个参数：一个整数类型的tickerId，表示通知的唯一标识符
-        notification.defaults = Notification.DEFAULT_LIGHTS;
+     * 和一个字符串类型的content，表示通知的内容，可以是任何文本信息，例如消息、警告或其他相关信息
-        notification.flags = Notification.FLAG_AUTO_CANCEL;
+     */
-        PendingIntent pendingIntent;
+    private void showNotification(int tickerId, String content)  {
+        PendingIntent pendingIntent;//一个描述了想要启动一个Activity、Broadcast或是Service的意图
         if (tickerId != R.string.ticker_success) {
             pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
                     NotesPreferenceActivity.class), 0);
@@ -77,16 +92,41 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
             pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
                     NotesListActivity.class), 0);
         }
-        notification.setLatestEventInfo(mContext, mContext.getString(R.string.app_name), content,
+        /*
-                pendingIntent);
+        如果同步不成功，那么从系统取得一个用于启动一个NotesPreferenceActivity的PendingIntent对象
+        如果同步成功，那么从系统取得一个用于启动一个NotesListActivity的PendingIntent对象
+        */
+
+        Notification.Builder builder = new Notification.Builder(mContext)
+                .setAutoCancel(true)
+                .setContentTitle(mContext.getString(R.string.app_name))
+                .setContentText(content)
+                .setContentIntent(pendingIntent)
+                .setWhen(System.currentTimeMillis())
+                .setOngoing(true);
+        Notification notification=builder.getNotification();
+        //通过NotificationManager对象的notify（）方法来执行一个notification的消息
         mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
     }
 
+    /**
+     *用于在后台线程中执行耗时操作具体来说，它的作用是在后台线程中同步数据
+     * 它是一个受保护的方法，返回类型为Integer。该方法接受一个可变参数unused，表示没有使用到的参数
+    */
     @Override
     protected Integer doInBackground(Void... unused) {
         publishProgess(mContext.getString(R.string.sync_progress_login, NotesPreferenceActivity
                 .getSyncAccountName(mContext)));
+        /*
+        publishProgess用于更新进度信息，NotesPreferenceActivity.getSyncAccountName(mContext)来生成进度信息
+        利用getString,把进程信息的内容传进sync_progress_login中
+
+        */
         return mTaskManager.sync(mContext, this);
+        /*
+        进行后台同步具体操作
+        sync方法接受两个参数：一个是上下文对象mContext，另一个是当前对象this
+        */
     }
 
     @Override
@@ -97,6 +137,15 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
         }
     }
 
+    /**
+     * 用于在执行完后台任务后更新UI,显示结果
+     * 根据不同的执行结果，代码会调用showNotification方法来显示相应的通知信息
+     * 显示的不同结果：
+     * 如果结果为GTaskManager.STATE_SUCCESS，则显示成功同步的通知
+     * 如果结果为GTaskManager.STATE_NETWORK_ERROR，则显示网络错误的通知
+     * 如果结果为GTaskManager.STATE_INTERNAL_ERROR，则显示内部错误的通知
+     * 如果结果为GTaskManager.STATE_SYNC_CANCELLED，则显示同步取消的通知
+     */
     @Override
     protected void onPostExecute(Integer result) {
         if (result == GTaskManager.STATE_SUCCESS) {
@@ -111,6 +160,9 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
             showNotification(R.string.ticker_cancel, mContext
                     .getString(R.string.error_sync_cancelled));
         }
+        /*
+         如果存在mOnCompleteListener对象，代码还会创建一个新的线程来执行mOnCompleteListener.onComplete()方法，以完成一次操作
+         */
         if (mOnCompleteListener != null) {
             new Thread(new Runnable() {
 

src/xiaomi/Notes-master/src/net/micode/notes/gtask/remote/GTaskClient.java

@@ -59,7 +59,15 @@ import java.util.List;
 import java.util.zip.GZIPInputStream;
 import java.util.zip.Inflater;
 import java.util.zip.InflaterInputStream;
-
+/**
+ * @aPackage :      net.micode.notes.gtask.remote
+ * @aClassName:     GTaskClient
+ * @Description:
+ * 主要功能：实现GTASK的登录操作，进行GTASK任务的创建，创建任务列表，从网络上获取任务和任务列表的内容
+ * 主要使用类或技术：accountManager JSONObject HttpParams authToken Gid
+ * @aAuthor:        Li Qiushi
+ * @createdate:     12/24/2023 19:31 PM
+ */
 
 public class GTaskClient {
     private static final String TAG = GTaskClient.class.getSimpleName();
@@ -102,6 +110,10 @@ public class GTaskClient {
         mUpdateArray = null;
     }
 
+    /* 用来获取的实例化对象
+     * 使用 getInstance()
+     * 返回mInstance这个实例化对象
+     */
     public static synchronized GTaskClient getInstance() {
         if (mInstance == null) {
             mInstance = new GTaskClient();
@@ -109,42 +121,50 @@ public class GTaskClient {
         return mInstance;
     }
 
+
+    /*用来实现登录操作的函数，传入的参数是一个Activity
+     * 设置登录操作限制时间，如果超时则需要重新登录
+     * 有两种登录方式，使用用户自己的URL登录或者使用谷歌官方的URL登录
+     * 返回true或者false，即最后是否登陆成功
+    */
     public boolean login(Activity activity) {
-        // we suppose that the cookie would expire after 5 minutes
+        //判断距离最后一次登录操作是否超过5分钟
-        // then we need to re-login
         final long interval = 1000 * 60 * 5;
         if (mLastLoginTime + interval < System.currentTimeMillis()) {
             mLoggedin = false;
         }
 
-        // need to re-login after account switch
+        // need to re-login after account switch  也就是重新登录
         if (mLoggedin
                 && !TextUtils.equals(getSyncAccount().name, NotesPreferenceActivity
                         .getSyncAccountName(activity))) {
             mLoggedin = false;
         }
 
+        //如果没超过时间，则不需要重新登录
         if (mLoggedin) {
             Log.d(TAG, "already logged in");
             return true;
         }
 
-        mLastLoginTime = System.currentTimeMillis();
+        mLastLoginTime = System.currentTimeMillis();//更新最后登录时间，改为系统当前的时间
-        String authToken = loginGoogleAccount(activity, false);
+        String authToken = loginGoogleAccount(activity, false);//判断是否登录到谷歌账户
         if (authToken == null) {
             Log.e(TAG, "login google account failed");
             return false;
         }
 
         // login with custom domain if necessary
+        //尝试使用用户自己的域名登录
+        //将用户账号名改为统一格式（小写）后判断是否为一个谷歌账号地址
         if (!(mAccount.name.toLowerCase().endsWith("gmail.com") || mAccount.name.toLowerCase()
                 .endsWith("googlemail.com"))) {
             StringBuilder url = new StringBuilder(GTASK_URL).append("a/");
             int index = mAccount.name.indexOf('@') + 1;
             String suffix = mAccount.name.substring(index);
             url.append(suffix + "/");
-            mGetUrl = url.toString() + "ig";
+            mGetUrl = url.toString() + "ig";//设置用户对应的getUrl
-            mPostUrl = url.toString() + "r/ig";
+            mPostUrl = url.toString() + "r/ig";//设置用户对应的postUrl
 
             if (tryToLoginGtask(activity, authToken)) {
                 mLoggedin = true;
@@ -152,6 +172,7 @@ public class GTaskClient {
         }
 
         // try to login with google official url
+        //如果用户账户无法登录，则使用谷歌官方的URI进行登录
         if (!mLoggedin) {
             mGetUrl = GTASK_GET_URL;
             mPostUrl = GTASK_POST_URL;
@@ -164,10 +185,15 @@ public class GTaskClient {
         return true;
     }
 
+    /*具体实现登录谷歌账户的方法
+     * 使用令牌机制
+     * 使用AccountManager来管理注册账号
+     * 返回值是账号的令牌
+     */
     private String loginGoogleAccount(Activity activity, boolean invalidateToken) {
-        String authToken;
+        String authToken;  //令牌，是登录操作保证安全性的一个方法
-        AccountManager accountManager = AccountManager.get(activity);
+        AccountManager accountManager = AccountManager.get(activity);//AccountManager这个类给用户提供了集中注册账号的接口
-        Account[] accounts = accountManager.getAccountsByType("com.google");
+        Account[] accounts = accountManager.getAccountsByType("com.google");//获取全部以com.google结尾的account
 
         if (accounts.length == 0) {
             Log.e(TAG, "there is no available google account");
@@ -176,6 +202,7 @@ public class GTaskClient {
 
         String accountName = NotesPreferenceActivity.getSyncAccountName(activity);
         Account account = null;
+        //遍历获得的accounts信息，寻找已经记录过的账户信息
         for (Account a : accounts) {
             if (a.name.equals(accountName)) {
                 account = a;
@@ -190,11 +217,13 @@ public class GTaskClient {
         }
 
         // get the token now
+        //获取选中账号的令牌
         AccountManagerFuture<Bundle> accountManagerFuture = accountManager.getAuthToken(account,
                 "goanna_mobile", null, activity, null, null);
         try {
             Bundle authTokenBundle = accountManagerFuture.getResult();
             authToken = authTokenBundle.getString(AccountManager.KEY_AUTHTOKEN);
+            //如果是invalidateToken，那么需要调用invalidateAuthToken(String, String)方法废除这个无效token
             if (invalidateToken) {
                 accountManager.invalidateAuthToken("com.google", authToken);
                 loginGoogleAccount(activity, false);
@@ -207,10 +236,13 @@ public class GTaskClient {
         return authToken;
     }
 
+
+    //尝试登陆Gtask，这只是一个预先判断令牌是否是有效以及是否能登上GTask的方法,而不是具体实现登陆的方法
     private boolean tryToLoginGtask(Activity activity, String authToken) {
         if (!loginGtask(authToken)) {
-            // maybe the auth token is out of date, now let's invalidate the
+            // maybe the auth token is out of authTokedate, now let's invalidate the
             // token and try again
+            //删除过一个无效的authToken，申请一个新的后再次尝试登陆
             authToken = loginGoogleAccount(activity, true);
             if (authToken == null) {
                 Log.e(TAG, "login google account failed");
@@ -225,25 +257,27 @@ public class GTaskClient {
         return true;
     }
 
+    //实现登录GTask的具体操作
     private boolean loginGtask(String authToken) {
         int timeoutConnection = 10000;
-        int timeoutSocket = 15000;
+        int timeoutSocket = 15000;  //socket是一种通信连接实现数据的交换的端口
-        HttpParams httpParameters = new BasicHttpParams();
+        HttpParams httpParameters = new BasicHttpParams(); //实例化一个新的HTTP参数类
-        HttpConnectionParams.setConnectionTimeout(httpParameters, timeoutConnection);
+        HttpConnectionParams.setConnectionTimeout(httpParameters, timeoutConnection);//设置连接超时时间
-        HttpConnectionParams.setSoTimeout(httpParameters, timeoutSocket);
+        HttpConnectionParams.setSoTimeout(httpParameters, timeoutSocket);//设置设置端口超时时间
         mHttpClient = new DefaultHttpClient(httpParameters);
-        BasicCookieStore localBasicCookieStore = new BasicCookieStore();
+        BasicCookieStore localBasicCookieStore = new BasicCookieStore(); //设置本地cookie
         mHttpClient.setCookieStore(localBasicCookieStore);
         HttpProtocolParams.setUseExpectContinue(mHttpClient.getParams(), false);
 
         // login gtask
         try {
-            String loginUrl = mGetUrl + "?auth=" + authToken;
+            String loginUrl = mGetUrl + "?auth=" + authToken;  //设置登录的url
-            HttpGet httpGet = new HttpGet(loginUrl);
+            HttpGet httpGet = new HttpGet(loginUrl);  //通过登录的uri实例化网页上资源的查找
             HttpResponse response = null;
             response = mHttpClient.execute(httpGet);
 
             // get the cookie now
+            //获取CookieStore里存放的cookie,看如果存有“GTL(不知道什么意思)”，则说明有验证成功的有效的cookie
             List<Cookie> cookies = mHttpClient.getCookieStore().getCookies();
             boolean hasAuthCookie = false;
             for (Cookie cookie : cookies) {
@@ -256,6 +290,7 @@ public class GTaskClient {
             }
 
             // get the client version
+            //获取client的内容，具体操作是在返回的Content中截取从_setup(开始到)}</script>中间的字符串内容，也就是gtask_url的内容
             String resString = getResponseContent(response.getEntity());
             String jsBegin = "_setup(";
             String jsEnd = ")}</script>";
@@ -280,10 +315,24 @@ public class GTaskClient {
         return true;
     }
 
+    /*实例化创建一个用于向网络传输数据的对象
+     * 使用HttpPost类
+     * 返回一个httpPost实例化对象，但里面还没有内容
+     */
     private int getActionId() {
         return mActionId++;
     }
 
+    /*通过URL获取响应后返回的数据，也就是网络上的数据和资源
+     * 使用getContentEncoding()获取网络上的资源和数据
+     * 返回值就是获取到的资源
+     */
+
+
+     /*实例化创建一个用于向网络传输数据的对象
+     * 使用HttpPost类
+     * 返回一个httpPost实例化对象，但里面还没有内容
+     */
     private HttpPost createHttpPost() {
         HttpPost httpPost = new HttpPost(mPostUrl);
         httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
@@ -291,6 +340,10 @@ public class GTaskClient {
         return httpPost;
     }
 
+    /*通过URL获取响应后返回的数据，也就是网络上的数据和资源
+     * 使用getContentEncoding()获取网络上的资源和数据
+     * 返回值就是获取到的资源
+     */
     private String getResponseContent(HttpEntity entity) throws IOException {
         String contentEncoding = null;
         if (entity.getContentEncoding() != null) {
@@ -323,43 +376,57 @@ public class GTaskClient {
         }
     }
 
-    private JSONObject postRequest(JSONObject js) throws NetworkFailureException {
+     /*通过JSON发送请求
-        if (!mLoggedin) {
+   * 请求的具体内容在json的实例化对象js中然后传入
-            Log.e(TAG, "please login first");
+   * 利用UrlEncodedFormEntity entity和httpPost.setEntity(entity)方法把js中的内容放置到httpPost中
-            throw new ActionFailureException("not logged in");
+   * 执行请求后使用getResponseContent方法得到返回的数据和资源
-        }
+   * 将资源再次放入json后返回
-
+   */
-        HttpPost httpPost = createHttpPost();
+     private JSONObject postRequest(JSONObject js) throws NetworkFailureException {
-        try {
+         if (!mLoggedin) {//未登录
-            LinkedList<BasicNameValuePair> list = new LinkedList<BasicNameValuePair>();
+             Log.e(TAG, "please login first");
-            list.add(new BasicNameValuePair("r", js.toString()));
+             throw new ActionFailureException("not logged in");
-            UrlEncodedFormEntity entity = new UrlEncodedFormEntity(list, "UTF-8");
+         }
-            httpPost.setEntity(entity);
+
-
+         //实例化一个httpPost的对象用来向服务器传输数据，在这里就是发送请求，而请求的内容在js里
-            // execute the post
+         HttpPost httpPost = createHttpPost();
-            HttpResponse response = mHttpClient.execute(httpPost);
+         try {
-            String jsString = getResponseContent(response.getEntity());
+             LinkedList<BasicNameValuePair> list = new LinkedList<BasicNameValuePair>();
-            return new JSONObject(jsString);
+             list.add(new BasicNameValuePair("r", js.toString()));
-
+             UrlEncodedFormEntity entity = new UrlEncodedFormEntity(list, "UTF-8"); //UrlEncodedFormEntity()的形式比较单一，是普通的键值对
-        } catch (ClientProtocolException e) {
+             httpPost.setEntity(entity);
-            Log.e(TAG, e.toString());
+
-            e.printStackTrace();
+             // execute the post
-            throw new NetworkFailureException("postRequest failed");
+             //执行这个请求
-        } catch (IOException e) {
+             HttpResponse response = mHttpClient.execute(httpPost);
-            Log.e(TAG, e.toString());
+             String jsString = getResponseContent(response.getEntity());
-            e.printStackTrace();
+             return new JSONObject(jsString);
-            throw new NetworkFailureException("postRequest failed");
+
-        } catch (JSONException e) {
+         } catch (ClientProtocolException e) {
-            Log.e(TAG, e.toString());
+             Log.e(TAG, e.toString());
-            e.printStackTrace();
+             e.printStackTrace();
-            throw new ActionFailureException("unable to convert response content to jsonobject");
+             throw new NetworkFailureException("postRequest failed");
-        } catch (Exception e) {
+         } catch (IOException e) {
-            Log.e(TAG, e.toString());
+             Log.e(TAG, e.toString());
-            e.printStackTrace();
+             e.printStackTrace();
-            throw new ActionFailureException("error occurs when posting request");
+             throw new NetworkFailureException("postRequest failed");
-        }
+         } catch (JSONException e) {
-    }
+             Log.e(TAG, e.toString());
-
+             e.printStackTrace();
+             throw new ActionFailureException("unable to convert response content to jsonobject");
+         } catch (Exception e) {
+             Log.e(TAG, e.toString());
+             e.printStackTrace();
+             throw new ActionFailureException("error occurs when posting request");
+         }
+     }
+
+    /*创建单个任务
+     * 传入参数是一个.gtask.data.Task包里Task类的对象
+     * 利用json获取Task里的内容,并且创建相应的jsPost
+     * 利用postRequest得到任务的返回信息
+     * 使用task.setGid设置task的new_ID
+     */
     public void createTask(Task task) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -386,6 +453,9 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 创建一个任务列表，与createTask几乎一样，区别就是最后设置的是tasklist的gid
+     */
     public void createTaskList(TaskList tasklist) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -412,6 +482,11 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 同步更新操作
+     * 使用JSONObject进行数据存储，使用jsPost.put，Put的信息包括UpdateArray和ClientVersion
+     * 使用postRequest发送这个jspost,进行处理
+     */
     public void commitUpdate() throws NetworkFailureException {
         if (mUpdateArray != null) {
             try {
@@ -433,6 +508,10 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 添加更新的事项
+     * 调用commitUpdate()实现
+     */
     public void addUpdateNode(Node node) throws NetworkFailureException {
         if (node != null) {
             // too many update items may result in an error
@@ -447,6 +526,12 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 移动task,比如讲task移动到不同的task列表中去
+     * 通过getGid获取task所属列表的gid
+     * 通过JSONObject.put(String name, Object value)函数设置移动后的task的相关属性值，从而达到移动的目的
+     * 最后还是通过postRequest进行更新后的发送
+     */
     public void moveTask(Task task, TaskList preParent, TaskList curParent)
             throws NetworkFailureException {
         commitUpdate();
@@ -463,15 +548,17 @@ public class GTaskClient {
             if (preParent == curParent && task.getPriorSibling() != null) {
                 // put prioring_sibing_id only if moving within the tasklist and
                 // it is not the first one
+                //设置优先级ID，只有当移动是发生在文件中
                 action.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, task.getPriorSibling());
             }
-            action.put(GTaskStringUtils.GTASK_JSON_SOURCE_LIST, preParent.getGid());
+            action.put(GTaskStringUtils.GTASK_JSON_SOURCE_LIST, preParent.getGid());  //设置移动前所属列表
-            action.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT, curParent.getGid());
+            action.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT, curParent.getGid());  //设置当前所属列表
             if (preParent != curParent) {
                 // put the dest_list only if moving between tasklists
                 action.put(GTaskStringUtils.GTASK_JSON_DEST_LIST, curParent.getGid());
             }
             actionList.put(action);
+            //最后将ACTION_LIST加入到jsPost中
             jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
 
             // client_version
@@ -486,6 +573,11 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 删除操作节点
+     * 还是利用JSON
+     * 删除过后使用postRequest发送删除后的结果
+     */
     public void deleteNode(Node node) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -494,7 +586,7 @@ public class GTaskClient {
 
             // action_list
             node.setDeleted(true);
-            actionList.put(node.getUpdateAction(getActionId()));
+            actionList.put(node.getUpdateAction(getActionId()));//这里会获取到删除操作的ID，加入到actionLiast中
             jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
 
             // client_version
@@ -509,6 +601,11 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 获取任务列表
+     * 首先通过GetURI使用getResponseContent从网上获取数据
+     * 然后筛选出"_setup("到)}</script>的部分，并且从中获取GTASK_JSON_LISTS的内容返回
+     */
     public JSONArray getTaskLists() throws NetworkFailureException {
         if (!mLoggedin) {
             Log.e(TAG, "please login first");
@@ -521,6 +618,7 @@ public class GTaskClient {
             response = mHttpClient.execute(httpGet);
 
             // get the task list
+            //筛选工作，把筛选出的字符串放入jsString
             String resString = getResponseContent(response.getEntity());
             String jsBegin = "_setup(";
             String jsEnd = ")}</script>";
@@ -531,6 +629,8 @@ public class GTaskClient {
                 jsString = resString.substring(begin + jsBegin.length(), end);
             }
             JSONObject js = new JSONObject(jsString);
+
+            //获取GTASK_JSON_LISTS
             return js.getJSONObject("t").getJSONArray(GTaskStringUtils.GTASK_JSON_LISTS);
         } catch (ClientProtocolException e) {
             Log.e(TAG, e.toString());
@@ -547,6 +647,9 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 通过传入的TASKList的gid,从网络上获取相应属于这个任务列表的任务
+     */
     public JSONArray getTaskList(String listGid) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -558,7 +661,7 @@ public class GTaskClient {
             action.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                     GTaskStringUtils.GTASK_JSON_ACTION_TYPE_GETALL);
             action.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, getActionId());
-            action.put(GTaskStringUtils.GTASK_JSON_LIST_ID, listGid);
+            action.put(GTaskStringUtils.GTASK_JSON_LIST_ID, listGid); //这里设置为传入的listGid
             action.put(GTaskStringUtils.GTASK_JSON_GET_DELETED, false);
             actionList.put(action);
             jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
@@ -579,6 +682,7 @@ public class GTaskClient {
         return mAccount;
     }
 
+    //重置更新的内容
     public void resetUpdateArray() {
         mUpdateArray = null;
     }

src/xiaomi/Notes-master/src/net/micode/notes/gtask/remote/GTaskManager.java

@@ -46,8 +46,14 @@ import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Iterator;
 import java.util.Map;
-
+/**
-
+ * @aPackage :      net.micode.notes.gtask.remote
+ * @aClassName:     GTaskManager
+ * @Description:
+ * GTask管理者，提供同步本地和远端的任务，初始化任务列表，同步内容、文件夹，添加、更新本地和远端结点，刷新本地同步任务D等功能
+ * @aAuthor:        Li Qiushi
+ * @createdate:     12/24/2023 19:31 PM
+ */
 public class GTaskManager {
     private static final String TAG = GTaskManager.class.getSimpleName();
 
@@ -73,49 +79,67 @@ public class GTaskManager {
 
     private boolean mCancelled;
 
-    private HashMap<String, TaskList> mGTaskListHashMap;
+    private HashMap<String, TaskList> mGTaskListHashMap = new HashMap<>();
 
-    private HashMap<String, Node> mGTaskHashMap;
+    private HashMap<String, Node> mGTaskHashMap = new HashMap<>();
 
-    private HashMap<String, MetaData> mMetaHashMap;
+    private HashMap<String, MetaData> mMetaHashMap = new HashMap<>();
 
-    private TaskList mMetaList;
+    private TaskList mMetaList = null;
 
-    private HashSet<Long> mLocalDeleteIdMap;
+    private HashSet<Long> mLocalDeleteIdMap = new HashSet<>();
 
-    private HashMap<String, Long> mGidToNid;
+    private HashMap<String, Long> mGidToNid = new HashMap<>();
 
-    private HashMap<Long, String> mNidToGid;
+    private HashMap<Long, String> mNidToGid = new HashMap<>();
 
     private GTaskManager() {
         mSyncing = false;
         mCancelled = false;
-        mGTaskListHashMap = new HashMap<String, TaskList>();
-        mGTaskHashMap = new HashMap<String, Node>();
-        mMetaHashMap = new HashMap<String, MetaData>();
-        mMetaList = null;
-        mLocalDeleteIdMap = new HashSet<Long>();
-        mGidToNid = new HashMap<String, Long>();
-        mNidToGid = new HashMap<Long, String>();
     }
 
-    public static synchronized GTaskManager getInstance() {
+    /**
+     * 包含关键字synchronized，语言级同步，指明该函数可能运行在多线程的环境下。
+     * 功能：类初始化函数
+     * @return GtaskManger
+     */
+    public static synchronized GTaskManager getInstance() {//可能运行在多线程环境下，使用语言级同步--synchronized
         if (mInstance == null) {
             mInstance = new GTaskManager();
         }
         return mInstance;
     }
 
+    /**
+     * 包含关键字synchronized，语言级同步，指明该函数可能运行在多线程的环境下。
+     * @param activity
+     */
     public synchronized void setActivityContext(Activity activity) {
-        // used for getting authtoken
+        // used for getting auth token
         mActivity = activity;
     }
 
-    public int sync(Context context, GTaskASyncTask asyncTask) {
+    /**
+     * 核心函数
+     * 功能：实现了本地同步操作和远端同步操作，用于同步Google任务列表
+     * @param context-----获取上下文
+     * @param asyncTask-------用于同步的异步操作类
+     * @return int
+     */
+    public int sync(Context context, GTaskASyncTask asyncTask) {           //核心函数
+       /*检查是否已经在进行同步操作(mSyncing为true)
+         如果是，则记录一条调试日志并返回STATE_SYNC_IN_PROGRESS状态，表示同步正在进行中
+       */
         if (mSyncing) {
             Log.d(TAG, "Sync is in progress");
             return STATE_SYNC_IN_PROGRESS;
         }
+
+        /*
+          将传入的context赋值给成员变量mContext，并获取其内容解析器(ContentResolver)赋值给成员变量mContentResolver
+          将mSyncing设置为true，表示开始同步操作，将mCancelled设置为false，表示同步未被取消
+          清空所有与任务相关的数据结构（如任务列表、任务映射、元数据映射等）
+         */
         mContext = context;
         mContentResolver = mContext.getContentResolver();
         mSyncing = true;
@@ -127,9 +151,16 @@ public class GTaskManager {
         mGidToNid.clear();
         mNidToGid.clear();
 
+        /**
+         *创建一个GTaskClient实例
+         * 重置更新数组
+         * 登录Google任务。如果登录失败，抛出NetworkFailureException异常
+         * 从Google获取任务列表，并将其转换为本地任务列表
+         * 执行内容同步工作
+         */
         try {
-            GTaskClient client = GTaskClient.getInstance();
+            GTaskClient client = GTaskClient.getInstance();//getInstance即为创建一个实例,client--客户机
-            client.resetUpdateArray();
+            client.resetUpdateArray();//JSONArray类型，reset即置为NULL
 
             // login google task
             if (!mCancelled) {
@@ -140,15 +171,15 @@ public class GTaskManager {
 
             // get the task list from google
             asyncTask.publishProgess(mContext.getString(R.string.sync_progress_init_list));
-            initGTaskList();
+            initGTaskList();  //获取Google上的JSONtasklist转为本地TaskList
 
             // do content sync work
             asyncTask.publishProgess(mContext.getString(R.string.sync_progress_syncing));
             syncContent();
-        } catch (NetworkFailureException e) {
+        } catch (NetworkFailureException e) {  //分为两种异常，此类异常为网络异常
-            Log.e(TAG, e.toString());
+            Log.e(TAG, e.toString());    //创建日志文件（调试信息），error
             return STATE_NETWORK_ERROR;
-        } catch (ActionFailureException e) {
+        } catch (ActionFailureException e) {  //此类异常为操作异常
             Log.e(TAG, e.toString());
             return STATE_INTERNAL_ERROR;
         } catch (Exception e) {
@@ -164,36 +195,53 @@ public class GTaskManager {
             mNidToGid.clear();
             mSyncing = false;
         }
-
+        //根据mCancelled的值返回相应的状态(STATE_SYNC_CANCELLED表示同步已取消，STATE_SUCCESS表示同步成功)
         return mCancelled ? STATE_SYNC_CANCELLED : STATE_SUCCESS;
     }
 
+    /**
+     *功能：初始化GtaskList，获取Google上的JSONtasklist转为本地TaskList。
+     *获得的数据存储在mMetaList，mGTaskListHashMap，mGTaskHashMap
+     *@exception NetworkFailureException
+     *@return void
+     */
     private void initGTaskList() throws NetworkFailureException {
         if (mCancelled)
             return;
+        //getInstance即为创建一个实例，client应指远端客户机，用于与远程服务器进行通信
         GTaskClient client = GTaskClient.getInstance();
         try {
-            JSONArray jsTaskLists = client.getTaskLists();
+            /*Json对象是Name Value对(即子元素)的无序集合，相当于一个Map对象。JsonObject类是bantouyan-json库对Json对象的抽象，提供操纵Json对象的各种方法。
+              其格式为{"key1":value1,"key2",value2....};key 必须是字符串。
+              因为ajax请求不刷新页面，但配合js可以实现局部刷新，因此json常常被用来作为异步请求的返回对象使用
+            */
+            JSONArray jsTaskLists = client.getTaskLists(); //通过调用client.getTaskLists()方法获取远程服务器上的任务列表，并将其存储在JSONArray对象jsTaskLists中
 
             // init meta list first
             mMetaList = null;
+            /*
+            遍历jsTaskLists中的每个元素，将其转换为JSONObject对象，并从中提取任务列表的ID和名称
+             */
             for (int i = 0; i < jsTaskLists.length(); i++) {
-                JSONObject object = jsTaskLists.getJSONObject(i);
+                JSONObject object = jsTaskLists.getJSONObject(i);  //JSONObject与JSONArray一个为对象，一个为数组。此处取出单个JASONObject
                 String gid = object.getString(GTaskStringUtils.GTASK_JSON_ID);
                 String name = object.getString(GTaskStringUtils.GTASK_JSON_NAME);
 
-                if (name
+                /*
-                        .equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_META)) {
+                如果任务列表的名称以特定的前缀开头且不等于元数据文件夹的前缀，则创建一个新的TaskList对象，并将其添加到本地的任务列表映射中
-                    mMetaList = new TaskList();
+                同时，加载该任务列表的元数据，并将其添加到元数据列表映射中
-                    mMetaList.setContentByRemoteJSON(object);
+                 */
+                if (name.equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_META)) {
+                    mMetaList = new TaskList();                    //MetaList意为元表,Tasklist类型，此处为初始化
+                    mMetaList.setContentByRemoteJSON(object);      //将JSON中部分数据复制到自己定义的对象中相对应的数据：name->mname...
 
                     // load meta data
                     JSONArray jsMetas = client.getTaskList(gid);
                     for (int j = 0; j < jsMetas.length(); j++) {
                         object = (JSONObject) jsMetas.getJSONObject(j);
-                        MetaData metaData = new MetaData();
+                        MetaData metaData = new MetaData();         //继承自Node
                         metaData.setContentByRemoteJSON(object);
-                        if (metaData.isWorthSaving()) {
+                        if (metaData.isWorthSaving()) {             //if not worth to save，metadata将不加入mMetaList
                             mMetaList.addChildTask(metaData);
                             if (metaData.getGid() != null) {
                                 mMetaHashMap.put(metaData.getRelatedGid(), metaData);
@@ -203,7 +251,10 @@ public class GTaskManager {
                 }
             }
 
-            // create meta list if not existed
+            /*
+            如果本地没有元数据列表，则创建一个新的元数据列表，并将其设置为默认名称
+            然后，使用GTaskClient.getInstance().createTaskList(mMetaList)方法将元数据列表上传到远程服务器
+             */
             if (mMetaList == null) {
                 mMetaList = new TaskList();
                 mMetaList.setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX
@@ -211,16 +262,22 @@ public class GTaskManager {
                 GTaskClient.getInstance().createTaskList(mMetaList);
             }
 
-            // init task list
+            /*
+            最后，再次遍历jsTaskLists中的每个元素，将其转换为JSONObject对象，并从中提取任务列表的ID和名称
+             */
             for (int i = 0; i < jsTaskLists.length(); i++) {
                 JSONObject object = jsTaskLists.getJSONObject(i);
-                String gid = object.getString(GTaskStringUtils.GTASK_JSON_ID);
+                String gid = object.getString(GTaskStringUtils.GTASK_JSON_ID);  //通过getString函数传入本地某个标志数据的名称，获取其在远端的名称。
                 String name = object.getString(GTaskStringUtils.GTASK_JSON_NAME);
 
+                /*
+                如果任务列表的名称以特定的前缀开头且不等于元数据文件夹的前缀，则创建一个新的TaskList对象，并将其添加到本地的任务列表映射中
+                同时，加载该任务列表的任务，并将其添加到任务列表映射中
+                 */
                 if (name.startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX)
                         && !name.equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX
-                                + GTaskStringUtils.FOLDER_META)) {
+                        + GTaskStringUtils.FOLDER_META)) {
-                    TaskList tasklist = new TaskList();
+                    TaskList tasklist = new TaskList();     //继承自Node
                     tasklist.setContentByRemoteJSON(object);
                     mGTaskListHashMap.put(gid, tasklist);
                     mGTaskHashMap.put(gid, tasklist);
@@ -240,26 +297,40 @@ public class GTaskManager {
                     }
                 }
             }
+
         } catch (JSONException e) {
             Log.e(TAG, e.toString());
             e.printStackTrace();
             throw new ActionFailureException("initGTaskList: handing JSONObject failed");
+            /*
+            如果在处理过程中发生任何JSONException异常，将记录错误日志并抛出一个ActionFailureException异常
+             */
         }
     }
 
-    private void syncContent() throws NetworkFailureException {
+    /**
+     * 功能：本地内容同步操作
+     * @throws NetworkFailureException
+     * @return 无返回值
+     */
+    private void syncContent() throws NetworkFailureException {    //本地内容同步操作
         int syncType;
-        Cursor c = null;
+        Cursor c = null;    //数据库指针
-        String gid;
+        String gid;         //GoogleID
-        Node node;
+        Node node;          //Node包含Sync_Action的不同类型
 
-        mLocalDeleteIdMap.clear();
+        mLocalDeleteIdMap.clear();   //HashSet<Long>类型
 
         if (mCancelled) {
             return;
         }
 
-        // for local deleted note
+        /*
+        查询本地已删除的笔记（即类型不是系统类型且父ID是垃圾文件夹的笔记），并将查询结果存储在游标c中
+        遍历游标，获取每个笔记的Google ID（gid）和对应的节点（node）
+        如果节点不为空，则从mGTaskHashMap中移除该节点，并调用doContentSync()方法进行同步操作
+        同时，将该笔记的ID添加到mLocalDeleteIdMap中
+         */
         try {
             c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE,
                     "(type<>? AND parent_id=?)", new String[] {
@@ -286,10 +357,15 @@ public class GTaskManager {
             }
         }
 
-        // sync folder first
+        //同步文件夹
         syncFolder();
 
-        // for note existing in database
+        /*
+        查询数据库中存在的笔记（即类型是系统类型且父ID不是垃圾文件夹的笔记），并将查询结果存储在游标c中
+        遍历游标，获取每个笔记的Google ID（gid）和对应的节点（node）
+        如果节点不为空，则从mGTaskHashMap中移除该节点，并通过hashmap建立联系
+        然后根据节点的同步操作类型（syncType），调用doContentSync()方法进行同步操作
+         */
         try {
             c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE,
                     "(type=? AND parent_id<>?)", new String[] {
@@ -301,8 +377,8 @@ public class GTaskManager {
                     node = mGTaskHashMap.get(gid);
                     if (node != null) {
                         mGTaskHashMap.remove(gid);
-                        mGidToNid.put(gid, c.getLong(SqlNote.ID_COLUMN));
+                        mGidToNid.put(gid, c.getLong(SqlNote.ID_COLUMN));   //通过hashmap建立联系
-                        mNidToGid.put(c.getLong(SqlNote.ID_COLUMN), gid);
+                        mNidToGid.put(c.getLong(SqlNote.ID_COLUMN), gid);   //通过hashmap建立联系
                         syncType = node.getSyncAction(c);
                     } else {
                         if (c.getString(SqlNote.GTASK_ID_COLUMN).trim().length() == 0) {
@@ -327,23 +403,25 @@ public class GTaskManager {
         }
 
         // go through remaining items
-        Iterator<Map.Entry<String, Node>> iter = mGTaskHashMap.entrySet().iterator();
+        Iterator<Map.Entry<String, Node>> iter = mGTaskHashMap.entrySet().iterator();   //Iterator迭代器
         while (iter.hasNext()) {
             Map.Entry<String, Node> entry = iter.next();
             node = entry.getValue();
             doContentSync(Node.SYNC_ACTION_ADD_LOCAL, node, null);
         }
 
-        // mCancelled can be set by another thread, so we neet to check one by
+        /*如果mCancelled为假，首先调用DataUtils.batchDeleteNotes()方法批量删除本地已删除的笔记
-        // one
+        若删除失败，则抛出ActionFailureException异常
-        // clear local delete table
+         */
         if (!mCancelled) {
             if (!DataUtils.batchDeleteNotes(mContentResolver, mLocalDeleteIdMap)) {
                 throw new ActionFailureException("failed to batch-delete local deleted notes");
             }
         }
 
-        // refresh local sync id
+        /*
+        用于提交更新并且刷新本地同步ID
+         */
         if (!mCancelled) {
             GTaskClient.getInstance().commitUpdate();
             refreshLocalSyncId();
@@ -351,6 +429,14 @@ public class GTaskManager {
 
     }
 
+    /**
+     * 功能：
+     * 同步文件夹
+     * 先查询根文件夹、电话记录文件夹和本地存在的文件夹，然后根据查询结果执行相应的同步操作
+     * 最后，会遍历远程添加的文件夹，并将它们添加到本地
+     * 在整个过程中，如果遇到网络故障，会抛出NetworkFailureException异常
+     * @throws NetworkFailureException
+     */
     private void syncFolder() throws NetworkFailureException {
         Cursor c = null;
         String gid;
@@ -394,7 +480,7 @@ public class GTaskManager {
         try {
             c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(_id=?)",
                     new String[] {
-                        String.valueOf(Notes.ID_CALL_RECORD_FOLDER)
+                            String.valueOf(Notes.ID_CALL_RECORD_FOLDER)
                     }, null);
             if (c != null) {
                 if (c.moveToNext()) {
@@ -476,6 +562,14 @@ public class GTaskManager {
             GTaskClient.getInstance().commitUpdate();
     }
 
+    /**
+     * 功能：
+     * 根据传入的同步类型（syncType）对节点（Node）进行相应的操作
+     * @param syncType
+     * @param node
+     * @param c
+     * @throws NetworkFailureException
+     */
     private void doContentSync(int syncType, Node node, Cursor c) throws NetworkFailureException {
         if (mCancelled) {
             return;
@@ -522,6 +616,14 @@ public class GTaskManager {
         }
     }
 
+    /**
+     * 功能：将一个本地节点（Node）添加到数据库中
+     * 首先检查是否已经取消操作，如果是，则直接返回
+     * 否则，根据节点的类型（TaskList或其他类型），创建一个新的SqlNote对象，并设置其内容和父ID
+     * 接下来，将新创建的SqlNote对象提交到数据库中，并更新gid-nid映射以及元数据。
+     * @param node
+     * @throws NetworkFailureException
+     */
     private void addLocalNode(Node node) throws NetworkFailureException {
         if (mCancelled) {
             return;
@@ -596,6 +698,14 @@ public class GTaskManager {
         updateRemoteMeta(node.getGid(), sqlNote);
     }
 
+    /**
+     * 功能：update本地node
+     * @param node
+     * ----同步操作的基础数据类型
+     * @param c
+     * ----Cursor
+     * @throws NetworkFailureException
+     */
     private void updateLocalNode(Node node, Cursor c) throws NetworkFailureException {
         if (mCancelled) {
             return;
@@ -619,12 +729,21 @@ public class GTaskManager {
         updateRemoteMeta(node.getGid(), sqlNote);
     }
 
+    /**
+     * 功能：远程增加Node
+     * 需要updateRemoteMeta
+     * @param node
+     * ----同步操作的基础数据类型
+     * @param c
+     * --Cursor
+     * @throws NetworkFailureException
+     */
     private void addRemoteNode(Node node, Cursor c) throws NetworkFailureException {
         if (mCancelled) {
             return;
         }
 
-        SqlNote sqlNote = new SqlNote(mContext, c);
+        SqlNote sqlNote = new SqlNote(mContext, c); //从本地mContext中获取内容
         Node n;
 
         // update remotely
@@ -634,11 +753,12 @@ public class GTaskManager {
 
             String parentGid = mNidToGid.get(sqlNote.getParentId());
             if (parentGid == null) {
-                Log.e(TAG, "cannot find task's parent tasklist");
+                Log.e(TAG, "cannot find task's parent tasklist"); //调试信息
                 throw new ActionFailureException("cannot add remote task");
             }
-            mGTaskListHashMap.get(parentGid).addChildTask(task);
+            mGTaskListHashMap.get(parentGid).addChildTask(task);   //在本地生成的GTaskList中增加子结点
 
+            //登录远程服务器，创建Task
             GTaskClient.getInstance().createTask(task);
             n = (Node) task;
 
@@ -656,6 +776,7 @@ public class GTaskManager {
             else
                 folderName += sqlNote.getSnippet();
 
+            //iterator迭代器，通过统一的接口迭代所有的map元素
             Iterator<Map.Entry<String, TaskList>> iter = mGTaskListHashMap.entrySet().iterator();
             while (iter.hasNext()) {
                 Map.Entry<String, TaskList> entry = iter.next();
@@ -687,11 +808,19 @@ public class GTaskManager {
         sqlNote.resetLocalModified();
         sqlNote.commit(true);
 
-        // gid-id mapping
+        // gid-id mapping                                             //创建id间的映射
         mGidToNid.put(n.getGid(), sqlNote.getId());
         mNidToGid.put(sqlNote.getId(), n.getGid());
     }
 
+    /**
+     * 功能：更新远端的Node，包含meta更新(updateRemoteMeta)
+     * @param node
+     * ----同步操作的基础数据类型
+     * @param c
+     *  --Cursor
+     * @throws NetworkFailureException
+     */
     private void updateRemoteNode(Node node, Cursor c) throws NetworkFailureException {
         if (mCancelled) {
             return;
@@ -701,7 +830,7 @@ public class GTaskManager {
 
         // update remotely
         node.setContentByLocalJSON(sqlNote.getContent());
-        GTaskClient.getInstance().addUpdateNode(node);
+        GTaskClient.getInstance().addUpdateNode(node);  //GTaskClient用途为从本地登陆远端服务器
 
         // update meta
         updateRemoteMeta(node.getGid(), sqlNote);
@@ -710,14 +839,17 @@ public class GTaskManager {
         if (sqlNote.isNoteType()) {
             Task task = (Task) node;
             TaskList preParentList = task.getParent();
+            //preParentList为通过node获取的父节点列表
 
             String curParentGid = mNidToGid.get(sqlNote.getParentId());
+            //curParentGid为通过光标在数据库中找到sqlNote的mParentId，再通过mNidToGid由long类型转为String类型的Gid
+
             if (curParentGid == null) {
                 Log.e(TAG, "cannot find task's parent tasklist");
                 throw new ActionFailureException("cannot update remote task");
             }
             TaskList curParentList = mGTaskListHashMap.get(curParentGid);
-
+            //通过HashMap找到对应Gid的TaskList
             if (preParentList != curParentList) {
                 preParentList.removeChildTask(task);
                 curParentList.addChildTask(task);
@@ -725,11 +857,19 @@ public class GTaskManager {
             }
         }
 
-        // clear local modified flag
         sqlNote.resetLocalModified();
+        //commit到本地数据库
         sqlNote.commit(true);
     }
 
+    /**
+     * 功能：升级远程meta。  meta---元数据----计算机文件系统管理数据---管理数据的数据。
+     * @param gid
+     * ---GoogleID为String类型
+     * @param sqlNote
+     * ---同步前的数据库操作，故使用类SqlNote
+     * @throws NetworkFailureException
+     */
     private void updateRemoteMeta(String gid, SqlNote sqlNote) throws NetworkFailureException {
         if (sqlNote != null && sqlNote.isNoteType()) {
             MetaData metaData = mMetaHashMap.get(gid);
@@ -746,12 +886,17 @@ public class GTaskManager {
         }
     }
 
+    /**
+     * 功能：刷新本地，给sync的ID对应上最后更改过的对象
+     * @return void
+     * @throws NetworkFailureException
+     */
     private void refreshLocalSyncId() throws NetworkFailureException {
         if (mCancelled) {
             return;
         }
 
-        // get the latest gtask list
+        //获取最近的（最晚的）gtask list
         mGTaskHashMap.clear();
         mGTaskListHashMap.clear();
         mMetaHashMap.clear();
@@ -762,16 +907,16 @@ public class GTaskManager {
             c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE,
                     "(type<>? AND parent_id<>?)", new String[] {
                             String.valueOf(Notes.TYPE_SYSTEM), String.valueOf(Notes.ID_TRASH_FOLER)
-                    }, NoteColumns.TYPE + " DESC");
+                    }, NoteColumns.TYPE + " DESC");  //query语句：五个参数，NoteColumns.TYPE + " DESC"-----为按类型递减顺序返回查询结果。new String[] {String.valueOf(Notes.TYPE_SYSTEM), String.valueOf(Notes.ID_TRASH_FOLER)}------为选择参数。"(type<>? AND parent_id<>?)"-------指明返回行过滤器。SqlNote.PROJECTION_NOTE--------应返回的数据列的名字。Notes.CONTENT_NOTE_URI--------contentProvider包含所有数据集所对应的uri
             if (c != null) {
                 while (c.moveToNext()) {
                     String gid = c.getString(SqlNote.GTASK_ID_COLUMN);
                     Node node = mGTaskHashMap.get(gid);
                     if (node != null) {
                         mGTaskHashMap.remove(gid);
-                        ContentValues values = new ContentValues();
+                        ContentValues values = new ContentValues(); //在ContentValues中创建键值对。准备通过contentResolver写入数据
                         values.put(NoteColumns.SYNC_ID, node.getLastModified());
-                        mContentResolver.update(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI,
+                        mContentResolver.update(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, //进行批量更改，选择参数为NULL，应该可以用insert替换，参数分别为表名和需要更新的value对象。
                                 c.getLong(SqlNote.ID_COLUMN)), values, null, null);
                     } else {
                         Log.e(TAG, "something is missed");
@@ -790,10 +935,18 @@ public class GTaskManager {
         }
     }
 
+    /**
+     * 功能：获取同步账号,mAccount.name
+     * @return String
+     */
     public String getSyncAccount() {
         return GTaskClient.getInstance().getSyncAccount().name;
     }
 
+    /**
+     * 功能：取消同步，置mCancelled为true
+     * @author TTS
+     */
     public void cancelSync() {
         mCancelled = true;
     }

src/xiaomi/Notes-master/src/net/micode/notes/gtask/remote/GTaskSyncService.java

@@ -22,7 +22,16 @@ import android.content.Context;
 import android.content.Intent;
 import android.os.Bundle;
 import android.os.IBinder;
-
+/**
+ * @aPackage :      net.micode.notes.gtask.remote
+ * @aClassName:     GTaskSyncService
+ * @Description:
+ * 该类继承了Service父类，Service是在一段不定的时间运行在后台，不和用户交互的应用组件
+ * 作用：
+ * GTask同步服务，用于提供同步服务（开始、取消同步)，发送广播
+ * @aAuthor:        Li Qiushi
+ * @createdate:     12/24/2023 20:15 PM
+ */
 public class GTaskSyncService extends Service {
     public final static String ACTION_STRING_NAME = "sync_action_type";
 
@@ -42,20 +51,28 @@ public class GTaskSyncService extends Service {
 
     private static String mSyncProgress = "";
 
+    /**
+     *功能：用于自动一个同步任务
+     */
     private void startSync() {
+        /*
+        如果mSyncTask为null，则创建一个新的GTaskASyncTask对象，并将其赋值给mSyncTask
+        这个新对象的构造函数接受两个参数：当前对象（this）和一个Lambda表达式
+         */
         if (mSyncTask == null) {
-            mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
+            mSyncTask = new GTaskASyncTask(this, () -> {
-                public void onComplete() {
+                mSyncTask = null;
-                    mSyncTask = null;
+                sendBroadcast("");
-                    sendBroadcast("");
+                stopSelf();
-                    stopSelf();
-                }
             });
             sendBroadcast("");
             mSyncTask.execute();
         }
     }
 
+    /**
+     * 功能：取消同步任务，以避免不必要的资源占用和潜在的错误
+     */
     private void cancelSync() {
         if (mSyncTask != null) {
             mSyncTask.cancelSync();
@@ -67,11 +84,20 @@ public class GTaskSyncService extends Service {
         mSyncTask = null;
     }
 
+    /**
+     * 功能：
+     * 用于处理启动服务时的命令
+     * @param intent
+     * @param flags
+     * @param startId
+     * @return int
+     */
     @Override
     public int onStartCommand(Intent intent, int flags, int startId) {
         Bundle bundle = intent.getExtras();
         if (bundle != null && bundle.containsKey(ACTION_STRING_NAME)) {
             switch (bundle.getInt(ACTION_STRING_NAME, ACTION_INVALID)) {
+                //两种情况，开始同步或者取消同步
                 case ACTION_START_SYNC:
                     startSync();
                     break;
@@ -86,6 +112,9 @@ public class GTaskSyncService extends Service {
         return super.onStartCommand(intent, flags, startId);
     }
 
+    /**
+     * 功能：用于处理低内存情况，当系统内存不足时，该方法会被调用
+     */
     @Override
     public void onLowMemory() {
         if (mSyncTask != null) {
@@ -97,24 +126,36 @@ public class GTaskSyncService extends Service {
         return null;
     }
 
+    /**
+     * 功能：发送一个广播消息，通知其他组件或服务有关同步任务的状态和进度信息
+     * @param msg
+     */
     public void sendBroadcast(String msg) {
         mSyncProgress = msg;
         Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
         intent.putExtra(GTASK_SERVICE_BROADCAST_IS_SYNCING, mSyncTask != null);
         intent.putExtra(GTASK_SERVICE_BROADCAST_PROGRESS_MSG, msg);
-        sendBroadcast(intent);
+        sendBroadcast(intent);//将intent对象发送出去，以便其他组件或服务可以接收到这个广播消息并进行相应的处理
     }
 
+    /**
+     * 功能：启动一个名为GTaskSyncService的服务来进行同步操作
+     * @param activity
+     */
     public static void startSync(Activity activity) {
         GTaskManager.getInstance().setActivityContext(activity);
         Intent intent = new Intent(activity, GTaskSyncService.class);
         intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_START_SYNC);
-        activity.startService(intent);
+        activity.startService(intent);//启动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);
+        intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_CANCEL_SYNC);//向Intent对象添加额外的数据
         context.startService(intent);
     }
 

src/xiaomi/Notes-master/src/net/micode/notes/tool/BackupUtils.java

@@ -34,53 +34,90 @@ import java.io.FileNotFoundException;
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.PrintStream;
-
+/**
+ * @aPackage :      net.micode.notes.tool
+ * @aClassName:     BackupUtils
+ * @Description:
+ * 主要功能：备份工具类，用于数据备份读取、显示
+ * 使用单例模式，确保在整个应用程序只有一个实例
+ * @aAuthor:        Li Qiushi
+ * @createdate:     12/23/2023 10:31 AM
+ */
 
 public class BackupUtils {
     private static final String TAG = "BackupUtils";
     // Singleton stuff
     private static BackupUtils sInstance;
 
+    /**
+     * 作用：用于获取BackupUtils类的实例
+     * 使用synchronized关键字确保在多线程环境下的安全性
+     * @param context
+     * @return sInstance
+     */
     public static synchronized BackupUtils getInstance(Context context) {
         if (sInstance == null) {
-            sInstance = new BackupUtils(context);
+            sInstance = new BackupUtils(context);//创建一个新的BackupUtils实例并将其赋值给sInstance
         }
         return sInstance;
     }
 
     /**
-     * Following states are signs to represents backup or restore
+     * 下列状态是表示备份或还原状态的状态
-     * status
      */
-    // Currently, the sdcard is not mounted
+    // 当前SD卡未挂载
     public static final int STATE_SD_CARD_UNMOUONTED           = 0;
-    // The backup file not exist
+
+    // 备份文件不存在
     public static final int STATE_BACKUP_FILE_NOT_EXIST        = 1;
-    // The data is not well formated, may be changed by other programs
+
+    //数据格式错误
     public static final int STATE_DATA_DESTROIED               = 2;
-    // Some run-time exception which causes restore or backup fails
+
+    // 系统错误
     public static final int STATE_SYSTEM_ERROR                 = 3;
-    // Backup or restore success
+
+    // 备份或恢复成功
     public static final int STATE_SUCCESS                      = 4;
 
     private TextExport mTextExport;
 
+    /**
+     * 作用：接收一个Context参数，并使用该参数创建一个TextExport实例
+     * @param context
+     */
     private BackupUtils(Context context) {
         mTextExport = new TextExport(context);
     }
 
+    /**
+     * 作用： 用于检查外部存储是否可用
+     * @return boolean
+     */
     private static boolean externalStorageAvailable() {
         return Environment.MEDIA_MOUNTED.equals(Environment.getExternalStorageState());
     }
 
+    /**
+     * 作用：用于将数据导出到文本文件。
+     * @return int
+     */
     public int exportToText() {
         return mTextExport.exportToText();
     }
 
+    /**
+     * 作用：用于获取导出的文本文件名
+     * @return String
+     */
     public String getExportedTextFileName() {
         return mTextExport.mFileName;
     }
 
+    /**
+     * 作用：用于获取导出的文本文件目录
+     * @return String
+     */
     public String getExportedTextFileDir() {
         return mTextExport.mFileDirectory;
     }
@@ -125,6 +162,10 @@ public class BackupUtils {
         private String mFileName;
         private String mFileDirectory;
 
+        /**
+         * 作用：接收一个Context对象作为参数，并初始化一些成员变量，如TEXT_FORMAT、mContext、mFileName和mFileDirectory
+         * @param context
+         */
         public TextExport(Context context) {
             TEXT_FORMAT = context.getResources().getStringArray(R.array.format_for_exported_note);
             mContext = context;
@@ -132,12 +173,19 @@ public class BackupUtils {
             mFileDirectory = "";
         }
 
+        /**
+         * 作用：根据传入的id返回对应的文本格式
+         * @param id
+         * @return String
+         */
         private String getFormat(int id) {
             return TEXT_FORMAT[id];
         }
 
         /**
-         * Export the folder identified by folder id to text
+         * 作用：用于将指定文件夹下的所有笔记导出为文本文件
+         * @param folderId
+         * @param ps
          */
         private void exportFolderToText(String folderId, PrintStream ps) {
             // Query notes belong to this folder
@@ -146,6 +194,9 @@ public class BackupUtils {
                         folderId
                     }, null);
 
+            /*
+            查询该文件夹下的所有笔记，然后遍历每个笔记，打印其最后修改日期和内容
+             */
             if (notesCursor != null) {
                 if (notesCursor.moveToFirst()) {
                     do {
@@ -155,7 +206,7 @@ public class BackupUtils {
                                 notesCursor.getLong(NOTE_COLUMN_MODIFIED_DATE))));
                         // Query data belong to this note
                         String noteId = notesCursor.getString(NOTE_COLUMN_ID);
-                        exportNoteToText(noteId, ps);
+                        exportNoteToText(noteId, ps);//将笔记的内容导出为文本
                     } while (notesCursor.moveToNext());
                 }
                 notesCursor.close();
@@ -163,9 +214,12 @@ public class BackupUtils {
         }
 
         /**
-         * Export note identified by id to a print stream
+         * 作用：将指定ID的笔记导出到文本文件中，包括电话记录和普通笔记的内容
+         * @param noteId
+         * @param ps
          */
         private void exportNoteToText(String noteId, PrintStream ps) {
+            //查询与给定noteId相关的数据，并将结果存储在Cursor对象dataCursor中
             Cursor dataCursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI,
                     DATA_PROJECTION, DataColumns.NOTE_ID + "=?", new String[] {
                         noteId
@@ -175,6 +229,9 @@ public class BackupUtils {
                 if (dataCursor.moveToFirst()) {
                     do {
                         String mimeType = dataCursor.getString(DATA_COLUMN_MIME_TYPE);
+                        /*
+                        表示该记录是一个电话记录,此时，获取电话记录中的电话号码、通话日期和位置信息，并将其格式化后输出到PrintStream对象ps中
+                         */
                         if (DataConstants.CALL_NOTE.equals(mimeType)) {
                             // Print phone number
                             String phoneNumber = dataCursor.getString(DATA_COLUMN_PHONE_NUMBER);
@@ -194,7 +251,7 @@ public class BackupUtils {
                                 ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
                                         location));
                             }
-                        } else if (DataConstants.NOTE.equals(mimeType)) {
+                        } else if (DataConstants.NOTE.equals(mimeType)) {//表示该记录是一个普通笔记,此时，获取笔记的内容，并将其格式化后输出到PrintStream对象ps中
                             String content = dataCursor.getString(DATA_COLUMN_CONTENT);
                             if (!TextUtils.isEmpty(content)) {
                                 ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
@@ -205,7 +262,7 @@ public class BackupUtils {
                 }
                 dataCursor.close();
             }
-            // print a line separator between note
+            // 向PrintStream对象ps中写入一个换行符，用于分隔不同笔记之间的内容
             try {
                 ps.write(new byte[] {
                         Character.LINE_SEPARATOR, Character.LETTER_NUMBER
@@ -216,14 +273,21 @@ public class BackupUtils {
         }
 
         /**
-         * Note will be exported as text which is user readable
+         * 作用：将笔记导出到文本文件中
+         * @return int
          */
         public int exportToText() {
+            /*
+            如果外部存储未挂载，则记录一条日志并返回一个表示外部存储未挂载的状态码（STATE_SD_CARD_UNMOUONTED）
+             */
             if (!externalStorageAvailable()) {
                 Log.d(TAG, "Media was not mounted");
                 return STATE_SD_CARD_UNMOUONTED;
             }
-
+            /*
+            获取一个用于输出到文本文件的打印流（PrintStream），并将其赋值给变量ps
+            如果获取打印流失败，则记录一条错误日志并返回一个表示系统错误的状态码（STATE_SYSTEM_ERROR）
+             */
             PrintStream ps = getExportToTextPrintStream();
             if (ps == null) {
                 Log.e(TAG, "get print stream error");
@@ -237,7 +301,9 @@ public class BackupUtils {
                             + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER + ") OR "
                             + NoteColumns.ID + "=" + Notes.ID_CALL_RECORD_FOLDER, null, null);
 
+
             if (folderCursor != null) {
+
                 if (folderCursor.moveToFirst()) {
                     do {
                         // Print folder's name
@@ -247,6 +313,7 @@ public class BackupUtils {
                         } else {
                             folderName = folderCursor.getString(NOTE_COLUMN_SNIPPET);
                         }
+                        //将格式化后的文件夹名称写入打印流ps
                         if (!TextUtils.isEmpty(folderName)) {
                             ps.println(String.format(getFormat(FORMAT_FOLDER_NAME), folderName));
                         }
@@ -264,6 +331,10 @@ public class BackupUtils {
                     NoteColumns.TYPE + "=" + +Notes.TYPE_NOTE + " AND " + NoteColumns.PARENT_ID
                             + "=0", null, null);
 
+            /*如果noteCursor不为空，则遍历查询结果
+            将格式化后的笔记修改日期写入打印流ps
+            获取笔记的ID，并调用exportNoteToText方法将笔记的内容导出到文本文件中
+             */
             if (noteCursor != null) {
                 if (noteCursor.moveToFirst()) {
                     do {
@@ -283,16 +354,21 @@ public class BackupUtils {
         }
 
         /**
-         * Get a print stream pointed to the file {@generateExportedTextFile}
+         * 作用：建一个用于导出文本的PrintStream对象
+         * @return PrintStream
          */
         private PrintStream getExportToTextPrintStream() {
+            //生成一个文件，该文件位于SD卡上
             File file = generateFileMountedOnSDcard(mContext, R.string.file_path,
                     R.string.file_name_txt_format);
+            /*
+            表示创建文件失败，此时会记录一条错误日志（Log.e(TAG, "create file to exported failed")）
+             */
             if (file == null) {
                 Log.e(TAG, "create file to exported failed");
                 return null;
             }
-            mFileName = file.getName();
+            mFileName = file.getName();//文件名赋值给成员变量mFileName
             mFileDirectory = mContext.getString(R.string.file_path);
             PrintStream ps = null;
             try {
@@ -310,19 +386,27 @@ public class BackupUtils {
     }
 
     /**
-     * Generate the text file to store imported data
+     * 作用：用于在Android设备上生成一个文件
+     * @param context
+     * @param filePathResId
+     * @param fileNameFormatResId
+     * @return File
      */
     private static File generateFileMountedOnSDcard(Context context, int filePathResId, int fileNameFormatResId) {
         StringBuilder sb = new StringBuilder();
-        sb.append(Environment.getExternalStorageDirectory());
+        sb.append(Environment.getExternalStorageDirectory()); //获取外部存储设备的根目录
-        sb.append(context.getString(filePathResId));
+        sb.append(context.getString(filePathResId)); //根据传入的filePathResId参数，将指定的路径添加到根目录下
         File filedir = new File(sb.toString());
+        //根据传入的fileNameFormatResId参数和当前日期时间，生成文件名，并将其添加到目录路径中
         sb.append(context.getString(
                 fileNameFormatResId,
                 DateFormat.format(context.getString(R.string.format_date_ymd),
                         System.currentTimeMillis())));
         File file = new File(sb.toString());
-
+        /*
+        尝试创建文件所在的目录（如果不存在），并创建文件本身（如果不存在）
+        如果成功创建了文件，返回该文件的引用；否则，返回null
+         */
         try {
             if (!filedir.exists()) {
                 filedir.mkdir();
@@ -338,7 +422,7 @@ public class BackupUtils {
         }
 
         return null;
+        }
     }
-}
 
 

src/xiaomi/Notes-master/src/net/micode/notes/tool/DataUtils.java

@@ -33,21 +33,38 @@ import net.micode.notes.ui.NotesListAdapter.AppWidgetAttribute;
 
 import java.util.ArrayList;
 import java.util.HashSet;
-
+/**
+ * @aPackage :      net.micode.notes.tool
+ * @aClassName:     DataUtils
+ * @Description:
+ * 主要功能：实现便签数据处理工具类，封装如查找、移动、删除数据等操作
+ * @aAuthor:        Li Qiushi
+ * @createdate:     12/30/2023 08:31 AM
+ */
 
 public class DataUtils {
     public static final String TAG = "DataUtils";
+
+    /**
+     * 作用：用于批量删除笔记
+     * @param resolver
+     * @param ids
+     * @return boolean
+     */
     public static boolean batchDeleteNotes(ContentResolver resolver, HashSet<Long> ids) {
+        //判断ids是否为空
         if (ids == null) {
             Log.d(TAG, "the ids is null");
             return true;
         }
+        //判断ids大小是否为0
         if (ids.size() == 0) {
             Log.d(TAG, "no id is in the hashset");
             return true;
         }
-
+        //创建类存储删除的动作
         ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
+        //遍历ID，如果发现是根文件夹，则不删除
         for (long id : ids) {
             if(id == Notes.ID_ROOT_FOLDER) {
                 Log.e(TAG, "Don't delete system folder root");
@@ -57,9 +74,10 @@ public class DataUtils {
                     .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) {
+            if (results.length == 0 || results[0] == null) {
                 Log.d(TAG, "delete notes failed, ids:" + ids.toString());
                 return false;
             }
@@ -72,14 +90,29 @@ public class DataUtils {
         return false;
     }
 
+    /**
+     * 作用：将一个笔记从一个文件夹移动到另一个文件夹
+     * @param resolver
+     * @param id
+     * @param srcFolderId
+     * @param desFolderId
+     */
     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.ORIGIN_PARENT_ID, srcFolderId);
         values.put(NoteColumns.LOCAL_MODIFIED, 1);
+        //对需要移动的便签进行数据更新，然后用update实现
         resolver.update(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id), values, null, null);
     }
 
+    /**
+     * 作用：用于将一组笔记（由id集合表示）批量移动到指定的文件夹
+     * @param resolver
+     * @param ids
+     * @param folderId
+     * @return boolean
+     */
     public static boolean batchMoveToFolder(ContentResolver resolver, HashSet<Long> ids,
             long folderId) {
         if (ids == null) {
@@ -89,13 +122,15 @@ public class DataUtils {
 
         ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
         for (long id : ids) {
+            //通过withAppendedId方法，为该Uri加上ID
             ContentProviderOperation.Builder builder = ContentProviderOperation
                     .newUpdate(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id));
             builder.withValue(NoteColumns.PARENT_ID, folderId);
             builder.withValue(NoteColumns.LOCAL_MODIFIED, 1);
             operationList.add(builder.build());
-        }
+        }//将ids里包含的每一列的数据逐次加入到operationList中，等待最后的批量处理
 
+        //使用ContentResolver的applyBatch方法执行批量更新操作
         try {
             ContentProviderResult[] results = resolver.applyBatch(Notes.AUTHORITY, operationList);
             if (results == null || results.length == 0 || results[0] == null) {
@@ -112,39 +147,50 @@ public class DataUtils {
     }
 
     /**
-     * Get the all folder count except system folders {@link Notes#TYPE_SYSTEM}}
+     * 作用 ：获取除系统文件夹之外的所有文件夹数量
+     * @param resolver
+     * @return count
      */
     public static int getUserFolderCount(ContentResolver resolver) {
         Cursor cursor =resolver.query(Notes.CONTENT_NOTE_URI,
                 new String[] { "COUNT(*)" },
                 NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>?",
+                //筛选条件：源文件不为trash folder，即垃圾文件
                 new String[] { String.valueOf(Notes.TYPE_FOLDER), String.valueOf(Notes.ID_TRASH_FOLER)},
                 null);
 
         int count = 0;
-        if(cursor != null) {
+        if(cursor != null && cursor.moveToFirst()) {
-            if(cursor.moveToFirst()) {
+            try {
-                try {
+                //获取文件夹的数量，并将其赋值给count变量
-                    count = cursor.getInt(0);
+                count = cursor.getInt(0);
-                } catch (IndexOutOfBoundsException e) {
+            } catch (IndexOutOfBoundsException e) {
-                    Log.e(TAG, "get folder count failed:" + e.toString());
+                Log.e(TAG, "get folder count failed:" + e.toString());
-                } finally {
+            } finally {
-                    cursor.close();
+                cursor.close();
-                }
             }
         }
         return count;
     }
 
+    /**
+     * 作用：用于检查一个笔记是否在Note数据库中可见
+     * @param resolver
+     * @param noteId
+     * @param type
+     * @return boolean
+     */
     public static boolean visibleInNoteDatabase(ContentResolver resolver, long noteId, int type) {
         Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId),
                 null,
+                //查询条件：type符合，且不属于垃圾文件夹
                 NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER,
                 new String [] {String.valueOf(type)},
                 null);
 
         boolean exist = false;
         if (cursor != null) {
+            //用getCount函数判断cursor是否为空
             if (cursor.getCount() > 0) {
                 exist = true;
             }
@@ -153,6 +199,12 @@ public class DataUtils {
         return exist;
     }
 
+    /**
+     * 作用：用于检查一个笔记是否存在于Note数据库中
+     * @param resolver
+     * @param noteId
+     * @return boolean
+     */
     public static boolean existInNoteDatabase(ContentResolver resolver, long noteId) {
         Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId),
                 null, null, null, null);
@@ -167,6 +219,12 @@ public class DataUtils {
         return exist;
     }
 
+    /**
+     * 作用：用于检查给定的数据ID是否存在于数据数据库中(检查方法同上)
+     * @param resolver
+     * @param dataId
+     * @return boolean
+     */
     public static boolean existInDataDatabase(ContentResolver resolver, long dataId) {
         Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, dataId),
                 null, null, null, null);
@@ -181,6 +239,12 @@ public class DataUtils {
         return exist;
     }
 
+    /**
+     * 作用：用于检查给定的文件夹名称是否在Notes数据库中可见
+     * @param resolver
+     * @param name
+     * @return boolean
+     */
     public static boolean checkVisibleFolderName(ContentResolver resolver, String name) {
         Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI, null,
                 NoteColumns.TYPE + "=" + Notes.TYPE_FOLDER +
@@ -188,6 +252,7 @@ public class DataUtils {
                 " AND " + NoteColumns.SNIPPET + "=?",
                 new String[] { name }, null);
         boolean exist = false;
+        //通过名字查询文件是否存在
         if(cursor != null) {
             if(cursor.getCount() > 0) {
                 exist = true;
@@ -197,7 +262,14 @@ public class DataUtils {
         return exist;
     }
 
+    /**
+     * 作用：用于从Notes数据库中获取指定文件夹ID下的所有小部件属性
+     * @param resolver
+     * @param folderId
+     * @return HashSet
+     */
     public static HashSet<AppWidgetAttribute> getFolderNoteWidget(ContentResolver resolver, long folderId) {
+        //查询条件：父ID是传入的folderId
         Cursor c = resolver.query(Notes.CONTENT_NOTE_URI,
                 new String[] { NoteColumns.WIDGET_ID, NoteColumns.WIDGET_TYPE },
                 NoteColumns.PARENT_ID + "=?",
@@ -211,6 +283,10 @@ public class DataUtils {
                 do {
                     try {
                         AppWidgetAttribute widget = new AppWidgetAttribute();
+                        /*
+                            0对应NoteColumns.WIDGET_ID
+                            1行应的NoteColumns.WIDGET_TYPE
+                         */
                         widget.widgetId = c.getInt(0);
                         widget.widgetType = c.getInt(1);
                         set.add(widget);
@@ -224,6 +300,12 @@ public class DataUtils {
         return set;
     }
 
+    /**
+     * 作用：用于根据笔记ID获取通话记录中的电话号码
+     * @param resolver
+     * @param noteId
+     * @return String
+     */
     public static String getCallNumberByNoteId(ContentResolver resolver, long noteId) {
         Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI,
                 new String [] { CallNote.PHONE_NUMBER },
@@ -243,6 +325,13 @@ public class DataUtils {
         return "";
     }
 
+    /**
+     * 作用：用于根据电话号码和通话日期从Android的ContentResolver中查询Notes数据库中的记录
+     * @param resolver
+     * @param phoneNumber
+     * @param callDate
+     * @return long
+     */
     public static long getNoteIdByPhoneNumberAndCallDate(ContentResolver resolver, String phoneNumber, long callDate) {
         Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI,
                 new String [] { CallNote.NOTE_ID },
@@ -264,7 +353,14 @@ public class DataUtils {
         return 0;
     }
 
+    /**
+     * 作用：根据给定的noteId从ContentResolver中获取对应的笔记片段（snippet）
+     * @param resolver
+     * @param noteId
+     * @return String
+     */
     public static String getSnippetById(ContentResolver resolver, long noteId) {
+        //查询条件：noteId
         Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI,
                 new String [] { NoteColumns.SNIPPET },
                 NoteColumns.ID + "=?",
@@ -282,6 +378,11 @@ public class DataUtils {
         throw new IllegalArgumentException("Note is not found with id: " + noteId);
     }
 
+    /**
+     * 作用：对输入的字符串进行处理，返回处理后的字符串
+     * @param snippet
+     * @return String
+     */
     public static String getFormattedSnippet(String snippet) {
         if (snippet != null) {
             snippet = snippet.trim();

src/xiaomi/Notes-master/src/net/micode/notes/tool/GTaskStringUtils.java

@@ -15,9 +15,19 @@
  */
 
 package net.micode.notes.tool;
+/**
+ * @aPackage :      net.micode.notes.tool
+ * @aClassName:     GTaskStringUtils
+ * @Description:
+ * 主要功能：同步中使用的字符串工具类，为jsonObject提供string对象
+ * 定义了很多的静态字符串，目的就是为了提供jsonObject中相应字符串的"key"。把这些静态的定义单独写到了一个类里面，方便查看管理
+ * @aAuthor:        Li Qiushi
+ * @createdate:     12/30/2023 10:31 AM
+ */
 
 public class GTaskStringUtils {
 
+
     public final static String GTASK_JSON_ACTION_ID = "action_id";
 
     public final static String GTASK_JSON_ACTION_LIST = "action_list";

src/xiaomi/Notes-master/src/net/micode/notes/tool/ResourceParser.java

@@ -21,7 +21,22 @@ import android.preference.PreferenceManager;
 
 import net.micode.notes.R;
 import net.micode.notes.ui.NotesPreferenceActivity;
-
+/**
+ * @aPackage :      net.micode.notes.tool
+ * @aClassName:     ResourceParser
+ * @Description:
+ * 主要功能：界面元素的解析工具类，利用R.java这个类来获取资源供程序调用
+ * 字面意义是资源分析器，实际上就是获取资源并且在程序中使用，比如颜色图片等
+ * 实现方法：实现方法：主要利用R.java这个类，其中包括
+ * R.id      组件资源引用
+ * R.drawable  图片资源 （被使用）
+ * R.layout  布局资源
+ * R.menu   菜单资源
+ * R.String  文字资源
+ * R.style    主题资源 （被使用）
+ * @aAuthor:        Li Qiushi
+ * @createdate:     12/30/2023 10:31 AM
+ */
 public class ResourceParser {
 
     public static final int YELLOW           = 0;
@@ -39,6 +54,9 @@ public class ResourceParser {
 
     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,