data包中类的标注

src/Contact.java

@@ -1,79 +0,0 @@
-/*
- * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net)
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *        http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package net.micode.notes.data;
-
-import android.content.Context;
-import android.database.Cursor;
-import android.provider.ContactsContract.CommonDataKinds.Phone;
-import android.provider.ContactsContract.Data;
-import android.telephony.PhoneNumberUtils;
-import android.util.Log;
-
-import java.util.HashMap;
-
-public class Contact {//联系人
-    //定义了一个静态的HashMap变量sContactCache和一个静态的字符串常量TAG。
-    private static HashMap<String, String> sContactCache;
-    private static final String TAG = "Contact";
-    //定义字符串常量CALLER_ID_SELECTION包含了整个查询的语句，其中使用了安卓提供的一些函数和常量，比如PHONE_NUMBERS_EQUAL函数和Phone.NUMBER常量。
-    //该查询语句作用是从小米设备的联系人数据库中设法获取和指定电话号码匹配的联系人的信息。
-    private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER
-    + ",?) AND " + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'"
-    + " AND " + Data.RAW_CONTACT_ID + " IN "
-            + "(SELECT raw_contact_id "
-            + " FROM phone_lookup"
-            + " WHERE min_match = '+')";
-
-    //定义了一个getContact用来接收context对象和电话号码作为参数，该方法先检查sContactCache中是否已经缓存了号码对应联系人信息，是的话直接返回联系人姓名。
-    //否则就构造一个查询语句，查询成功后将姓名缓存到sContactCache中,返回姓名；失败的话就返回null
-    public static String getContact(Context context, String phoneNumber) {
-        if(sContactCache == null) {
-            sContactCache = new HashMap<String, String>();
-        }
-
-        if(sContactCache.containsKey(phoneNumber)) {
-            return sContactCache.get(phoneNumber);
-        }
-        //将电话号码中的"+"替换为最小匹配的呼叫者ID，以生成新的查询条件。
-        //使用查询条件在联系人数据的URI(Data.CONTENT_URI)上进行查询，查询的结果只包含联系人的显示名称(Phone.DISPLAY_NAME)。
-        String selection = CALLER_ID_SELECTION.replace("+",
-                PhoneNumberUtils.toCallerIDMinMatch(phoneNumber));
-        Cursor cursor = context.getContentResolver().query(
-                Data.CONTENT_URI,
-                new String [] { Phone.DISPLAY_NAME },
-                selection,
-                new String[] { phoneNumber },
-                null);
-
-        //如果查询结果不为空，将第一个结果的显示名称存储在缓存中，并返回该名称；否则，记录日志并返回null。
-        if (cursor != null && cursor.moveToFirst()) {
-            try {
-                String name = cursor.getString(0);
-                sContactCache.put(phoneNumber, name);
-                return name;
-            } catch (IndexOutOfBoundsException e) {
-                Log.e(TAG, " Cursor get string error " + e.toString());
-                return null;
-            } finally {
-                cursor.close();
-            }
-        } else {
-            Log.d(TAG, "No contact matched with number:" + phoneNumber);
-            return null;
-        }
-    }
-}

src/xiaomi/Notes-master/src/net/micode/notes/data/Contact.java

@@ -25,48 +25,77 @@ import android.util.Log;
 
 import java.util.HashMap;
 
-public class Contact {//联系人
-    //定义了一个静态的HashMap变量sContactCache和一个静态的字符串常量TAG。
-    private static HashMap<String, String> sContactCache;
-    private static final String TAG = "Contact";
-    //定义字符串常量CALLER_ID_SELECTION包含了整个查询的语句，其中使用了安卓提供的一些函数和常量，比如PHONE_NUMBERS_EQUAL函数和Phone.NUMBER常量。
-    //该查询语句作用是从小米设备的联系人数据库中设法获取和指定电话号码匹配的联系人的信息。
+/**
+ * @Package:    net.micode.notes.data
+ * @ClassName:  Contact
+ * @Description:
+ * Contact类是一个用于获取联系人信息的工具类，包含有一个方法getContact，通过给定的电话号码来实现获取联系人信息的功能。
+ * 并且使用缓存和错误日志记录功能来提高程序的稳定性和效率。
+ * @Author: Dong Jiaqi
+ * @CreateDate: 12/21/2023 19:31 PM
+ */
+public class Contact {
+
+
+    private static HashMap<String, String> sContactCache;//定义了一个静态的HashMap变量sContactCache
+    private static final String TAG = "Contact";//定义了一个静态的字符串常量TAG
     private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER
     + ",?) AND " + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'"
     + " AND " + Data.RAW_CONTACT_ID + " IN "
             + "(SELECT raw_contact_id "
             + " FROM phone_lookup"
             + " WHERE min_match = '+')";
+    /*
+     *声明了一个字符串常量CALLER_ID_SELECTION,
+     *其中使用了函数调用PHONE_NUMBERS_EQUAL用来匹配电话号码,同时还使用了条件语句限制数据类型为电话号码联系人ID.
+    */
 
-    //定义了一个getContact用来接收context对象和电话号码作为参数，该方法先检查sContactCache中是否已经缓存了号码对应联系人信息，是的话直接返回联系人姓名。
-    //否则就构造一个查询语句，查询成功后将姓名缓存到sContactCache中,返回姓名；失败的话就返回null
+    /**
+     * 该方法定义了一个getContact,通过给定的电话号码实现获取联系人信息的功能。
+     * getContact中有2个输入参数分别是context和phoneNumber,其中前者是一个Context对象,提供了访问应用程序的信息和资源的环境;后者就是给定输入的电话号码
+     * 有3种返回结果，其中返回sContactCache.get(phoneNumber)代表通过sContactCache这一个HashMap对象获取并且返回电话号码对应的联系人的名字
+     * 返回 name则是直接返回联系人的名字;返回 null表示发生了IndexOutOfBoundsException异常；
+     */
     public static String getContact(Context context, String phoneNumber) {
-        if(sContactCache == null) {
+        if(sContactCache == null) {//确保HashMap对象不会空，始终指向一个实例化的HashMap对象
             sContactCache = new HashMap<String, String>();
         }
 
         if(sContactCache.containsKey(phoneNumber)) {
             return sContactCache.get(phoneNumber);
         }
-        //将电话号码中的"+"替换为最小匹配的呼叫者ID，以生成新的查询条件。
-        //使用查询条件在联系人数据的URI(Data.CONTENT_URI)上进行查询，查询的结果只包含联系人的显示名称(Phone.DISPLAY_NAME)。
+
         String selection = CALLER_ID_SELECTION.replace("+",
-                PhoneNumberUtils.toCallerIDMinMatch(phoneNumber));
+                PhoneNumberUtils.toCallerIDMinMatch(phoneNumber)); //获取电话号码的最小匹配形式，比如字母换数字，然后用replace方发将CALLER_ID_SELECTION中的"+"替换为最小匹配后的电话号码
         Cursor cursor = context.getContentResolver().query(
                 Data.CONTENT_URI,
                 new String [] { Phone.DISPLAY_NAME },
                 selection,
                 new String[] { phoneNumber },
                 null);
+        /*
+         *context.getContentResolver()获取应用的内容解析器对象，然后调用query()方法进行查询，
+         *接受了Data.CONTENT_URI等参数，其中Data.CONTENT_URI表示联系人数据的URI；
+         *new String []{Phone.DISPLAY_NAME}表示联系人的显示名称；
+         *selection表示查询的条件；
+         *new String[] {phoneNumber}表示替换前的原始电话号码，也是查询的参数；
+         *null表示没有排序方式
+         */
 
-        //如果查询结果不为空，将第一个结果的显示名称存储在缓存中，并返回该名称；否则，记录日志并返回null。
+        //如果查询结果不为空，将第一个结果的显示名称存储在缓存中，并返回该名称；否则，记录到错误日志并返回null。
         if (cursor != null && cursor.moveToFirst()) {
+            /*
+             * 语句块功能：是尝试获取联系人的名称，并且存储在name变量中，再将电话号码和对应联系人名字放到sContactCache缓存中去
+             * 如果获取失败，发生IndexOutOfBoundsException报错，那么把错误信息按照错误级别写进日志，有利于debug的进行。
+             * 为什么：通过使用缓存和try-catch-finally语句块，可以确保在获取联系人姓名时不会因为异常而导致程序崩溃，并且在结束查询后及时释放资源，提高了程序的稳定性和效率。
+             * 同时错误信息被写进日志文件，可以有助于开发人员调试和故障排除时找到问题所在。
+             */
             try {
                 String name = cursor.getString(0);
                 sContactCache.put(phoneNumber, name);
                 return name;
             } catch (IndexOutOfBoundsException e) {
-                Log.e(TAG, " Cursor get string error " + e.toString());
+                Log.e(TAG, " Cursor get string error " + e.toString());//调用Log.e()方法，把错误信息写到日志。
                 return null;
             } finally {
                 cursor.close();

src/xiaomi/Notes-master/src/net/micode/notes/data/Notes.java

@@ -17,6 +17,18 @@
 package net.micode.notes.data;
 
 import android.net.Uri;
+/**
+ * @Package:    net.micode.notes.data
+ * @ClassName:  Notes
+ * @Description:
+ * Notes类是一个笔记应用的数据类，用于定义笔记和文件夹的属性和操作。它包括一些常量定义、URI定义和接口定义，以及文本笔记和通话记录笔记的数据列定义。
+ * 在这个类中，定义了一些常量用来标记；
+ * 还定义了一些 常量，用于传递数据。
+ * 以及一些数据列的定义，包括笔记和文件夹的 ID、创建日期、修改日期、提醒日期、内容摘要、小部件 ID、小部件类型、背景颜色ID等。
+ * 这个类的功能是定义了笔记应用中笔记和文件夹的数据结构，并提供了相关的常量、URI 和接口定义，以及文本笔记和通话记录笔记的数据列定义，方便应用程序对这些数据进行操作和管理。
+ * @Author: Dong Jiaqi
+ * @CreateDate: 12/22/2023 0:53 AM
+ */
 public class Notes {
     public static final String AUTHORITY = "micode_notes";
     public static final String TAG = "Notes";
@@ -46,6 +58,7 @@ public class Notes {
     public static final int TYPE_WIDGET_2X            = 0;
     public static final int TYPE_WIDGET_4X            = 1;
 
+    //定义了一个静态内部类DataConstants，包含2个变量NOTE和CALL_NOTE，前者用于表示数据类型为文本笔记类型；后者用于表示数据类型为通话类型
     public static class DataConstants {
         public static final String NOTE = TextNote.CONTENT_ITEM_TYPE;
         public static final String CALL_NOTE = CallNote.CONTENT_ITEM_TYPE;
@@ -61,6 +74,10 @@ public class Notes {
      */
     public static final Uri CONTENT_DATA_URI = Uri.parse("content://" + AUTHORITY + "/data");
 
+    /**
+     * 定义了一个接口NoteColumns，其中包含一些用于表示数据库中笔记，文件夹各种属性的常量。
+     * 通过使用这些常量，可以方便地访问和操作数据库中的笔记或者文件夹得各个属性
+     */
     public interface NoteColumns {
         /**
          * The unique ID for a row
@@ -167,6 +184,10 @@ public class Notes {
         public static final String VERSION = "version";
     }
 
+    /**
+     * 定义了一个接口DataColumns，其中包含了一些用来表示笔记和文件及的数据列的常量
+     * 这些常量可以用于在应用程序当中访问和操作笔记和文件夹的相关数据。通过使用这些常量，我们可以方便地获取和更新笔记当中的信息和数据列。
+     */
     public interface DataColumns {
         /**
          * The unique ID for a row
@@ -241,28 +262,34 @@ public class Notes {
         public static final String DATA5 = "data5";
     }
 
+    /**
+     * TextNote是一个静态内部类，实现了接口DataColumns，定义了一些常量和方法来表示文本笔记的属性和操作
+     */
     public static final class TextNote implements DataColumns {
         /**
          * Mode to indicate the text in check list mode or not
          * <P> Type: Integer 1:check list mode 0: normal mode </P>
          */
-        public static final String MODE = DATA1;
+        public static final String MODE = DATA1;//表示文本笔记的模式，用来指示是否处于检查模式当中，值为1表示检查模式，为0表示普通模式
 
-        public static final int MODE_CHECK_LIST = 1;
+        public static final int MODE_CHECK_LIST = 1;//表示检查列表模式的常量值。
 
         public static final String CONTENT_TYPE = "vnd.android.cursor.dir/text_note";
 
         public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/text_note";
 
-        public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/text_note");
+        public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/text_note");//表示文本笔记的内容URI，用来访问和操作笔记中的数，值是两者拼合成的URI
     }
 
+    /**
+     * CallNote是一个静态内部类，实现了接口DataColumns，定义了一些常量和方法来表示通话笔记的属性和操作
+     */
     public static final class CallNote implements DataColumns {
         /**
          * Call date for this record
          * <P> Type: INTEGER (long) </P>
          */
-        public static final String CALL_DATE = DATA1;
+        public static final String CALL_DATE = DATA1;//表示通话笔记的通话日期
 
         /**
          * Phone number for this record

src/xiaomi/Notes-master/src/net/micode/notes/data/NotesDatabaseHelper.java

@@ -26,7 +26,17 @@ import net.micode.notes.data.Notes.DataColumns;
 import net.micode.notes.data.Notes.DataConstants;
 import net.micode.notes.data.Notes.NoteColumns;
 
-
+/**
+ * @Package: net.micode.notes.data
+ * @ClassName: NotesDatabaseHelper
+ * @Description:
+ * 这是一个用于管理小米便签的数据库类NotesDatabaseHelper,这个类继承自SQLiteOpenHelper
+ * ,用于创建和管理小米便签所需要用到的数据库以及表结构。
+ * 类当中包含了5大部分，分别是常量的定义，表结构的创建，触发器的创建，系统文件夹创建以及数据库表的创建
+ * 该类是整个小米便签软件中用于数据库管理的核心类。
+ * @Author: Dong Jiaqi
+ * @CreateDate: 12/23/2023 0:44 AM
+ */
 public class NotesDatabaseHelper extends SQLiteOpenHelper {
     private static final String DB_NAME = "note.db";
 
@@ -61,7 +71,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
             NoteColumns.ORIGIN_PARENT_ID + " INTEGER NOT NULL DEFAULT 0," +
             NoteColumns.GTASK_ID + " TEXT NOT NULL DEFAULT ''," +
             NoteColumns.VERSION + " INTEGER NOT NULL DEFAULT 0" +
-        ")";
+        ")";//这是用于创建便签表的SQL语句，定义了便签表的结构，包含便签各种属性和字段，存储了用户创建的所有便签的信息。
 
     private static final String CREATE_DATA_TABLE_SQL =
         "CREATE TABLE " + TABLE.DATA + "(" +
@@ -76,14 +86,14 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
             DataColumns.DATA3 + " TEXT NOT NULL DEFAULT ''," +
             DataColumns.DATA4 + " TEXT NOT NULL DEFAULT ''," +
             DataColumns.DATA5 + " TEXT NOT NULL DEFAULT ''" +
-        ")";
+        ")";//这是用于定义数据表结构的SQL语句，存储了与便签相关的数据信息，包括了各种附加数据，用来扩展便签功能。
 
     private static final String CREATE_DATA_NOTE_ID_INDEX_SQL =
         "CREATE INDEX IF NOT EXISTS note_id_index ON " +
         TABLE.DATA + "(" + DataColumns.NOTE_ID + ");";
 
     /**
-     * Increase folder's note count when move note to the folder
+     * 当将便签移动到文件夹时，通过增加文件夹的便签数量来实现
      */
     private static final String NOTE_INCREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER =
         "CREATE TRIGGER increase_folder_count_on_update "+
@@ -95,7 +105,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         " END";
 
     /**
-     * Decrease folder's note count when move note from folder
+     * 将便签从文件夹中移出时，通过减少文件夹的便签数量来实现
      */
     private static final String NOTE_DECREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER =
         "CREATE TRIGGER decrease_folder_count_on_update " +
@@ -108,7 +118,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         " END";
 
     /**
-     * Increase folder's note count when insert new note to the folder
+     * 当向文件夹中插入新的便签时，通过增加文件夹的便签数量来实现
      */
     private static final String NOTE_INCREASE_FOLDER_COUNT_ON_INSERT_TRIGGER =
         "CREATE TRIGGER increase_folder_count_on_insert " +
@@ -120,7 +130,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         " END";
 
     /**
-     * Decrease folder's note count when delete note from the folder
+     * 当从文件夹中删除便签时，通过减少文件夹的便签数量来实现
      */
     private static final String NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER =
         "CREATE TRIGGER decrease_folder_count_on_delete " +
@@ -133,7 +143,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         " END";
 
     /**
-     * Update note's content when insert data with type {@link DataConstants#NOTE}
+     * 当插入新的数据类型时，需要更新便签的内容{@link DataConstants#NOTE}
      */
     private static final String DATA_UPDATE_NOTE_CONTENT_ON_INSERT_TRIGGER =
         "CREATE TRIGGER update_note_content_on_insert " +
@@ -172,7 +182,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         " END";
 
     /**
-     * Delete datas belong to note which has been deleted
+     * 删除已经被删除的便签所关联的数据
      */
     private static final String NOTE_DELETE_DATA_ON_DELETE_TRIGGER =
         "CREATE TRIGGER delete_data_on_delete " +
@@ -183,7 +193,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         " END";
 
     /**
-     * Delete notes belong to folder which has been deleted
+     * 删除已经被删除的文件夹所包含的便签
      */
     private static final String FOLDER_DELETE_NOTES_ON_DELETE_TRIGGER =
         "CREATE TRIGGER folder_delete_notes_on_delete " +
@@ -194,7 +204,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         " END";
 
     /**
-     * Move notes belong to folder which has been moved to trash folder
+     * 将已经被移动到回收站文件夹的文件夹中的便签也一并移动到回收站文件夹
      */
     private static final String FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER =
         "CREATE TRIGGER folder_move_notes_on_trash " +
@@ -210,6 +220,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         super(context, DB_NAME, null, DB_VERSION);
     }
 
+    /**
+     * 创建便签表、重新创建触发器并创建系统文件夹
+     * @param： 一个SQLiteDatabase对象db，表示要创建便签的数据库
+     */
     public void createNoteTable(SQLiteDatabase db) {
         db.execSQL(CREATE_NOTE_TABLE_SQL);
         reCreateNoteTableTriggers(db);
@@ -217,6 +231,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         Log.d(TAG, "note table has been created");
     }
 
+    /**
+     * 重新创建和便签表相关的触发器，会在数据库中对触发器进行设置，以便在特定操作时自动执行相应的处理过程。
+     * @param： db
+     */
     private void reCreateNoteTableTriggers(SQLiteDatabase db) {
         db.execSQL("DROP TRIGGER IF EXISTS increase_folder_count_on_update");
         db.execSQL("DROP TRIGGER IF EXISTS decrease_folder_count_on_update");
@@ -235,6 +253,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.execSQL(FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER);
     }
 
+    /**
+     * 初始化数据库中的系统文件夹，确保在数据库中存在且具有特定的属性和类型标识。
+     * @param： db
+     */
     private void createSystemFolder(SQLiteDatabase db) {
         ContentValues values = new ContentValues();
 
@@ -277,6 +299,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         Log.d(TAG, "data table has been created");
     }
 
+    /**
+     * 重新创建一个和数据表相关的触发器，先删除3个已经存在的触发器，再一次创建3个新的触发器
+     * @param db
+     */
     private void reCreateDataTableTriggers(SQLiteDatabase db) {
         db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_insert");
         db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_update");
@@ -287,6 +313,15 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER);
     }
 
+    /**
+     * 这个方法确保了在整个应用程序当中只创建了一个NotesDatabaseHelper实例
+     * 并且提供了一个全局访问点，让其他部分可以方便地获取该实例并且使用数据库功能，提供了对数据库的统一管理和访问
+     * @param context  Context是一个表示当前应用程序的环境的类，包含了应用程序全局信息。
+     *                在这个方法中,Context context参数用于创建NoteDatabaseHelper实例时所需的环境信息，
+     *                 传入参数确保正确地获取了应用程序的环境信息。
+     * @return mInstance是一个实例，如果为null表示还没有创建这个类的实例，会创建一个新的实例并且赋值给它。
+     * 无论是新建的实例或者是已经存在的实例按照mInstance返回。避免了多个实例的创建和内存的浪费。
+     */
     static synchronized NotesDatabaseHelper getInstance(Context context) {
         if (mInstance == null) {
             mInstance = new NotesDatabaseHelper(context);
@@ -300,11 +335,21 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         createDataTable(db);
     }
 
+    /**
+     * 这个方法的功能是根据新旧版本号,依次来执行相应的数据库升级操作,从而确保数据库的结构和内容能够与新版本要求相匹配。
+     * @param db 表示要升级的数据库对象
+     * @param oldVersion 表示当前数据库的旧版本号
+     * @param newVersion 表示需要升级到的新版本号
+     */
     @Override
     public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
         boolean reCreateTriggers = false;
         boolean skipV2 = false;
 
+        /**
+         * 该语句块是一个数据库升级的逻辑处理，它的功能是按照旧版本号和新版本号的要求执行相应的数据库升级操作，并进行相关的标记和检查。
+         * 这个语句块的目的是实现数据库版本升级，通过这样的逻辑判断，可以保证数据库的顺序升级，并在每个升级阶段进行必要的操作和标记，以确保升级的正确性和完整性。
+         */
         if (oldVersion == 1) {
             upgradeToV2(db);
             skipV2 = true; // this upgrade including the upgrade from v2 to v3