Skip to content

Improve ReviewRemindersDatabase docstrings #18827

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
david-allison merged 1 commit into from
Jul 11, 2025
Merged

Improve ReviewRemindersDatabase docstrings #18827

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 25 additions & 25 deletions AnkiDroid/src/main/java/com/ichi2/anki/reviewreminders/ReviewRemindersDatabase.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,23 +56,23 @@ class ReviewRemindersDatabase {
/**
* Decode an encoded HashMap<[ReviewReminderId], [ReviewReminder]> JSON string.
* @see Json.decodeFromString
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
* @throws SerializationException If the stored string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded reminders map is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
*/
private fun decodeJson(jsonString: String): HashMap<ReviewReminderId, ReviewReminder> =
Json.decodeFromString<HashMap<ReviewReminderId, ReviewReminder>>(jsonString)

/**
* Encode a Map<[ReviewReminderId], [ReviewReminder]> as a JSON string.
* @see Json.encodeToString
* @throws SerializationException If the string is not a valid JSON string.
* @throws SerializationException If the stored string is somehow not a valid JSON string, even though the input parameter is type-checked.
*/
private fun encodeJson(reminders: Map<ReviewReminderId, ReviewReminder>): String = Json.encodeToString(reminders)

/**
* Get the [ReviewReminder]s for a specific key.
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
* @throws SerializationException If the value associated with this key is not valid JSON string.
* @throws IllegalArgumentException If the decoded reminders map is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
*/
private fun getRemindersForKey(key: String): HashMap<ReviewReminderId, ReviewReminder> {
val jsonString = AnkiDroidApp.sharedPrefs().getString(key, null) ?: return hashMapOf()
Expand All @@ -81,22 +81,22 @@ class ReviewRemindersDatabase {

/**
* Get the [ReviewReminder]s for a specific deck.
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
* @throws SerializationException If the reminders map has not been stored in SharedPreferences as a valid JSON string.
* @throws IllegalArgumentException If the decoded reminders map is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
*/
fun getRemindersForDeck(did: DeckId): HashMap<ReviewReminderId, ReviewReminder> = getRemindersForKey(DECK_SPECIFIC_KEY + did)

/**
* Get the app-wide [ReviewReminder]s.
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
* @throws SerializationException If the reminders map has not been stored in SharedPreferences as a valid JSON string.
* @throws IllegalArgumentException If the decoded reminders map is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
*/
fun getAllAppWideReminders(): HashMap<ReviewReminderId, ReviewReminder> = getRemindersForKey(APP_WIDE_KEY)

/**
* Get all [ReviewReminder]s that are associated with a specific deck, grouped by deck ID.
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
* @throws SerializationException If the reminders maps have not been stored in SharedPreferences as valid JSON strings.
* @throws IllegalArgumentException If the decoded reminders maps are not instances of HashMap<[ReviewReminderId], [ReviewReminder]>.
*/
private fun getAllDeckSpecificRemindersGrouped(): Map<DeckId, HashMap<ReviewReminderId, ReviewReminder>> {
return AnkiDroidApp
Expand All @@ -112,17 +112,17 @@ class ReviewRemindersDatabase {

/**
* Get all [ReviewReminder]s that are associated with a specific deck, all in a single flattened map.
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
* @throws SerializationException If the reminders maps have not been stored in SharedPreferences as valid JSON strings.
* @throws IllegalArgumentException If the decoded reminders maps are not instances of HashMap<[ReviewReminderId], [ReviewReminder]>.
*/
fun getAllDeckSpecificReminders(): HashMap<ReviewReminderId, ReviewReminder> = getAllDeckSpecificRemindersGrouped().flatten()

/**
* Edit the [ReviewReminder]s for a specific key.
* @param key
* @param reminderEditor A lambda that takes the current map and returns the updated map.
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
* @throws SerializationException If the current reminders map has not been stored in SharedPreferences as a valid JSON string.
* @throws IllegalArgumentException If the decoded current reminders map is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
*/
private fun editRemindersForKey(
key: String,
Expand All @@ -140,8 +140,8 @@ class ReviewRemindersDatabase {
* This assumes the resulting map contains only reminders of scope [ReviewReminderScope.DeckSpecific].
* @param did
* @param reminderEditor A lambda that takes the current map and returns the updated map.
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
* @throws SerializationException If the current reminders map has not been stored in SharedPreferences as a valid JSON string.
* @throws IllegalArgumentException If the decoded current reminders map is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
*/
fun editRemindersForDeck(
did: DeckId,
Expand All @@ -152,8 +152,8 @@ class ReviewRemindersDatabase {
* Edit the app-wide [ReviewReminder]s.
* This assumes the resulting map contains only reminders of scope [ReviewReminderScope.Global].
* @param reminderEditor A lambda that takes the current map and returns the updated map.
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
* @throws SerializationException If the current reminders map has not been stored in SharedPreferences as a valid JSON string.
* @throws IllegalArgumentException If the decoded current reminders map is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
*/
fun editAllAppWideReminders(reminderEditor: (HashMap<ReviewReminderId, ReviewReminder>) -> Map<ReviewReminderId, ReviewReminder>) =
editRemindersForKey(APP_WIDE_KEY, reminderEditor)
Expand All @@ -162,8 +162,8 @@ class ReviewRemindersDatabase {
* Edit all [ReviewReminder]s that are associated with a specific deck by operating on a single mutable map.
* This assumes the resulting map contains only reminders of scope [ReviewReminderScope.DeckSpecific].
* @param reminderEditor A lambda that takes the current map and returns the updated map.
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [ReviewReminder]>.
* @throws SerializationException If the current reminders maps have not been stored in SharedPreferences as valid JSON strings.
* @throws IllegalArgumentException If the decoded current reminders maps are not instances of HashMap<[ReviewReminderId], [ReviewReminder]>.
*/
fun editAllDeckSpecificReminders(reminderEditor: (HashMap<ReviewReminderId, ReviewReminder>) -> Map<ReviewReminderId, ReviewReminder>) {
val existingRemindersGrouped = getAllDeckSpecificRemindersGrouped()
Expand Down Expand Up @@ -211,7 +211,7 @@ class ReviewRemindersDatabase {
/**
* Helper method for getting all SharedPreferences that represent app-wide or deck-specific reminder HashMaps.
* For example, may be used for constructing a backup of all review reminders pending a potentially-destructive migration operation.
* Does not return the next-free-ID preference for review reminders used by [ReviewReminder.getAndIncrementNextFreeReminderId].
* Does not return the next-free-ID preference for review reminders used by [ReviewReminderId.getAndIncrementNextFreeReminderId].
*/
fun getAllReviewReminderSharedPrefsAsMap(): Map<String, Any?> =
AnkiDroidApp.sharedPrefs().all.filter {
Expand All @@ -221,7 +221,7 @@ class ReviewRemindersDatabase {

/**
* Helper method for deleting all SharedPreferences that represent app-wide or deck-specific reminder HashMaps.
* Does not delete the next-free-ID preference for review reminders used by [ReviewReminder.getAndIncrementNextFreeReminderId].
* Does not delete the next-free-ID preference for review reminders used by [ReviewReminderId.getAndIncrementNextFreeReminderId].
*
* For example, may be used when a potentially-destructive operation, like a failed migration, has been applied to all review reminders.
* This method can be used to delete all potentially-corrupted review reminder shared preferences so that backed-up
Expand All @@ -247,8 +247,8 @@ class ReviewRemindersDatabase {
* need to have their data ported to the new schema.
* @param serializer The serializer for the old schema of type [T] implementing [OldReviewReminderSchema]
* @see [OldReviewReminderSchema]
* @throws SerializationException If the string is not a valid JSON string.
* @throws IllegalArgumentException If the decoded object is not a HashMap<[ReviewReminderId], [T]>.
* @throws SerializationException If the current reminders maps have not been stored in SharedPreferences as valid JSON strings.
* @throws IllegalArgumentException If the decoded current reminders maps are not instances of HashMap<[ReviewReminderId], [T]>.
*/
fun <T : OldReviewReminderSchema> attemptSchemaMigration(serializer: KSerializer<T>) {
val mapSerializer = MapSerializer(ReviewReminderId.serializer(), serializer)
Expand Down