提交

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

@@ -329,6 +329,11 @@ public class TaskList extends Node {
         return (removeChildTask(task) && addChildTask(task, index));
     }
 
+    /**
+     * @param gid
+     * @return返回寻找结果
+     * 功能：按gid寻找Task
+     */
     public Task findChildTaskByGid(String gid) {
         for (int i = 0; i < mChildren.size(); i++) {
             Task t = mChildren.get(i);
@@ -339,10 +344,20 @@ public class TaskList extends Node {
         return null;
     }
 
+    /**
+     * @param task
+     * @return
+     * 功能：返回指定Task的index
+     */
     public int getChildTaskIndex(Task task) {
         return mChildren.indexOf(task);
     }
 
+    /**
+     * @param index
+     * @return
+     * 功能：返回指定index的Task
+     */
     public Task getChildTaskByIndex(int index) {
         if (index < 0 || index >= mChildren.size()) {
             Log.e(TAG, "getTaskByIndex: invalid index");
@@ -351,6 +366,11 @@ public class TaskList extends Node {
         return mChildren.get(index);
     }
 
+    /**
+     * @param gid
+     * @return
+     * 功能：返回指定gid的Task
+     */
     public Task getChilTaskByGid(String gid) {
         for (Task task : mChildren) {
             if (task.getGid().equals(gid))

java/net/micode/notes/gtask/exception/ActionFailureException.java

@@ -16,13 +16,24 @@
 
 package net.micode.notes.gtask.exception;
 
+/*
+ * Description：支持小米便签运行过程中的运行异常处理。
+ */
 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);
     }

java/net/micode/notes/gtask/exception/NetworkFailureException.java

@@ -13,16 +13,27 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
+/*
+ * Description：支持小米便签运行过程中的网络异常处理。
+ */
 package net.micode.notes.gtask.exception;
 
 public class NetworkFailureException extends Exception {
     private static final long serialVersionUID = 2107610287180234136L;
-
+    /*
+     * serialVersionUID相当于java类的身份证。主要用于版本控制。
+     * serialVersionUID作用是序列化时保持版本的兼容性，即在版本升级时反序列化仍保持对象的唯一性。
+     */
     public NetworkFailureException() {
         super();
     }
 
+    /*
+     * 在JAVA类中使用super来引用父类的成分，用this来引用当前对象.
+     * 如果一个类从另外一个类继承，我们new这个子类的实例对象的时候，这个子类对象里面会有一个父类对象。
+     * 怎么去引用里面的父类对象呢？使用super来引用
+     * 也就是说，此处super()以及super (paramString)可认为是Exception ()和Exception (paramString)
+     */
     public NetworkFailureException(String paramString) {
         super(paramString);
     }

java/net/micode/notes/gtask/remote/GTaskASyncTask.java

@@ -28,7 +28,13 @@ import net.micode.notes.R;
 import net.micode.notes.ui.NotesListActivity;
 import net.micode.notes.ui.NotesPreferenceActivity;
 
-
+/*异步操作类，实现GTask的异步操作过程
+ * 主要方法：
+ * private void showNotification(int tickerId, String content) 向用户提示当前同步的状态，是一个用于交互的方法
+ * protected Integer doInBackground(Void... unused) 此方法在后台线程执行，完成任务的主要工作，通常需要较长的时间
+ * protected void onProgressUpdate(String... progress)  可以使用进度条增加用户体验度。 此方法在主线程执行，用于显示任务执行的进度。
+ * protected void onPostExecute(Integer result)  相当于Handler 处理UI的方式，在这里面可以使用在doInBackground 得到的结果处理操作UI
+ */
 public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
     private static int GTASK_SYNC_NOTIFICATION_ID = 5234235; // 通知ID
 

java/net/micode/notes/gtask/remote/GTaskClient.java

@@ -60,7 +60,10 @@ import java.util.zip.GZIPInputStream;
 import java.util.zip.Inflater;
 import java.util.zip.InflaterInputStream;
 
-
+/*
+ * 主要功能：实现GTASK的登录操作，进行GTASK任务的创建，创建任务列表，从网络上获取任务和任务列表的内容
+ * 主要使用类或技术：accountManager JSONObject HttpParams authToken Gid
+ */
 public class GTaskClient {
     private static final String TAG = GTaskClient.class.getSimpleName();
 
@@ -90,6 +93,7 @@ public class GTaskClient {
 
     private JSONArray mUpdateArray;
 
+
     private GTaskClient() {
         mHttpClient = null;
         mGetUrl = GTASK_GET_URL;
@@ -102,6 +106,10 @@ public class GTaskClient {
         mUpdateArray = null;
     }
 
+    /*用来获取的实例化对象
+     * 使用 getInstance()
+     * 返回mInstance这个实例化对象
+     */
     public static synchronized GTaskClient getInstance() {
         if (mInstance == null) {
             mInstance = new GTaskClient();
@@ -109,42 +117,54 @@ 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
         // then we need to re-login
+        //判断距离最后一次登录操作是否超过5分钟
         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();
         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";
-            mPostUrl = url.toString() + "r/ig";
+            mGetUrl = url.toString() + "ig"; //设置用户对应的getUrl
+            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,9 +185,17 @@ public class GTaskClient {
         return true;
     }
 
-    private String loginGoogleAccount(Activity activity, boolean invalidateToken) {
+    /*具体实现登录谷歌账户的方法
+     * 使用令牌机制
+     * 使用AccountManager来管理注册账号
+     * 返回值是账号的令牌
+     */
+    private String loginGoogleAccount(Activity activity, boolean invalidateToken) {//令牌，是登录操作保证安全性的一个方法
         String authToken;
+        //AccountManager这个类给用户提供了集中注册账号的接口
         AccountManager accountManager = AccountManager.get(activity);
+
+        //获取全部以com.google结尾的account
         Account[] accounts = accountManager.getAccountsByType("com.google");
 
         if (accounts.length == 0) {
@@ -176,6 +205,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 +220,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 +239,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
             // token and try again
+
+            //删除过一个无效的authToken，申请一个新的后再次尝试登陆
             authToken = loginGoogleAccount(activity, true);
             if (authToken == null) {
                 Log.e(TAG, "login google account failed");
@@ -225,25 +260,34 @@ public class GTaskClient {
         return true;
     }
 
+    //实现登录GTask的具体操作
     private boolean loginGtask(String authToken) {
         int timeoutConnection = 10000;
         int timeoutSocket = 15000;
+        //socket是一种通信连接实现数据的交换的端口
         HttpParams httpParameters = new BasicHttpParams();
+        //实例化一个新的HTTP参数类
         HttpConnectionParams.setConnectionTimeout(httpParameters, timeoutConnection);
+        //设置连接超时时间
         HttpConnectionParams.setSoTimeout(httpParameters, timeoutSocket);
+        //设置设置端口超时时间
         mHttpClient = new DefaultHttpClient(httpParameters);
         BasicCookieStore localBasicCookieStore = new BasicCookieStore();
+        //设置本地cookie
         mHttpClient.setCookieStore(localBasicCookieStore);
         HttpProtocolParams.setUseExpectContinue(mHttpClient.getParams(), false);
 
         // login gtask
         try {
             String loginUrl = mGetUrl + "?auth=" + authToken;
+            //设置登录的url
             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 +300,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>";
@@ -284,6 +329,10 @@ public class GTaskClient {
         return mActionId++;
     }
 
+    /*实例化创建一个用于向网络传输数据的对象
+     * 使用HttpPost类
+     * 返回一个httpPost实例化对象，但里面还没有内容
+     */
     private HttpPost createHttpPost() {
         HttpPost httpPost = new HttpPost(mPostUrl);
         httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
@@ -291,17 +340,23 @@ public class GTaskClient {
         return httpPost;
     }
 
+    /*通过URL获取响应后返回的数据，也就是网络上的数据和资源
+     * 使用getContentEncoding()获取网络上的资源和数据
+     * 返回值就是获取到的资源
+     */
     private String getResponseContent(HttpEntity entity) throws IOException {
         String contentEncoding = null;
         if (entity.getContentEncoding() != null) {
+            //通过URL得到HttpEntity对象，如果不为空则使用getContent（）方法创建一个流将数据从网络都过来
             contentEncoding = entity.getContentEncoding().getValue();
             Log.d(TAG, "encoding: " + contentEncoding);
         }
 
         InputStream input = entity.getContent();
         if (contentEncoding != null && contentEncoding.equalsIgnoreCase("gzip")) {
+//GZIP是使用DEFLATE进行压缩数据的另一个压缩库
             input = new GZIPInputStream(entity.getContent());
-        } else if (contentEncoding != null && contentEncoding.equalsIgnoreCase("deflate")) {
+        } else if (contentEncoding != null && contentEncoding.equalsIgnoreCase("deflate")) {//DEFLATE是一个无专利的压缩算法，它可以实现无损数据压缩
             Inflater inflater = new Inflater(true);
             input = new InflaterInputStream(entity.getContent(), inflater);
         }
@@ -309,6 +364,7 @@ public class GTaskClient {
         try {
             InputStreamReader isr = new InputStreamReader(input);
             BufferedReader br = new BufferedReader(isr);
+//是一个包装类，它可以包装字符流，将字符流放入缓存里，先把字符读到缓存里，到缓存满了时候，再读入内存，是为了提供读的效率而设计的
             StringBuilder sb = new StringBuilder();
 
             while (true) {
@@ -323,12 +379,19 @@ public class GTaskClient {
         }
     }
 
+    /*通过JSON发送请求
+     * 请求的具体内容在json的实例化对象js中然后传入
+     * 利用UrlEncodedFormEntity entity和httpPost.setEntity(entity)方法把js中的内容放置到httpPost中
+     * 执行请求后使用getResponseContent方法得到返回的数据和资源
+     * 将资源再次放入json后返回
+     */
+
     private JSONObject postRequest(JSONObject js) throws NetworkFailureException {
         if (!mLoggedin) {
             Log.e(TAG, "please login first");
             throw new ActionFailureException("not logged in");
         }
-
+        //实例化一个httpPost的对象用来向服务器传输数据，在这里就是发送请求，而请求的内容在js里
         HttpPost httpPost = createHttpPost();
         try {
             LinkedList<BasicNameValuePair> list = new LinkedList<BasicNameValuePair>();
@@ -360,6 +423,13 @@ public class GTaskClient {
         }
     }
 
+    /*创建单个任务
+     * 传入参数是一个.gtask.data.Task包里Task类的对象
+     * 利用json获取Task里的内容,并且创建相应的jsPost
+     * 利用postRequest得到任务的返回信息
+     * 使用task.setGid设置task的new_ID
+     */
+
     public void createTask(Task task) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -386,6 +456,9 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 创建一个任务列表，与createTask几乎一样，区别就是最后设置的是tasklist的gid
+     */
     public void createTaskList(TaskList tasklist) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -412,6 +485,11 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 同步更新操作
+     * 使用JSONObject进行数据存储，使用jsPost.put，Put的信息包括UpdateArray和ClientVersion
+     * 使用postRequest发送这个jspost,进行处理
+     */
     public void commitUpdate() throws NetworkFailureException {
         if (mUpdateArray != null) {
             try {
@@ -433,6 +511,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 +529,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();
@@ -462,6 +550,8 @@ public class GTaskClient {
             action.put(GTaskStringUtils.GTASK_JSON_ID, task.getGid());
             if (preParent == curParent && task.getPriorSibling() != null) {
                 // put prioring_sibing_id only if moving within the tasklist and
+
+                //设置优先级ID，只有当移动是发生在文件中
                 // it is not the first one
                 action.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, task.getPriorSibling());
             }
@@ -472,6 +562,7 @@ public class GTaskClient {
                 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 +577,11 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 删除操作节点
+     * 还是利用JSON
+     * 删除过后使用postRequest发送删除后的结果
+     */
     public void deleteNode(Node node) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -509,6 +605,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 +622,7 @@ public class GTaskClient {
             response = mHttpClient.execute(httpGet);
 
             // get the task list
+            //筛选工作，把筛选出的字符串放入jsString
             String resString = getResponseContent(response.getEntity());
             String jsBegin = "_setup(";
             String jsEnd = ")}</script>";
@@ -547,6 +649,9 @@ public class GTaskClient {
         }
     }
 
+    /*
+     * 通过传入的TASKList的gid,从网络上获取相应属于这个任务列表的任务
+     */
     public JSONArray getTaskList(String listGid) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -579,6 +684,8 @@ public class GTaskClient {
         return mAccount;
     }
 
+
+    //重置更新的内容
     public void resetUpdateArray() {
         mUpdateArray = null;
     }

java/net/micode/notes/gtask/remote/GTaskManager.java

@@ -87,10 +87,13 @@ public class GTaskManager {
 
     private HashMap<Long, String> mNidToGid;
 
-    private GTaskManager() {
+    private GTaskManager() {//对象初始化函数
         mSyncing = false;
+        //正在同步,flase代表未执行
         mCancelled = false;
+        //全局标识，flase代表可以执行
         mGTaskListHashMap = new HashMap<String, TaskList>();
+        //<>代表Java的泛型,就是创建一个用类型作为参数的类。
         mGTaskHashMap = new HashMap<String, Node>();
         mMetaHashMap = new HashMap<String, MetaData>();
         mMetaList = null;
@@ -98,22 +101,42 @@ public class GTaskManager {
         mGidToNid = new HashMap<String, Long>();
         mNidToGid = new HashMap<Long, String>();
     }
-
-    public static synchronized GTaskManager getInstance() {
+    /*
+     * 包含关键字synchronized，语言级同步，指明该函数可能运行在多线程的环境下。
+     * 功能：类初始化函数
+     * @author TTS
+     * @return GtaskManger
+     */
+
+    public static synchronized GTaskManager getInstance() { //可能运行在多线程环境下，使用语言级同步--synchronized
         if (mInstance == null) {
             mInstance = new GTaskManager();
         }
         return mInstance;
     }
 
+    /*
+     * 包含关键字synchronized，语言级同步，指明该函数可能运行在多线程的环境下。
+     * @author TTS
+     * @param activity
+     */
     public synchronized void setActivityContext(Activity activity) {
         // used for getting authtoken
         mActivity = activity;
     }
 
+    /*
+     * 核心函数
+     * 功能：实现了本地同步操作和远端同步操作
+     * @author TTS
+     * @param context-----获取上下文
+     * @param asyncTask-------用于同步的异步操作类
+     * @return int
+     */
     public int sync(Context context, GTaskASyncTask asyncTask) {
         if (mSyncing) {
             Log.d(TAG, "Sync is in progress");
+            //创建日志文件（调试信息），debug
             return STATE_SYNC_IN_PROGRESS;
         }
         mContext = context;
@@ -130,6 +153,7 @@ public class GTaskManager {
         try {
             GTaskClient client = GTaskClient.getInstance();
             client.resetUpdateArray();
+//JSONArray类型，reset即置为NULL
 
             // login google task
             if (!mCancelled) {
@@ -141,14 +165,18 @@ public class GTaskManager {
             // get the task list from google
             asyncTask.publishProgess(mContext.getString(R.string.sync_progress_init_list));
             initGTaskList();
+            //获取Google上的JSONtasklist转为本地TaskList
 
             // do content sync work
             asyncTask.publishProgess(mContext.getString(R.string.sync_progress_syncing));
             syncContent();
         } catch (NetworkFailureException e) {
+            //分为两种异常，此类异常为网络异常
             Log.e(TAG, e.toString());
+            //创建日志文件（调试信息），error
             return STATE_NETWORK_ERROR;
         } catch (ActionFailureException e) {
+            //此类异常为操作异常
             Log.e(TAG, e.toString());
             return STATE_INTERNAL_ERROR;
         } catch (Exception e) {
@@ -168,11 +196,22 @@ public class GTaskManager {
         return mCancelled ? STATE_SYNC_CANCELLED : STATE_SUCCESS;
     }
 
+    /*
+     *功能：初始化GtaskList，获取Google上的JSONtasklist转为本地TaskList。
+     *获得的数据存储在mMetaList，mGTaskListHashMap，mGTaskHashMap
+     *@author TTS
+     *@exception NetworkFailureException
+     *@return void
+     */
+
     private void initGTaskList() throws NetworkFailureException {
         if (mCancelled)
             return;
         GTaskClient client = GTaskClient.getInstance();
-        try {
+        try {//Json对象是Name Value对(即子元素)的无序集合，相当于一个Map对象。JsonObject类是bantouyan-json库对Json对象的抽象，提供操纵Json对象的各种方法。
+            //其格式为{"key1":value1,"key2",value2....};key 必须是字符串。
+            //因为ajax请求不刷新页面，但配合js可以实现局部刷新，因此json常常被用来作为异步请求的返回对象使用。
+
             JSONArray jsTaskLists = client.getTaskLists();
 
             // init meta list first
@@ -185,7 +224,7 @@ public class GTaskManager {
                 if (name
                         .equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_META)) {
                     mMetaList = new TaskList();
-                    mMetaList.setContentByRemoteJSON(object);
+                    mMetaList.setContentByRemoteJSON(object);//将JSON中部分数据复制到自己定义的对象中相对应的数据：name->mname...
 
                     // load meta data
                     JSONArray jsMetas = client.getTaskList(gid);
@@ -247,9 +286,17 @@ public class GTaskManager {
         }
     }
 
+    /*
+     * 功能：本地内容同步操作
+     * @throws NetworkFailureException
+     * @return 无返回值
+     */
     private void syncContent() throws NetworkFailureException {
+        //本地内容同步操作
         int syncType;
         Cursor c = null;
+
+        //数据库指针
         String gid;
         Node node;
 
@@ -476,6 +523,14 @@ public class GTaskManager {
             GTaskClient.getInstance().commitUpdate();
     }
 
+    /*
+     * 功能：syncType分类，addLocalNode，addRemoteNode，deleteNode，updateLocalNode，updateRemoteNode
+     * @author TTS
+     * @param syncType
+     * @param node
+     * @param c
+     * @throws NetworkFailureException
+     */
     private void doContentSync(int syncType, Node node, Cursor c) throws NetworkFailureException {
         if (mCancelled) {
             return;
@@ -522,6 +577,12 @@ public class GTaskManager {
         }
     }
 
+    /*
+     * 功能：本地增加Node
+     * @author TTS
+     * @param node
+     * @throws NetworkFailureException
+     */
     private void addLocalNode(Node node) throws NetworkFailureException {
         if (mCancelled) {
             return;
@@ -596,6 +657,16 @@ public class GTaskManager {
         updateRemoteMeta(node.getGid(), sqlNote);
     }
 
+    /*
+     * 功能：update本地node
+     * @author TTS
+     * @param node
+     * ----同步操作的基础数据类型
+     * @param c
+     * ----Cursor
+     * @throws NetworkFailureException
+     */
+
     private void updateLocalNode(Node node, Cursor c) throws NetworkFailureException {
         if (mCancelled) {
             return;
@@ -619,6 +690,17 @@ public class GTaskManager {
         updateRemoteMeta(node.getGid(), sqlNote);
     }
 
+    /*
+     * 功能：远程增加Node
+     * 需要updateRemoteMeta
+     * @author TTS
+     * @param node
+     * ----同步操作的基础数据类型
+     * @param c
+     * --Cursor
+     * @throws NetworkFailureException
+     */
+
     private void addRemoteNode(Node node, Cursor c) throws NetworkFailureException {
         if (mCancelled) {
             return;
@@ -638,7 +720,7 @@ public class GTaskManager {
                 throw new ActionFailureException("cannot add remote task");
             }
             mGTaskListHashMap.get(parentGid).addChildTask(task);
-
+//登录远程服务器，创建Task
             GTaskClient.getInstance().createTask(task);
             n = (Node) task;
 
@@ -656,6 +738,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();
@@ -692,6 +775,16 @@ public class GTaskManager {
         mNidToGid.put(sqlNote.getId(), n.getGid());
     }
 
+    /*
+     * 功能：更新远端的Node，包含meta更新(updateRemoteMeta)
+     * @author TTS
+     * @param node
+     * ----同步操作的基础数据类型
+     * @param c
+     *  --Cursor
+     * @throws NetworkFailureException
+     */
+
     private void updateRemoteNode(Node node, Cursor c) throws NetworkFailureException {
         if (mCancelled) {
             return;
@@ -710,12 +803,14 @@ public class GTaskManager {
         if (sqlNote.isNoteType()) {
             Task task = (Task) node;
             TaskList preParentList = task.getParent();
+            //preParentList为通过node获取的父节点列表
 
             String curParentGid = mNidToGid.get(sqlNote.getParentId());
             if (curParentGid == null) {
                 Log.e(TAG, "cannot find task's parent tasklist");
                 throw new ActionFailureException("cannot update remote task");
             }
+            //通过HashMap找到对应Gid的TaskList
             TaskList curParentList = mGTaskListHashMap.get(curParentGid);
 
             if (preParentList != curParentList) {
@@ -727,9 +822,18 @@ public class GTaskManager {
 
         // clear local modified flag
         sqlNote.resetLocalModified();
-        sqlNote.commit(true);
+        sqlNote.commit(true); //commit到本地数据库
     }
 
+    /**
+     * 功能：升级远程meta。  meta---元数据----计算机文件系统管理数据---管理数据的数据。
+     * @author TTS
+     * @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,6 +850,12 @@ public class GTaskManager {
         }
     }
 
+    /**
+     * 功能：刷新本地，给sync的ID对应上最后更改过的对象
+     * @author TTS
+     * @return void
+     * @throws NetworkFailureException
+     */
     private void refreshLocalSyncId() throws NetworkFailureException {
         if (mCancelled) {
             return;
@@ -790,10 +900,19 @@ public class GTaskManager {
         }
     }
 
+    /**
+     * 功能：获取同步账号,mAccount.name
+     * @author TTS
+     * @return String
+     */
     public String getSyncAccount() {
         return GTaskClient.getInstance().getSyncAccount().name;
     }
 
+    /**
+     * 功能：取消同步，置mCancelled为true
+     * @author TTS
+     */
     public void cancelSync() {
         mCancelled = true;
     }

java/net/micode/notes/gtask/remote/GTaskSyncService.java

@@ -15,6 +15,22 @@
  */
 
 package net.micode.notes.gtask.remote;
+/*
+ * Service是在一段不定的时间运行在后台，不和用户交互的应用组件
+ * 主要方法：
+ * private void startSync()  启动一个同步工作
+ * private void cancelSync() 取消同步
+ * public void onCreate()
+ * public int onStartCommand(Intent intent, int flags, int startId)  service生命周期的组成部分，相当于重启service（比如在被暂停之后），而不是创建一个新的service
+ * public void onLowMemory()  在没有内存的情况下如果存在service则结束掉这的service
+ * public IBinder onBind()
+ * public void sendBroadcast(String msg)   发送同步的相关通知
+ * public static void startSync(Activity activity)
+ * public static void cancelSync(Context context)
+ * public static boolean isSyncing()  判读是否在进行同步
+ * public static String getProgressString()  获取当前进度的信息
+ */
+
 
 import android.app.Activity;
 import android.app.Service;
@@ -42,7 +58,7 @@ public class GTaskSyncService extends Service {
 
     private static String mSyncProgress = "";
 
-    private void startSync() {
+    private void startSync() {//开始一个同步的工作
         if (mSyncTask == null) {
             mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
                 public void onComplete() {
@@ -52,7 +68,7 @@ public class GTaskSyncService extends Service {
                 }
             });
             sendBroadcast("");
-            mSyncTask.execute();
+            mSyncTask.execute();//这个函数让任务是以单线程队列方式或线程池队列方式运行
         }
     }
 
@@ -62,6 +78,7 @@ public class GTaskSyncService extends Service {
         }
     }
 
+    //初始化一个service
     @Override
     public void onCreate() {
         mSyncTask = null;
@@ -72,6 +89,7 @@ public class GTaskSyncService extends Service {
         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;
@@ -81,7 +99,7 @@ public class GTaskSyncService extends Service {
                 default:
                     break;
             }
-            return START_STICKY;
+            return START_STICKY;//等待新的intent来是这个service继续运行
         }
         return super.onStartCommand(intent, flags, startId);
     }
@@ -99,20 +117,20 @@ public class GTaskSyncService extends Service {
 
     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 intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);//创建一个新的Intent
+        intent.putExtra(GTASK_SERVICE_BROADCAST_IS_SYNCING, mSyncTask != null);//附加INTENT中的相应参数的值
         intent.putExtra(GTASK_SERVICE_BROADCAST_PROGRESS_MSG, msg);
-        sendBroadcast(intent);
+        sendBroadcast(intent); //发送这个通知
     }
 
-    public static void startSync(Activity activity) {
+    public static void startSync(Activity activity) {//执行一个service，service的内容里的同步动作就是开始同步
         GTaskManager.getInstance().setActivityContext(activity);
         Intent intent = new Intent(activity, GTaskSyncService.class);
         intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_START_SYNC);
         activity.startService(intent);
     }
 
-    public static void cancelSync(Context context) {
+    public static void cancelSync(Context context) {//执行一个service，service的内容里的同步动作就是取消同步
         Intent intent = new Intent(context, GTaskSyncService.class);
         intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_CANCEL_SYNC);
         context.startService(intent);