撰写注释

src/app/src/main/java/net/micode/notes/data/Contact.java

@@ -25,10 +25,24 @@ import android.util.Log;
 
 import java.util.HashMap;
 
+/**
+ *联系人类，主要用于获取电话号码对应的联系人姓名
+ */
 public class Contact {
+
+    /**
+     * 声明了一个静态变量sContactCache，用于缓存联系人信息
+     */
     private static HashMap<String, String> sContactCache;
+
+    /**
+     * 声明了一个静态常量TAG，用于在日志中标识该类名。
+     */
     private static final String TAG = "Contact";
 
+    /**
+    定义了一个SQL查询字符串，用于查询满足指定条件的联系人信息。
+     */
     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 "
@@ -36,6 +50,12 @@ public class Contact {
             + " FROM phone_lookup"
             + " WHERE min_match = '+')";
 
+    /**
+     * 公共方法，用于获取给定电话号码所对应联系人的姓名。
+     * @param context
+     * @param phoneNumber
+     * @return
+     */
     public static String getContact(Context context, String phoneNumber) {
         if(sContactCache == null) {
             sContactCache = new HashMap<String, String>();

src/app/src/main/java/net/micode/notes/data/Notes.java

@@ -18,8 +18,18 @@ package net.micode.notes.data;
 
 import android.net.Uri;
 public class Notes {
+
+    /**
+     * 这是一个静态的字符串常量，表示内容提供者的授权标识。
+     */
     public static final String AUTHORITY = "micode_notes";
+
+    /**
+     * 这是一个静态的字符串常量，用于在日志中标识该类名。
+     */
     public static final String TAG = "Notes";
+
+    //这些静态的整数常量表示不同类型的便签笔记。
     public static final int TYPE_NOTE     = 0;
     public static final int TYPE_FOLDER   = 1;
     public static final int TYPE_SYSTEM   = 2;
@@ -30,11 +40,13 @@ public class Notes {
      * {@link Notes#ID_TEMPARAY_FOLDER } is for notes belonging no folder
      * {@link Notes#ID_CALL_RECORD_FOLDER} is to store call records
      */
+    //这些静态的整数常量表示不同类型的系统文件夹的标识符
     public static final int ID_ROOT_FOLDER = 0;
     public static final int ID_TEMPARAY_FOLDER = -1;
     public static final int ID_CALL_RECORD_FOLDER = -2;
     public static final int ID_TRASH_FOLER = -3;
 
+    //这些静态的字符串常量表示传递给Intent对象的额外数据的键名。
     public static final String INTENT_EXTRA_ALERT_DATE = "net.micode.notes.alert_date";
     public static final String INTENT_EXTRA_BACKGROUND_ID = "net.micode.notes.background_color_id";
     public static final String INTENT_EXTRA_WIDGET_ID = "net.micode.notes.widget_id";
@@ -42,10 +54,14 @@ public class Notes {
     public static final String INTENT_EXTRA_FOLDER_ID = "net.micode.notes.folder_id";
     public static final String INTENT_EXTRA_CALL_DATE = "net.micode.notes.call_date";
 
+    //这些静态的整数常量表示小部件的类型。
     public static final int TYPE_WIDGET_INVALIDE      = -1;
     public static final int TYPE_WIDGET_2X            = 0;
     public static final int TYPE_WIDGET_4X            = 1;
 
+    /**
+     * 这是一个静态的内部类，定义了一些用于数据类型的常量字符串。
+     */
     public static class DataConstants {
         public static final String NOTE = TextNote.CONTENT_ITEM_TYPE;
         public static final String CALL_NOTE = CallNote.CONTENT_ITEM_TYPE;
@@ -53,14 +69,19 @@ public class Notes {
 
     /**
      * Uri to query all notes and folders
+     * 这静态的Uri常量表示查询的基础地址。
      */
     public static final Uri CONTENT_NOTE_URI = Uri.parse("content://" + AUTHORITY + "/note");
 
     /**
      * Uri to query data
+     * 这静态的Uri常量表示查询的基础地址。
      */
     public static final Uri CONTENT_DATA_URI = Uri.parse("content://" + AUTHORITY + "/data");
 
+    /**
+     * 标准接口，声明了列名。
+     */
     public interface NoteColumns {
         /**
          * The unique ID for a row
@@ -167,6 +188,9 @@ public class Notes {
         public static final String VERSION = "version";
     }
 
+    /**
+     * 这些是标准接口，声明了数据类型。
+     */
     public interface DataColumns {
         /**
          * The unique ID for a row
@@ -241,6 +265,9 @@ public class Notes {
         public static final String DATA5 = "data5";
     }
 
+    /**
+     * 这个静态的内部类扩展了DataColumns接口，表示不同类型的便签笔记。包含一些额外的列。
+     */
     public static final class TextNote implements DataColumns {
         /**
          * Mode to indicate the text in check list mode or not
@@ -257,6 +284,9 @@ public class Notes {
         public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/text_note");
     }
 
+    /**
+     * 这个静态的内部类扩展了DataColumns接口，表示不同类型的便签笔记。包含一些额外的数据类型。
+     */
     public static final class CallNote implements DataColumns {
         /**
          * Call date for this record

src/app/src/main/java/net/micode/notes/data/NotesDatabaseHelper.java

@@ -26,12 +26,17 @@ import net.micode.notes.data.Notes.DataColumns;
 import net.micode.notes.data.Notes.DataConstants;
 import net.micode.notes.data.Notes.NoteColumns;
 
-
+/**
+ * 用于打开、创建和管理Note应用程序的数据库
+ */
 public class NotesDatabaseHelper extends SQLiteOpenHelper {
     private static final String DB_NAME = "note.db";
 
     private static final int DB_VERSION = 4;
 
+    /**
+     * 这是一个接口，内部定义了一个笔记表和一个数据表的表名常量。
+     */
     public interface TABLE {
         public static final String NOTE = "note";
 
@@ -42,6 +47,9 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
 
     private static NotesDatabaseHelper mInstance;
 
+    /**
+     * 该字符串表示用于创建“note”表的SQL语句。该表用于存储笔记的基本信息。
+     */
     private static final String CREATE_NOTE_TABLE_SQL =
         "CREATE TABLE " + TABLE.NOTE + "(" +
             NoteColumns.ID + " INTEGER PRIMARY KEY," +
@@ -63,6 +71,9 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
             NoteColumns.VERSION + " INTEGER NOT NULL DEFAULT 0" +
         ")";
 
+    /**
+     * SQL语句用于创建“data”表的字符串常量
+     */
     private static final String CREATE_DATA_TABLE_SQL =
         "CREATE TABLE " + TABLE.DATA + "(" +
             DataColumns.ID + " INTEGER PRIMARY KEY," +
@@ -78,12 +89,16 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
             DataColumns.DATA5 + " TEXT NOT NULL DEFAULT ''" +
         ")";
 
+    /**
+     * SQL语句在"data"表上创建索引的字符串常量
+     */
     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 "+
@@ -96,6 +111,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
 
     /**
      * 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 " +
@@ -109,6 +125,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
 
     /**
      * Increase folder's note count when insert new note to the folder
+     * 此触发器将在向数据库中添加新的笔记时自动触发。当向某个文件夹添加新的笔记时，此触发器将使该文件夹的“notes_count”值增加 1。
      */
     private static final String NOTE_INCREASE_FOLDER_COUNT_ON_INSERT_TRIGGER =
         "CREATE TRIGGER increase_folder_count_on_insert " +
@@ -121,6 +138,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
 
     /**
      * Decrease folder's note count when delete note from the folder
+     * 此触发器将在从数据库中删除笔记时自动触发。当从某个文件夹删除笔记时，此触发器将使该文件夹的“notes_count”值减少 1。
      */
     private static final String NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER =
         "CREATE TRIGGER decrease_folder_count_on_delete " +
@@ -134,6 +152,8 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
 
     /**
      * Update note's content when insert data with type {@link DataConstants#NOTE}
+     * 此触发器将在向数据库中添加一个数据记录时自动触发。
+     * 当添加类型为“note”的数据记录时，此触发器将更新笔记的“snippet”列，将其设置为新增数据记录的“content”列值。
      */
     private static final String DATA_UPDATE_NOTE_CONTENT_ON_INSERT_TRIGGER =
         "CREATE TRIGGER update_note_content_on_insert " +
@@ -147,6 +167,8 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
 
     /**
      * Update note's content when data with {@link DataConstants#NOTE} type has changed
+     * 此触发器将在数据库中的数据记录被更新时自动触发。
+     * 当更新的数据记录类型为“note”时，此触发器将更新笔记的“snippet”列，将其设置为更新后的数据记录的“content”列的值。
      */
     private static final String DATA_UPDATE_NOTE_CONTENT_ON_UPDATE_TRIGGER =
         "CREATE TRIGGER update_note_content_on_update " +
@@ -160,6 +182,8 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
 
     /**
      * Update note's content when data with {@link DataConstants#NOTE} type has deleted
+     * 此触发器将在从数据库中删除一个数据记录时自动触发。
+     * 当被删除的数据记录类型为“note”时，此触发器将更新笔记的“snippet”列，并将其设置为空字符串。
      */
     private static final String DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER =
         "CREATE TRIGGER update_note_content_on_delete " +
@@ -173,6 +197,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
 
     /**
      * 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 " +
@@ -184,6 +209,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
 
     /**
      * 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 " +
@@ -195,6 +221,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
 
     /**
      * 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 " +
@@ -206,10 +233,20 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         "  WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
         " END";
 
+    /**
+     * 这是 NotesDatabaseHelper 类的构造函数，用于创建数据库，并将数据库名称、版本等参数传递给基类 SQLiteOpenHelper 的构造函数。
+     * @param context
+     */
     public NotesDatabaseHelper(Context context) {
         super(context, DB_NAME, null, DB_VERSION);
     }
 
+    /**
+     * 此方法用于在给定的 SQLiteDatabase 对象上创建“note”表。
+     * 它执行 CREATE_NOTE_TABLE_SQL 常量中指定的 SQL 语句，
+     * 并调用 reCreateNoteTableTriggers 和 createSystemFolder 方法以重置触发器并创建系统文件夹。
+     * @param db
+     */
     public void createNoteTable(SQLiteDatabase db) {
         db.execSQL(CREATE_NOTE_TABLE_SQL);
         reCreateNoteTableTriggers(db);
@@ -217,6 +254,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 +276,12 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.execSQL(FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER);
     }
 
+    /**
+     * 此私有方法用于向数据库中插入四个系统文件夹。
+     * 它通过为每个文件夹创建一个 ContentValues 对象来添加数据，并将其插入名为 "note" 的数据库表中。
+     * 其中，每个文件夹具有唯一的 ID，类型为 TYPE_SYSTEM。
+     * @param db
+     */
     private void createSystemFolder(SQLiteDatabase db) {
         ContentValues values = new ContentValues();
 
@@ -270,6 +317,12 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.insert(TABLE.NOTE, null, values);
     }
 
+    /**
+     * 此方法用于创建数据表。
+     * 它执行 CREATE_DATA_TABLE_SQL 常量中指定的 SQL 语句，并调用 reCreateDataTableTriggers 方法以重置触发器。
+     * 最后，它还创建了 CREATE_DATA_NOTE_ID_INDEX_SQL 常量中指定的 ID 索引。
+     * @param db
+     */
     public void createDataTable(SQLiteDatabase db) {
         db.execSQL(CREATE_DATA_TABLE_SQL);
         reCreateDataTableTriggers(db);
@@ -277,6 +330,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         Log.d(TAG, "data table has been created");
     }
 
+    /**
+     * 用于重置增删改触发器，删除所有现有的触发器，然后重新创建触发器。
+     * @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 +344,12 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER);
     }
 
+    /**
+     * 此方法是 NotesDatabaseHelper 类的静态方法，通过传递上下文对象来获取数据库的实例。
+     * 它将确保在多线程环境中只有一个实例创建。
+     * @param context
+     * @return
+     */
     static synchronized NotesDatabaseHelper getInstance(Context context) {
         if (mInstance == null) {
             mInstance = new NotesDatabaseHelper(context);
@@ -294,12 +357,25 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         return mInstance;
     }
 
+    /**
+     * 数据库被第一次创建时，此方法将调用。
+     * createNoteTable() 和 createDataTable() 两个方法将被调用，用于创建表和触发器。
+     * @param db
+     */
     @Override
     public void onCreate(SQLiteDatabase db) {
         createNoteTable(db);
         createDataTable(db);
     }
 
+    /**
+     * 当数据库需要更新到一个新版本时，此方法将被调用。
+     * 它通过指定旧版本和新版本号来确定进行哪些更新，
+     * 每个更新都会调用 upgradeToV2()、upgradeToV3() 和 upgradeToV4() 方法之一，以升级数据库结构。
+     * @param db
+     * @param oldVersion
+     * @param newVersion
+     */
     @Override
     public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
         boolean reCreateTriggers = false;
@@ -333,6 +409,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         }
     }
 
+    /**
+     * 此方法执行从 v1 升级到 v2 的数据迁移。它首先删除原来的表，然后创建新表，重新建立触发器。
+     * @param db
+     */
     private void upgradeToV2(SQLiteDatabase db) {
         db.execSQL("DROP TABLE IF EXISTS " + TABLE.NOTE);
         db.execSQL("DROP TABLE IF EXISTS " + TABLE.DATA);
@@ -340,6 +420,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         createDataTable(db);
     }
 
+    /**
+     * 此方法执行从 v2 升级到 v3 的数据迁移。
+     * 它删除不再需要的触发器并添加新的 note Gtask Id 列，以便允许在 Google Tasks 中同步任务到笔记应用程序中。
+     * @param db
+     */
     private void upgradeToV3(SQLiteDatabase db) {
         // drop unused triggers
         db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_insert");
@@ -355,6 +440,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
         db.insert(TABLE.NOTE, null, values);
     }
 
+    /**
+     * 此方法执行从 v3 升级到 v4 的数据迁移。它为 notes 表添加了版本号列，以便在后续升级中进行版本验证。
+     * @param db
+     */
     private void upgradeToV4(SQLiteDatabase db) {
         db.execSQL("ALTER TABLE " + TABLE.NOTE + " ADD COLUMN " + NoteColumns.VERSION
                 + " INTEGER NOT NULL DEFAULT 0");

src/app/src/main/java/net/micode/notes/data/NotesProvider.java

@@ -34,14 +34,28 @@ import net.micode.notes.data.Notes.DataColumns;
 import net.micode.notes.data.Notes.NoteColumns;
 import net.micode.notes.data.NotesDatabaseHelper.TABLE;
 
-
+/**
+ * 这个类中的方法可以处理来自应用程序的查询、插入、更新和删除等操作，并通过 UriMatcher 帮助确定请求的类型和内容。
+ * 同时，它还定义了搜索查询结果的格式，并实现了一些自定义的功能，例如笔记的回收站文件夹。
+ */
 public class NotesProvider extends ContentProvider {
+
+    /**
+     * UriMatcher 用于匹配可能的 URI 请求，并将其映射到适当的代码路径。它被声明为静态常量，并在静态块中进行初始化。
+     */
     private static final UriMatcher mMatcher;
 
+    /**
+     * NotesDatabaseHelper 对象用于打开和操作笔记数据库。
+     */
     private NotesDatabaseHelper mHelper;
 
+    /**
+     * 日志标签，用于调试目的。
+     */
     private static final String TAG = "NotesProvider";
 
+    //这几个静态常量是 URIs 返回时的返回值，它们分别对应笔记、单个笔记、数据和单个数据。这些常量被添加到 UriMatcher 中。
     private static final int URI_NOTE            = 1;
     private static final int URI_NOTE_ITEM       = 2;
     private static final int URI_DATA            = 3;
@@ -51,6 +65,10 @@ public class NotesProvider extends ContentProvider {
     private static final int URI_SEARCH_SUGGEST  = 6;
 
     static {
+        /*
+        这些语句将具有特定 URI 模式的请求添加到 UriMatcher 中，
+        例如 "content://com.example.notes/note"，并与与之关联的 UriMatcher 返回值进行映射。
+         */
         mMatcher = new UriMatcher(UriMatcher.NO_MATCH);
         mMatcher.addURI(Notes.AUTHORITY, "note", URI_NOTE);
         mMatcher.addURI(Notes.AUTHORITY, "note/#", URI_NOTE_ITEM);
@@ -64,6 +82,8 @@ public class NotesProvider extends ContentProvider {
     /**
      * x'0A' represents the '\n' character in sqlite. For title and content in the search result,
      * we will trim '\n' and white space in order to show more information.
+     * 用于定义搜索结果的内容，以及笔记的搜索查询SQL。
+     * 它们用于返回包含搜索查询结果的 Cursor 对象，并传递给 CursorAdapter 来填充 ListView 或 RecyclerView。
      */
     private static final String NOTES_SEARCH_PROJECTION = NoteColumns.ID + ","
         + NoteColumns.ID + " AS " + SearchManager.SUGGEST_COLUMN_INTENT_EXTRA_DATA + ","
@@ -73,18 +93,35 @@ public class NotesProvider extends ContentProvider {
         + "'" + Intent.ACTION_VIEW + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_ACTION + ","
         + "'" + Notes.TextNote.CONTENT_TYPE + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA;
 
+    /**
+     * 用于定义搜索结果的内容，以及笔记的搜索查询SQL。
+     * 它们用于返回包含搜索查询结果的 Cursor 对象，并传递给 CursorAdapter 来填充 ListView 或 RecyclerView。
+     */
     private static String NOTES_SNIPPET_SEARCH_QUERY = "SELECT " + NOTES_SEARCH_PROJECTION
         + " FROM " + TABLE.NOTE
         + " WHERE " + NoteColumns.SNIPPET + " LIKE ?"
         + " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER
         + " AND " + NoteColumns.TYPE + "=" + Notes.TYPE_NOTE;
 
+    /**
+     * 在 ContentProvider 被创建之后，此方法将被调用，并且在这个例子中，它会初始化 mHelper 变量和返回 true。
+     * @return
+     */
     @Override
     public boolean onCreate() {
         mHelper = NotesDatabaseHelper.getInstance(getContext());
         return true;
     }
 
+    /**
+     * 这个方法使用传递过来的参数来执行 SQL 查询，并返回一个 Cursor 对象，用于与 Activity 或 Fragment 中的 UI 控件进行交互。
+     * @param uri
+     * @param projection
+     * @param selection
+     * @param selectionArgs
+     * @param sortOrder
+     * @return
+     */
     @Override
     public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
             String sortOrder) {
@@ -147,6 +184,12 @@ public class NotesProvider extends ContentProvider {
         return c;
     }
 
+    /**
+     * 向 ContentProvider 中插入数据。
+     * @param uri
+     * @param values
+     * @return
+     */
     @Override
     public Uri insert(Uri uri, ContentValues values) {
         SQLiteDatabase db = mHelper.getWritableDatabase();
@@ -181,6 +224,13 @@ public class NotesProvider extends ContentProvider {
         return ContentUris.withAppendedId(uri, insertedId);
     }
 
+    /**
+     * 从 ContentProvider 中删除数据。
+     * @param uri
+     * @param selection
+     * @param selectionArgs
+     * @return
+     */
     @Override
     public int delete(Uri uri, String selection, String[] selectionArgs) {
         int count = 0;
@@ -227,6 +277,14 @@ public class NotesProvider extends ContentProvider {
         return count;
     }
 
+    /**
+     * 从 ContentProvider 中更新数据。
+     * @param uri
+     * @param values
+     * @param selection
+     * @param selectionArgs
+     * @return
+     */
     @Override
     public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) {
         int count = 0;
@@ -267,10 +325,21 @@ public class NotesProvider extends ContentProvider {
         return count;
     }
 
+    /**
+     * 将查询字符串转换为 SQL 语句。如果查询字符串为空，则直接返回空字符串。
+     * @param selection
+     * @return
+     */
     private String parseSelection(String selection) {
         return (!TextUtils.isEmpty(selection) ? " AND (" + selection + ')' : "");
     }
 
+    /**
+     * 将笔记的版本号加一。如果 ID 大于 0 或查询字符串不为空，则将更新语句添加到 SQL 语句中。
+     * @param id
+     * @param selection
+     * @param selectionArgs
+     */
     private void increaseNoteVersion(long id, String selection, String[] selectionArgs) {
         StringBuilder sql = new StringBuilder(120);
         sql.append("UPDATE ");

src/app/src/main/java/net/micode/notes/model/Note.java

@@ -33,13 +33,16 @@ import net.micode.notes.data.Notes.TextNote;
 
 import java.util.ArrayList;
 
-
+/**
+ * 要作用是封装了数据操作逻辑，并提供了方便的接口给外部进行调用。
+ */
 public class Note {
     private ContentValues mNoteDiffValues;
     private NoteData mNoteData;
     private static final String TAG = "Note";
     /**
      * Create a new note id for adding a new note to databases
+     * 获取新的笔记 ID
      */
     public static synchronized long getNewNoteId(Context context, long folderId) {
         // Create a new note in the database
@@ -70,36 +73,73 @@ public class Note {
         mNoteData = new NoteData();
     }
 
+    /**
+     * 设置笔记的值。
+     * @param key
+     * @param value
+     */
     public void setNoteValue(String key, String value) {
         mNoteDiffValues.put(key, value);
         mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
         mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
     }
 
+    /**
+     * 设置笔记数据的值。
+     * @param key
+     * @param value
+     */
     public void setTextData(String key, String value) {
         mNoteData.setTextData(key, value);
     }
 
+    /**
+     * 设置笔记数据的ID。
+     * @param id
+     */
     public void setTextDataId(long id) {
         mNoteData.setTextDataId(id);
     }
 
+    /**
+     * 获取笔记数据的ID。
+     * @return
+     */
     public long getTextDataId() {
         return mNoteData.mTextDataId;
     }
 
+    /**
+     * 设置笔记数据的ID。
+     * @param id
+     */
     public void setCallDataId(long id) {
         mNoteData.setCallDataId(id);
     }
 
+    /**
+     * 设置笔记数据的值。
+     * @param key
+     * @param value
+     */
     public void setCallData(String key, String value) {
         mNoteData.setCallData(key, value);
     }
 
+    /**
+     * 返回笔记是否已被本地修改。
+     * @return
+     */
     public boolean isLocalModified() {
         return mNoteDiffValues.size() > 0 || mNoteData.isLocalModified();
     }
 
+    /**
+     * 判断笔记是否需要同步，如果需要则更新笔记到 ContentProvider 中。
+     * @param context
+     * @param noteId
+     * @return
+     */
     public boolean syncNote(Context context, long noteId) {
         if (noteId <= 0) {
             throw new IllegalArgumentException("Wrong note id:" + noteId);
@@ -148,10 +188,18 @@ public class Note {
             mCallDataId = 0;
         }
 
+        /**
+         * 判断笔记数据是否已经被本地修改。
+         * @return
+         */
         boolean isLocalModified() {
             return mTextDataValues.size() > 0 || mCallDataValues.size() > 0;
         }
 
+        /**
+         * 设置文本数据的 ID。
+         * @param id
+         */
         void setTextDataId(long id) {
             if(id <= 0) {
                 throw new IllegalArgumentException("Text data id should larger than 0");
@@ -159,6 +207,10 @@ public class Note {
             mTextDataId = id;
         }
 
+        /**
+         * 设置电话数据的 ID。
+         * @param id
+         */
         void setCallDataId(long id) {
             if (id <= 0) {
                 throw new IllegalArgumentException("Call data id should larger than 0");
@@ -166,18 +218,34 @@ public class Note {
             mCallDataId = id;
         }
 
+        /**
+         * 设置笔记中电话数据的值。
+         * @param key
+         * @param value
+         */
         void setCallData(String key, String value) {
             mCallDataValues.put(key, value);
             mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
             mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
         }
 
+        /**
+         * 设置笔记中文本数据的值。
+         * @param key
+         * @param value
+         */
         void setTextData(String key, String value) {
             mTextDataValues.put(key, value);
             mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
             mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
         }
 
+        /**
+         * 将笔记数据插入 ContentProvider 中，同时更新对应的数据 ID。
+         * @param context
+         * @param noteId
+         * @return
+         */
         Uri pushIntoContentResolver(Context context, long noteId) {
             /**
              * Check for safety

src/app/src/main/java/net/micode/notes/model/WorkingNote.java

@@ -31,7 +31,9 @@ import net.micode.notes.data.Notes.NoteColumns;
 import net.micode.notes.data.Notes.TextNote;
 import net.micode.notes.tool.ResourceParser.NoteBgResources;
 
-
+/**
+ * 它用于代表一条笔记，并提供了一些操作笔记的方法。
+ */
 public class WorkingNote {
     // Note for the working note
     private Note mNote;
@@ -146,6 +148,7 @@ public class WorkingNote {
         loadNoteData();
     }
 
+
     private void loadNoteData() {
         Cursor cursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI, DATA_PROJECTION,
                 DataColumns.NOTE_ID + "=?", new String[] {
@@ -174,6 +177,15 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 创建一个新的空笔记。
+     * @param context
+     * @param folderId
+     * @param widgetId
+     * @param widgetType
+     * @param defaultBgColorId
+     * @return
+     */
     public static WorkingNote createEmptyNote(Context context, long folderId, int widgetId,
             int widgetType, int defaultBgColorId) {
         WorkingNote note = new WorkingNote(context, folderId);
@@ -183,10 +195,20 @@ public class WorkingNote {
         return note;
     }
 
+    /**
+     * 加载指定 Id 的笔记。
+     * @param context
+     * @param id
+     * @return
+     */
     public static WorkingNote load(Context context, long id) {
         return new WorkingNote(context, id, 0);
     }
 
+    /**
+     * 保存当前笔记。
+     * @return
+     */
     public synchronized boolean saveNote() {
         if (isWorthSaving()) {
             if (!existInDatabase()) {
@@ -225,10 +247,19 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 设置笔记设置变化的监听器。
+     * @param l
+     */
     public void setOnSettingStatusChangedListener(NoteSettingChangedListener l) {
         mNoteSettingStatusListener = l;
     }
 
+    /**
+     * 设置闹钟提醒时间。
+     * @param date
+     * @param set
+     */
     public void setAlertDate(long date, boolean set) {
         if (date != mAlertDate) {
             mAlertDate = date;
@@ -239,6 +270,10 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 标记笔记是否被删除。
+     * @param mark
+     */
     public void markDeleted(boolean mark) {
         mIsDeleted = mark;
         if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
@@ -247,6 +282,10 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 设置笔记的背景颜色。
+     * @param id
+     */
     public void setBgColorId(int id) {
         if (id != mBgColorId) {
             mBgColorId = id;
@@ -257,6 +296,10 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 设置笔记的模式。
+     * @param mode
+     */
     public void setCheckListMode(int mode) {
         if (mMode != mode) {
             if (mNoteSettingStatusListener != null) {
@@ -267,6 +310,10 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 设置笔记关联的小部件类型。
+     * @param type
+     */
     public void setWidgetType(int type) {
         if (type != mWidgetType) {
             mWidgetType = type;
@@ -274,6 +321,10 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 设置笔记关联的小部件 Id。
+     * @param id
+     */
     public void setWidgetId(int id) {
         if (id != mWidgetId) {
             mWidgetId = id;
@@ -281,6 +332,10 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 设置笔记的文本内容。
+     * @param text
+     */
     public void setWorkingText(String text) {
         if (!TextUtils.equals(mContent, text)) {
             mContent = text;
@@ -288,12 +343,18 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 将该笔记转化为呼叫记录。
+     * @param phoneNumber
+     * @param callDate
+     */
     public void convertToCallNote(String phoneNumber, long callDate) {
         mNote.setCallData(CallNote.CALL_DATE, String.valueOf(callDate));
         mNote.setCallData(CallNote.PHONE_NUMBER, phoneNumber);
         mNote.setNoteValue(NoteColumns.PARENT_ID, String.valueOf(Notes.ID_CALL_RECORD_FOLDER));
     }
 
+    //一些获取方法
     public boolean hasClockAlert() {
         return (mAlertDate > 0 ? true : false);
     }
@@ -342,24 +403,31 @@ public class WorkingNote {
         return mWidgetType;
     }
 
+    /**
+     * 用于监听笔记设置的变化。
+     */
     public interface NoteSettingChangedListener {
         /**
          * Called when the background color of current note has just changed
+         * 当当前笔记的背景色改变时被调用。
          */
         void onBackgroundColorChanged();
 
         /**
          * Called when user set clock
+         * 当闹钟提醒设置改变时被调用，参数 date 表示提醒时间，set 表示是否设置了提醒。
          */
         void onClockAlertChanged(long date, boolean set);
 
         /**
          * Call when user create note from widget
+         * 当用户从小部件创建新笔记时被调用。
          */
         void onWidgetChanged();
 
         /**
          * Call when switch between check list mode and normal mode
+         * 当切换到检查列表模式或常规模式时被调用，参数 oldMode 表示变化前的模式，newMode 表示新的模式。
          * @param oldMode is previous mode before change
          * @param newMode is new mode
          */

src/build.gradle

@@ -2,8 +2,8 @@
 
 buildscript {
     repositories {
-        jcenter()
         google()//add
+        jcenter()
     }
     dependencies {
         classpath 'com.android.tools.build:gradle:7.4.2'
@@ -12,7 +12,7 @@ buildscript {
 
 allprojects {
     repositories {
-        jcenter()
         google()//add
+        jcenter()
     }
 }