Fix Kotlin warnings (related to issue #5996) (#6320)

* refactor: replace unused exception variable with underscore

* refactor: code style fix

* fix: remove unnecessary latLng variable and return null directly

* fix: use explicit true/false instead of isFABsExpanded

* refactor: simplify marker update logic by reducing redundant conditions

* refactor: use data object instead of object

* fix: check placeBindings for null instead of checking each destructured value

* fix: check placeBindings for null instead of checking each destructured value

* docs: fix KDoc for contentUri property by removing incorrect @param tag

* docs: correct @see link in KDoc for showBadgesWithCount

* docs: fix KDoc tag from @property to @param for context in BottomSheetAdapter

* docs: comment out KDoc for disabled method to avoid unresolved @param warning

* docs: fix KDoc for onLongPress by removing invalid @param imageUri

* docs: clean up invalid KDoc tags on property and add docs to isEmpty

* docs: remove invalid @param originalImageCoordinates from findOtherImages KDoc

* docs: fix incorrect @param tag in checkDuplicateImage KDoc

* docs: fix incorrect @param in onLongPress KDoc

* docs: fix invalid @param and @return tags on author property

* docs: fix incorrect @param in provideWikidataMediaInterface KDoc

* docs: fix incorrect @param name in getWikiText KDoc

* docs: escape wikilinks with [[ ]] to avoid KDoc resolution warnings

* docs: fix KDoc by adding missing param descriptions to startActivityWithFlags

* docs: fix KDoc by replacing @param with @property for contentUri

* docs: fix malformed KDoc in startYourself, remove invalid @param line

* docs: remove invalid @param tag in createDialogsAndHandleLocationPermissions

* docs: remove invalid @param tags to @property

* @docs: remove invalid @property tags

* docs: clean up KDoc by removing invalid @param and @return tags

* docs: fix incorrect @param name in removeBlocklisted KDoc

* docs: fix incorrect @param name in checkDuplicateImage KDoc

* docs: fix incorrect @param tag

---------

Co-authored-by: Nicolas Raoul <nicolas.raoul@gmail.com>

app/src/androidTest/java/fr/free/nrw/commons/UploadCancelledTest.kt

@@ -49,7 +49,7 @@ class UploadCancelledTest {
     fun setup() {
         try {
             Intents.init()
-        } catch (ex: IllegalStateException) {
+        } catch (_: IllegalStateException) {
         }
         device.unfreezeRotation()
         device.setOrientationNatural()
@@ -65,7 +65,7 @@ class UploadCancelledTest {
     fun teardown() {
         try {
             Intents.release()
-        } catch (ex: IllegalStateException) {
+        } catch (_: IllegalStateException) {
         }
     }
 

app/src/androidTest/java/fr/free/nrw/commons/UploadTest.kt

@@ -71,7 +71,7 @@ class UploadTest {
     fun setup() {
         try {
             Intents.init()
-        } catch (ex: IllegalStateException) {
+        } catch (_: IllegalStateException) {
         }
         UITestHelper.loginUser()
         UITestHelper.skipWelcome()

app/src/main/java/fr/free/nrw/commons/Media.kt

@@ -28,9 +28,7 @@ class Media constructor(
      */
     var filename: String? = null,
     /**
-     * Gets or sets the file description.
+     * The fallback description of the file, used if no other description is provided.
-     * @return file description as a string
-     * @param fallbackDescription the new description of the file
      */
     var fallbackDescription: String? = null,
     /**
@@ -40,19 +38,24 @@ class Media constructor(
      */
     var dateUploaded: Date? = null,
     /**
-     * Gets or sets the license name of the file.
+     * The license name of the file.
-     * @return license as a String
-     * @param license license name as a String
      */
     var license: String? = null,
+    /**
+     * The URL corresponding to the license.
+     */
     var licenseUrl: String? = null,
     /**
-     * Gets or sets the name of the creator of the file.
+     * The name of the creator of the file.
-     * @return author name as a String
-     * @param author creator name as a string
      */
     var author: String? = null,
+    /**
+     * The username of the uploader.
+     */
     var user: String? = null,
+    /**
+     * The full name of the file's creator, if different from username.
+     */
     var creatorName: String? = null,
     /**
      * Gets the categories the file falls under.

app/src/main/java/fr/free/nrw/commons/actions/PageEditInterface.kt

@@ -129,9 +129,10 @@ interface PageEditInterface {
     ): Observable<Entities>
 
     /**
-     * Get wiki text for provided file names
+     * Gets the wiki text for the provided file name.
-     * @param titles : Name of the file
+     *
-     * @return Single<MwQueryResult>
+     * @param title The title (name) of the file to fetch wiki text for.
+     * @return A Single emitting the wiki query response.
      */
     @GET(MW_API_PREFIX + "action=query&prop=revisions&rvprop=content|timestamp&rvlimit=1&converttitles=")
     fun getWikiText(

app/src/main/java/fr/free/nrw/commons/bookmarks/models/Bookmark.kt

@@ -8,7 +8,7 @@ class Bookmark(
     /**
      * Gets or Sets the content URI - marking this bookmark as already saved in the database
      * @return content URI
-     * @param contentUri the content URI
+     * contentUri the content URI
      */
     var contentUri: Uri?,
 ) {

app/src/main/java/fr/free/nrw/commons/concurrency/ExceptionAwareThreadPoolExecutor.kt

@@ -22,9 +22,9 @@ class ExceptionAwareThreadPoolExecutor(
                 if (r.isDone) {
                     r.get()
                 }
-            } catch (e: CancellationException) {
+            } catch (_: CancellationException) {
                 // ignore
-            } catch (e: InterruptedException) {
+            } catch (_: InterruptedException) {
                 // ignore
             } catch (e: ExecutionException) {
                 throwable = e.cause ?: e

app/src/main/java/fr/free/nrw/commons/contributions/ContributionsFragment.kt

@@ -808,10 +808,11 @@ class ContributionsFragment : CommonsDaggerSupportFragment(), FragmentManager.On
         }
     }
 
-    /**
+    // /**
-     * Temporarily disabled, see issue [https://github.com/commons-app/apps-android-commons/issues/5847]
+    //  * Temporarily disabled. See issue [#5847](https://github.com/commons-app/apps-android-commons/issues/5847)
-     * @param count The number of pending uploads.
+    //  * @param count The number of pending uploads.
-     */
+    //  */
+    // public void updateUploadIcon(int count) {
     //    public void updateUploadIcon(int count) {
     //        if (pendingUploadsImageView != null) {
     //            if (count != 0) {

app/src/main/java/fr/free/nrw/commons/customselector/listeners/ImageSelectListener.kt

@@ -17,8 +17,11 @@ interface ImageSelectListener {
     )
 
     /**
-     * onLongPress
+     * Called when the user performs a long press on an image.
-     * @param imageUri : uri of image
+     *
+     * @param position The index of the pressed image in the list.
+     * @param images The list of all available images.
+     * @param selectedImages The currently selected images.
      */
     fun onLongPress(
         position: Int,

app/src/main/java/fr/free/nrw/commons/customselector/model/CallbackStatus.kt

@@ -8,15 +8,15 @@ sealed class CallbackStatus {
     /**
      IDLE : The callback is idle , doing nothing.
      */
-    object IDLE : CallbackStatus()
+    data object IDLE : CallbackStatus()
 
     /**
      FETCHING : Fetching images.
      */
-    object FETCHING : CallbackStatus()
+    data object FETCHING : CallbackStatus()
 
     /**
      SUCCESS : Success fetching images.
      */
-    object SUCCESS : CallbackStatus()
+    data object SUCCESS : CallbackStatus()
 }

app/src/main/java/fr/free/nrw/commons/customselector/ui/selector/CustomSelectorActivity.kt

@@ -610,8 +610,11 @@ class CustomSelectorActivity :
     }
 
     /**
-     * onLongPress
+     * Triggered when the user performs a long press on an image.
-     * @param imageUri : uri of image
+     *
+     * @param position The index of the selected image.
+     * @param images The list of all available images.
+     * @param selectedImages The list of images currently selected.
      */
     override fun onLongPress(
         position: Int,

app/src/main/java/fr/free/nrw/commons/customselector/ui/selector/ImageFileLoader.kt

@@ -104,7 +104,8 @@ class ImageFileLoader(
                 if (file != null && file.exists() && name != null && path != null && bucketName != null) {
                     val extension = path.substringAfterLast(".", "")
                     // Check if the extension is one of the allowed types
-                    if (extension.lowercase(Locale.ROOT) !in arrayOf("jpg", "jpeg", "png", "svg", "gif", "tiff", "webp", "xcf")) {
+                    if (extension.lowercase(Locale.ROOT) !in arrayOf("jpg", "jpeg", "png", "svg",
+                            "gif", "tiff", "webp", "xcf")) {
                         continue
                     }
 

app/src/main/java/fr/free/nrw/commons/di/NetworkingModule.kt

@@ -238,10 +238,10 @@ class NetworkingModule {
         factory.create(BuildConfig.COMMONS_URL)
 
     /**
-     * Add provider for WikidataMediaInterface
+     * Provides a Retrofit service for accessing the commons wiki site via [WikidataMediaInterface].
-     * It creates a retrofit service for the commons wiki site
+     *
-     * @param commonsWikiSite commonsWikiSite
+     * @param factory The CommonsServiceFactory used to create the Retrofit service.
-     * @return WikidataMediaInterface
+     * @return An instance of [WikidataMediaInterface].
      */
     @Provides
     @Singleton

app/src/main/java/fr/free/nrw/commons/explore/models/RecentSearch.kt

@@ -9,9 +9,9 @@ import java.util.Date
  */
 class RecentSearch(
     /**
-     * Modifies the content URI - marking this query as already saved in the database
+     * The content URI that marks this query as already saved in the database.
      *
-     * @param contentUri the content URI
+     * @property contentUri the content URI
      */
     var contentUri: Uri?,
     /**

app/src/main/java/fr/free/nrw/commons/mwapi/OkHttpJsonApiClient.kt

@@ -531,7 +531,6 @@ ${"wd:" + place.wikiDataEntityId}"""
         )
         if (placeBindings != null) {
             for ((item1, label, location, clas) in placeBindings) {
-                if (item1 != null && label != null && clas != null) {
                 val input = location.value
                 val pattern = Pattern.compile(
                     "Point\\(([-+]?[0-9]*\\.?[0-9]+) ([-+]?[0-9]*\\.?[0-9]+)\\)"
@@ -567,7 +566,6 @@ ${"wd:" + place.wikiDataEntityId}"""
                 }
             }
         }
-        }
         kmlString = """$kmlString
     </Document>
 </kml>
@@ -589,7 +587,6 @@ ${"wd:" + place.wikiDataEntityId}"""
         val placeBindings = runQuery(leftLatLng, rightLatLng)
         if (placeBindings != null) {
             for ((item1, label, location, clas) in placeBindings) {
-                if (item1 != null && label != null && clas != null) {
                 val input = location.value
                 val pattern = Pattern.compile(
                     "Point\\(([-+]?[0-9]*\\.?[0-9]+) ([-+]?[0-9]*\\.?[0-9]+)\\)"
@@ -622,7 +619,6 @@ ${"wd:" + place.wikiDataEntityId}"""
                 }
             }
         }
-        }
         gpxString = "$gpxString\n</gpx>"
         return gpxString
     }

app/src/main/java/fr/free/nrw/commons/nearby/BottomSheetAdapter.kt

@@ -16,7 +16,7 @@ import fr.free.nrw.commons.nearby.model.BottomSheetItem
 /**
  * RecyclerView Adapter for displaying items in a bottom sheet.
  *
- * @property context The context used for inflating layout resources.
+ * @param context The context used for inflating layout resources.
  * @property itemList The list of BottomSheetItem objects to display.
  * @constructor Creates an instance of BottomSheetAdapter.
  */

app/src/main/java/fr/free/nrw/commons/nearby/fragments/NearbyParentFragment.kt

@@ -63,6 +63,7 @@ import fr.free.nrw.commons.bookmarks.locations.BookmarkLocationsDao
 import fr.free.nrw.commons.contributions.ContributionController
 import fr.free.nrw.commons.contributions.MainActivity
 import fr.free.nrw.commons.contributions.MainActivity.ActiveFragment
+import fr.free.nrw.commons.customselector.ui.selector.ImageLoader
 import fr.free.nrw.commons.databinding.FragmentNearbyParentBinding
 import fr.free.nrw.commons.di.CommonsDaggerSupportFragment
 import fr.free.nrw.commons.filepicker.FilePicker
@@ -1756,9 +1757,9 @@ class NearbyParentFragment : CommonsDaggerSupportFragment(),
     override fun animateFABs() {
         if (binding!!.fabPlus.isShown) {
             if (isFABsExpanded) {
-                collapseFABs(isFABsExpanded)
+                collapseFABs(true)
             } else {
-                expandFABs(isFABsExpanded)
+                expandFABs(false)
             }
         }
     }
@@ -2013,17 +2014,17 @@ class NearbyParentFragment : CommonsDaggerSupportFragment(),
                 if (place.exists && place.pic.trim { it <= ' ' }.isEmpty()) {
                     shouldUpdateMarker = true
                 }
-            } else if (displayExists && !displayNeedsPhoto) {
+            } else if (displayExists) {
                 // Exists and all included needs and doesn't needs photo
                 if (place.exists) {
                     shouldUpdateMarker = true
                 }
-            } else if (!displayExists && displayNeedsPhoto) {
+            } else if (displayNeedsPhoto) {
                 // All and only needs photo
                 if (place.pic.trim { it <= ' ' }.isEmpty()) {
                     shouldUpdateMarker = true
                 }
-            } else if (!displayExists && !displayNeedsPhoto) {
+            } else {
                 // all
                 shouldUpdateMarker = true
             }

app/src/main/java/fr/free/nrw/commons/profile/achievements/AchievementsFragment.kt

@@ -389,7 +389,7 @@ class AchievementsFragment : CommonsDaggerSupportFragment(){
      * @param badgeTextColor The badge text color. Default is R.attr.colorPrimary
      * @param badgeGravity The position of the badge [TOP_END,TOP_START,BOTTOM_END,BOTTOM_START]. Default is TOP_END
      * @return if the number is 0, then it will not create badge for it and hide the view
-     * @see https://developer.android.com/reference/com/google/android/material/badge/BadgeDrawable
+     * @see <a href="https://developer.android.com/reference/com/google/android/material/badge/BadgeDrawable">BadgeDrawable (Android Developer)</a>
      */
 
     private fun showBadgesWithCount(

app/src/main/java/fr/free/nrw/commons/quiz/QuizResultActivity.kt

@@ -93,10 +93,11 @@ class QuizResultActivity : AppCompatActivity() {
     }
 
     /**
-     * Function to call intent to an activity
+     * Starts an activity using the provided context, target class, and intent flags.
-     * @param context
+     *
-     * @param cls
+     * @param context The context used to start the activity.
-     * @param flags
+     * @param cls The target activity class.
+     * @param flags A variable number of intent flags to apply to the Intent.
      */
     companion object {
         fun <T> startActivityWithFlags(context: Context, cls: Class<T>, vararg flags: Int) {

app/src/main/java/fr/free/nrw/commons/repository/UploadRepository.kt

@@ -199,10 +199,11 @@ class UploadRepository @Inject constructor(
     }
 
     /**
-     * Query the RemoteDataSource for image duplicity check
+     * Queries the RemoteDataSource to check if the image is a duplicate.
      *
-     * @param filePath file to be checked
+     * @param originalFilePath The original file to be checked.
-     * @return IMAGE_DUPLICATE or IMAGE_OK
+     * @param modifiedFilePath The modified version of the file (if any).
+     * @return IMAGE_DUPLICATE if the image already exists, otherwise IMAGE_OK.
      */
     fun checkDuplicateImage(originalFilePath: Uri?, modifiedFilePath: Uri?): Single<Int> {
         return uploadModel.checkDuplicateImage(originalFilePath, modifiedFilePath)

app/src/main/java/fr/free/nrw/commons/review/ReviewActivity.kt

@@ -55,10 +55,10 @@ class ReviewActivity : BaseActivity() {
     }
 
     /**
-     * Consumers should be simply using this method to use this activity.
+     * Starts the ReviewActivity.
      *
-     * @param context
+     * @param context The context used to start the activity.
-     * @param title Page title
+     * @param title The page title (currently unused).
      */
     companion object {
         fun startYourself(context: Context, title: String) {

app/src/main/java/fr/free/nrw/commons/settings/SettingsFragment.kt

@@ -276,9 +276,7 @@ class SettingsFragment : PreferenceFragmentCompat() {
     }
 
     /**
-     * Asks users to provide location access
+     * Asks users to provide location access.
-     *
-     * @param activity
      */
     private fun createDialogsAndHandleLocationPermissions() {
         inAppCameraLocationPermissionLauncher.launch(arrayOf(permission.ACCESS_FINE_LOCATION))

app/src/main/java/fr/free/nrw/commons/upload/Description.kt

@@ -6,29 +6,29 @@ package fr.free.nrw.commons.upload
 class Description {
     /**
      * The language code, e.g., "en" or "fr".
-     * @param languageCode The language code.
+     * @property  languageCode The language code.
      */
     var languageCode: String? = null
 
     /**
      * The description text for the item being uploaded.
-     * @param descriptionText The description text.
+     * @property  descriptionText The description text.
      */
     var descriptionText: String? = null
 
     /**
      * The index of the language selected in a spinner with [SpinnerLanguagesAdapter].
-     * @param selectedLanguageIndex The index of the selected language.
+     * @property  selectedLanguageIndex The index of the selected language.
      */
     var selectedLanguageIndex = -1
 
     /**
      * Indicates if the description was added manually (by the user or programmatically).
-     * @param manuallyAdded Sets to true if the description was manually added by the user.
-     * @return True if the description was manually added.
      */
     var isManuallyAdded = false
-
+    /**
+     * Returns true if the description text is null or empty.
+     */
     val isEmpty: Boolean
         get() = descriptionText == null || descriptionText!!.isEmpty()
 

app/src/main/java/fr/free/nrw/commons/upload/FileProcessor.kt

@@ -138,11 +138,10 @@ class FileProcessor
         }
 
     /**
-         * Find other images around the same location that were taken within the last 20 sec
+     * Finds other images around the same location that were taken within a ±120 sec window.
      *
-         * @param originalImageCoordinates
+     * @param fileBeingProcessed The file currently being checked.
-         * @param fileBeingProcessed
+     * @param similarImageInterface Callback to display similar images if any are found.
-         * @param similarImageInterface
      */
         private fun findOtherImages(
             fileBeingProcessed: File,

app/src/main/java/fr/free/nrw/commons/upload/ImageProcessingService.kt

@@ -138,10 +138,10 @@ class ImageProcessingService @Inject constructor(
     }
 
     /**
-     * Checks for duplicate image
+     * Checks for duplicate image by calculating its SHA1 hash and querying the media client.
      *
-     * @param filePath file to be checked
+     * @param inputStream The input stream of the file to check.
-     * @return IMAGE_DUPLICATE or IMAGE_OK
+     * @return IMAGE_DUPLICATE if the file exists, or IMAGE_OK otherwise.
      */
     private fun checkDuplicateImage(inputStream: InputStream): Single<Int> {
         return Single.fromCallable { fileUtilsWrapper.getSHA1(inputStream) }

app/src/main/java/fr/free/nrw/commons/upload/UploadMediaDetail.kt

@@ -10,18 +10,15 @@ import kotlinx.parcelize.Parcelize
 @Parcelize
 data class UploadMediaDetail(
     /**
-     * The language code ie. "en" or "fr".
+     * The language code, e.g., "en" or "fr".
-     * @param languageCode The language code ie. "en" or "fr".
      */
     var languageCode: String? = null,
     /**
      * The description text for the item being uploaded.
-     * @param descriptionText The description text.
      */
     var descriptionText: String? = "",
     /**
      * The caption text for the item being uploaded.
-     * @param captionText The caption text.
      */
     var captionText: String = "",
 ) : Parcelable {
@@ -35,15 +32,11 @@ data class UploadMediaDetail(
 
     /**
      * The index of the language selected in a spinner with [SpinnerLanguagesAdapter].
-     * @return The index of the selected language.
-     * @param selectedLanguageIndex The index of the language selected.
      */
     var selectedLanguageIndex: Int = -1
 
     /**
-     * Returns if the description was added manually (by the user, or programmatically).
+     * Indicates whether the description was added manually (by the user or programmatically).
-     * @return True if the description was manually added.
-     * @param manuallyAdded Sets to true if the description was manually added.
      */
     var isManuallyAdded: Boolean = false
 }

app/src/main/java/fr/free/nrw/commons/upload/UploadMediaDetailInputFilter.kt

@@ -30,9 +30,10 @@ class UploadMediaDetailInputFilter : InputFilter {
         patterns.any { it.matcher(source).find() }
 
     /**
-     * Removes any blocklisted characters from the source text.
+     * Removes any blocklisted characters from the input text.
-     * @param source input text
+     *
-     * @return a cleaned character sequence
+     * @param input The input text to be cleaned.
+     * @return A cleaned character sequence with blocklisted patterns removed.
      */
     private fun removeBlocklisted(input: CharSequence): CharSequence {
         var source = input

app/src/main/java/fr/free/nrw/commons/upload/UploadModel.kt

@@ -98,10 +98,11 @@ class UploadModel @Inject internal constructor(
         imageProcessingService.validateImage(uploadItem, inAppPictureLocation)
 
     /**
-     * Calls checkDuplicateImage() of ImageProcessingService to check if image is duplicate
+     * Calls checkDuplicateImage() of ImageProcessingService to check if the image is a duplicate.
      *
-     * @param filePath file to be checked
+     * @param originalFilePath The original file URI.
-     * @return IMAGE_DUPLICATE or IMAGE_OK
+     * @param modifiedFilePath The modified file URI.
+     * @return IMAGE_DUPLICATE if the file already exists, IMAGE_OK otherwise.
      */
     fun checkDuplicateImage(originalFilePath: Uri?, modifiedFilePath: Uri?): Single<Int> =
         imageProcessingService.checkIfFileAlreadyExists(

app/src/main/java/fr/free/nrw/commons/utils/LocationUtils.kt

@@ -16,12 +16,12 @@ object LocationUtils {
         val indexOfPrefix = customQuery.indexOf("Point(")
         if (indexOfPrefix == -1) {
             Timber.e("Invalid prefix index - Seems like user has entered an invalid query")
-            return latLng
+            return null
         }
         val indexOfSuffix = customQuery.indexOf(")\"", indexOfPrefix)
         if (indexOfSuffix == -1) {
             Timber.e("Invalid suffix index - Seems like user has entered an invalid query")
-            return latLng
+            return null
         }
         val latLngString = customQuery.substring(indexOfPrefix + "Point(".length, indexOfSuffix)
         if (latLngString.isEmpty()) {

app/src/main/java/fr/free/nrw/commons/wikidata/model/page/PageTitle.kt

@@ -32,8 +32,8 @@ class PageTitle : Parcelable {
      * looking at.
      *
      * Examples:
-     * * [[Manchester]] on enwiki will have a namespace of null
+     * * \[\[Manchester\]\] on enwiki will have a namespace of null
-     * * [[Deutschland]] on dewiki will have a namespace of null
+     * * \[\[Deutschland\]\] on dewiki will have a namespace of null
      * * [[User:Deskana]] on enwiki will have a namespace of "User"
      * * [[Utilisateur:Deskana]] on frwiki will have a namespace of "Utilisateur", even if you got
      * to the page by going to [[User:Deskana]] and having MediaWiki automatically redirect you.