add some ksdocs

adamff-dev · adamff-dev · commit 0d8164f8f544 · 2025-06-04T14:49:30.000+02:00
diff --git a/app/src/main/java/com/addev/listaspam/MainActivity.kt b/app/src/main/java/com/addev/listaspam/MainActivity.kt
@@ -35,6 +35,7 @@ import com.addev.listaspam.util.getWhitelistNumbers
 import com.addev.listaspam.util.setListaSpamApiLang
 import com.addev.listaspam.util.setTellowsApiCountry
 import java.util.Locale
+import androidx.core.net.toUri
 
 class MainActivity : AppCompatActivity(), CallLogAdapter.OnItemChangedListener {
 
@@ -82,13 +83,13 @@ class MainActivity : AppCompatActivity(), CallLogAdapter.OnItemChangedListener {
             }
 
             R.id.action_about -> {
-                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(ABOUT_LINK))
+                val intent = Intent(Intent.ACTION_VIEW, ABOUT_LINK.toUri())
                 this.startActivity(intent)
                 true
             }
 
             R.id.donate -> {
-                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(DONATE_LINK))
+                val intent = Intent(Intent.ACTION_VIEW, DONATE_LINK.toUri())
                 this.startActivity(intent)
                 true
             }
@@ -140,7 +141,7 @@ class MainActivity : AppCompatActivity(), CallLogAdapter.OnItemChangedListener {
         builder.setTitle(getString(R.string.test_number))
 
         val input = EditText(this)
-        input.inputType = InputType.TYPE_CLASS_PHONE // Para números telefónicos
+        input.inputType = InputType.TYPE_CLASS_PHONE
         builder.setView(input)
 
         builder.setPositiveButton(getString(R.string.aceptar)) { dialog, _ ->
@@ -236,6 +237,21 @@ class MainActivity : AppCompatActivity(), CallLogAdapter.OnItemChangedListener {
         Toast.makeText(context, message, duration).show()
     }
 
+    /**
+     * Checks for necessary permissions and requests them if not granted.
+     *
+     * This function identifies which of the required permissions (READ_CALL_LOG,
+     * READ_PHONE_STATE, READ_CONTACTS, ANSWER_PHONE_CALLS, and POST_NOTIFICATIONS
+     * for Android Tiramisu and above) are not granted.
+     *
+     * It then differentiates between permissions that haven't been requested yet
+     * (missingPermissions) and those that have been denied by the user previously
+     * (deniedPermissions).
+     *
+     * For missing permissions, it directly requests them using `ActivityCompat.requestPermissions`.
+     * For denied permissions, it calls `showPermissionToastAndRequest` to inform the user
+     * and guide them to settings.
+     */
     private fun checkPermissionsAndRequest() {
         val permissions = mutableListOf(
             Manifest.permission.READ_CALL_LOG,
@@ -273,7 +289,6 @@ class MainActivity : AppCompatActivity(), CallLogAdapter.OnItemChangedListener {
      *
      * @param missingPermissions a list of permissions that are missing.
      */
-
     private fun showPermissionToastAndRequest(missingPermissions: List<String>) {
         val permissionNames = missingPermissions.map { "• " + getPermissionName(it) }
         val message =
@@ -300,6 +315,12 @@ class MainActivity : AppCompatActivity(), CallLogAdapter.OnItemChangedListener {
         permissionDeniedDialog?.show()
     }
 
+    /**
+     * Returns the human-readable name for a given permission string.
+     *
+     * @param permission The permission string (e.g., Manifest.permission.READ_CALL_LOG).
+     * @return The human-readable name of the permission, or the original permission string if no mapping is found.
+     */
     private fun getPermissionName(permission: String): String {
         return when (permission) {
             Manifest.permission.READ_CALL_LOG -> getString(R.string.permission_read_call_log)
diff --git a/app/src/main/java/com/addev/listaspam/SettingsActivity.kt b/app/src/main/java/com/addev/listaspam/SettingsActivity.kt
@@ -7,6 +7,7 @@ import android.widget.Button
 import android.widget.Toast
 import androidx.activity.result.contract.ActivityResultContracts
 import androidx.appcompat.app.AppCompatActivity
+import androidx.core.content.edit
 import androidx.preference.PreferenceFragmentCompat
 import org.json.JSONArray
 import org.json.JSONException
@@ -24,55 +25,119 @@ class SettingsActivity : AppCompatActivity() {
         val importButton: Button = findViewById(R.id.btn_import)
 
         exportButton.setOnClickListener {
-            exportFileLauncher.launch("spam_call_blocker_prefs.json")
+            exportFileLauncher.launch("spam_call_blocker_export.json")
         }
 
         importButton.setOnClickListener {
             importFileLauncher.launch(arrayOf("application/json"))
         }
     }
 
+    /**
+     * Updates the settings container by replacing its content with a new instance of SettingsFragment.
+     * This function is typically called when the activity is created or when settings need to be refreshed,
+     * for example, after importing new settings.
+     */
     private fun updateSettingsContainer() {
         supportFragmentManager
             .beginTransaction()
             .replace(R.id.settings_container, SettingsFragment())
             .commit()
     }
 
-    // Fragmento para cargar las preferencias
+    /**
+     * A [PreferenceFragmentCompat] that displays the application's settings.
+     * It loads preferences from an XML resource file.
+     */
     class SettingsFragment : PreferenceFragmentCompat() {
         override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
             setPreferencesFromResource(R.xml.preferences, rootKey)
         }
     }
 
+    /**
+     * ActivityResultLauncher for creating a document to export SharedPreferences.
+     *
+     * This launcher is used to initiate the system's file picker to select a location
+     * and name for the JSON file where the SharedPreferences data will be exported.
+     *
+     * Upon successful selection of a URI by the user, the [exportAllSharedPreferences]
+     * method is called with the chosen URI. A Toast message is displayed to indicate
+     * the success or failure of the export operation.
+     */
     private val exportFileLauncher =
         registerForActivityResult(ActivityResultContracts.CreateDocument("application/json")) { uri: Uri? ->
             uri?.let {
                 if (exportAllSharedPreferences(it)) {
-                    Toast.makeText(this, "Preferencias exportadas con éxito", Toast.LENGTH_SHORT)
+                    Toast.makeText(
+                        this,
+                        this.getString(R.string.preferences_export_success),
+                        Toast.LENGTH_SHORT
+                    )
                         .show()
                 } else {
-                    Toast.makeText(this, "Error al exportar preferencias", Toast.LENGTH_SHORT)
+                    Toast.makeText(
+                        this,
+                        this.getString(R.string.preferences_export_error),
+                        Toast.LENGTH_SHORT
+                    )
                         .show()
                 }
             }
         }
 
+    /**
+     * ActivityResultLauncher for handling the result of opening a document to import SharedPreferences.
+     * It expects a URI as a result. If a URI is received, it attempts to import
+     * SharedPreferences from the selected file.
+     * Displays a success or error Toast message based on the outcome of the import operation.
+     * After a successful import, it updates the settings container.
+     */
     private val importFileLauncher =
         registerForActivityResult(ActivityResultContracts.OpenDocument()) { uri: Uri? ->
             uri?.let {
                 if (importAllSharedPreferences(it)) {
                     updateSettingsContainer()
-                    Toast.makeText(this, "Preferencias importadas con éxito", Toast.LENGTH_SHORT)
+                    Toast.makeText(
+                        this,
+                        this.getString(R.string.preferences_import_success),
+                        Toast.LENGTH_SHORT
+                    )
                         .show()
                 } else {
-                    Toast.makeText(this, "Error al importar preferencias", Toast.LENGTH_SHORT)
+                    Toast.makeText(
+                        this,
+                        this.getString(R.string.preferences_import_error),
+                        Toast.LENGTH_SHORT
+                    )
                         .show()
                 }
             }
         }
 
+    /**
+     * Exports all SharedPreferences to a JSON file.
+     *
+     * This function iterates through all SharedPreferences files in the application's
+     * `shared_prefs` directory. For each file, it reads all key-value pairs
+     * and constructs a JSON object representing the preferences. These individual
+     * JSON objects are then combined into a single parent JSON object, where each
+     * key is the name of the SharedPreferences file (without the .xml extension)
+     * and the value is the corresponding preferences JSON object.
+     *
+     * The resulting parent JSON object is then written to the `OutputStream`
+     * associated with the provided `Uri`.
+     *
+     * Special handling is implemented for `Set<String>` values, which are
+     * converted to JSONArrays. Other primitive types (Boolean, Int, Long, Float, String)
+     * are directly put into the JSON object.
+     *
+     * @param uri The Uri of the file where the SharedPreferences data will be exported.
+     *            This Uri should be obtained from a file picker (e.g., using
+     *            `ActivityResultContracts.CreateDocument`).
+     * @return `true` if the export was successful, `false` otherwise (e.g., if an
+     *         IOException or JSONException occurs).
+     */
     private fun exportAllSharedPreferences(uri: Uri): Boolean {
         return try {
             val prefsDir = File(applicationInfo.dataDir, "shared_prefs")
@@ -109,6 +174,21 @@ class SettingsActivity : AppCompatActivity() {
         }
     }
 
+    /**
+     * Imports all SharedPreferences from a JSON file specified by the given URI.
+     *
+     * This function reads a JSON file, validates its structure, and then iterates through
+     * each SharedPreferences file represented in the JSON. For each preference file,
+     * it reads the key-value pairs and writes them to the corresponding SharedPreferences
+     * on the device.
+     *
+     * Supported data types for import are: `String`, `Int`, `Long`, `Float`, `Boolean`,
+     * and `Set<String>` (represented as a JSONArray of strings in the JSON).
+     *
+     * @param uri The URI of the JSON file to import SharedPreferences from.
+     * @return `true` if the import was successful, `false` otherwise (e.g., if the file is invalid,
+     *         an I/O error occurs, or a JSON parsing error occurs).
+     */
     private fun importAllSharedPreferences(uri: Uri): Boolean {
         return try {
             contentResolver.openInputStream(uri)?.use { inputStream ->
@@ -117,35 +197,37 @@ class SettingsActivity : AppCompatActivity() {
 
                 // Validar el archivo JSON antes de importar
                 if (!isValidSharedPreferencesJson(jsonObject)) {
-                    Toast.makeText(this, "El archivo JSON no es válido", Toast.LENGTH_SHORT).show()
+                    Toast.makeText(
+                        this,
+                        this.getString(R.string.invalid_json_file),
+                        Toast.LENGTH_SHORT
+                    ).show()
                     return false
                 }
 
                 for (prefName in jsonObject.keys()) {
                     val sharedPreferences = getSharedPreferences(prefName, Context.MODE_PRIVATE)
-                    val editor = sharedPreferences.edit()
-
-                    val prefJsonObject = jsonObject.getJSONObject(prefName)
-                    for (key in prefJsonObject.keys()) {
-                        val value = prefJsonObject.get(key)
-                        when (value) {
-                            is JSONArray -> {
-                                val set = mutableSetOf<String>()
-                                for (i in 0 until value.length()) {
-                                    set.add(value.getString(i))
+                    sharedPreferences.edit {
+
+                        val prefJsonObject = jsonObject.getJSONObject(prefName)
+                        for (key in prefJsonObject.keys()) {
+                            when (val value = prefJsonObject.get(key)) {
+                                is JSONArray -> {
+                                    val set = mutableSetOf<String>()
+                                    for (i in 0 until value.length()) {
+                                        set.add(value.getString(i))
+                                    }
+                                    putStringSet(key, set)
                                 }
-                                editor.putStringSet(key, set)
-                            }
 
-                            is Int -> editor.putInt(key, value)
-                            is Long -> editor.putLong(key, value)
-                            is Float -> editor.putFloat(key, value)
-                            is Boolean -> editor.putBoolean(key, value)
-                            is String -> editor.putString(key, value)
-                            else -> throw IllegalArgumentException("Tipo no soportado")
+                                is Int -> putInt(key, value)
+                                is Long -> putLong(key, value)
+                                is Float -> putFloat(key, value)
+                                is Boolean -> putBoolean(key, value)
+                                is String -> putString(key, value)
+                            }
                         }
                     }
-                    editor.apply()
                 }
             }
             true
@@ -155,6 +237,30 @@ class SettingsActivity : AppCompatActivity() {
         }
     }
 
+    /**
+     * Validates if the given JSONObject represents a valid SharedPreferences structure.
+     *
+     * This function checks if the JSON object conforms to the expected format of
+     * SharedPreferences data. It iterates through each preference file (represented by
+     * a key in the root JSONObject) and then iterates through each key-value pair
+     * within that preference file.
+     *
+     * The validation ensures:
+     * - Each preference file is a JSONObject.
+     * - Values within each preference file are of supported types:
+     *   - Int
+     *   - Long
+     *   - Float
+     *   - Boolean
+     *   - String
+     *   - JSONArray (where all elements are Strings, representing a Set<String>)
+     *
+     * If any part of the JSON structure does not conform to these rules, or if a
+     * JSONException occurs during parsing, the function returns false.
+     *
+     * @param jsonObject The JSONObject to validate.
+     * @return True if the JSONObject is a valid representation of SharedPreferences, false otherwise.
+     */
     private fun isValidSharedPreferencesJson(jsonObject: JSONObject): Boolean {
         return try {
             for (prefName in jsonObject.keys()) {
diff --git a/app/src/main/java/com/addev/listaspam/util/ApiUtils.kt b/app/src/main/java/com/addev/listaspam/util/ApiUtils.kt
@@ -76,8 +76,6 @@ object ApiUtils {
      * @param phone The phone number being reported.
      * @param comment The user comment about the phone number.
      * @param lang The language code (e.g., "ES" for Spanish).
-     * @param username Optional: The username of the person submitting the report.
-     * @param phoneOwner Optional: A string indicating ownership or recipient identity.
      * @return `true` if the report was submitted successfully; `false` otherwise.
      */
     fun reportToUnknownPhone(
@@ -89,7 +87,7 @@ object ApiUtils {
         val optRating = if (isSpam) "1" else "5"
 
         val formBuilder = FormBody.Builder()
-            .add("api_key", "d58d5bdaba8a80b2311957e9e4af885c")
+            .add("api_key", UNKNOWN_PHONE_API_KEY)
             .add("phone", phone)
             .add("_action", "_submit_comment")
             .add("comment", comment)
