From af3e9ba47216b322b70b706fc3f2e9b68f630358 Mon Sep 17 00:00:00 2001
From: Rohit Verma <rv17837@outlook.com>
Date: Sat, 16 Aug 2025 16:25:15 +0530
Subject: [PATCH] docs: add KDoc for edge-to-edge insets utility functions

---
 .../free/nrw/commons/utils/EdgeToEdgeUtils.kt | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/app/src/main/java/fr/free/nrw/commons/utils/EdgeToEdgeUtils.kt b/app/src/main/java/fr/free/nrw/commons/utils/EdgeToEdgeUtils.kt
index 9a5460c46..8478f7f51 100644
--- a/app/src/main/java/fr/free/nrw/commons/utils/EdgeToEdgeUtils.kt
+++ b/app/src/main/java/fr/free/nrw/commons/utils/EdgeToEdgeUtils.kt
@@ -12,6 +12,15 @@ import androidx.core.view.updateLayoutParams
 import androidx.core.view.updatePadding
 import fr.free.nrw.commons.R
 
+/**
+ * Applies edge-to-edge system bar insets to a [View]’s margins using a custom adjustment block.
+ *
+ * Stores the initial margins to ensure inset calculations are additive, and applies the provided
+ * [block] with an [InsetsAccumulator] containing initial and system bar inset values.
+ *
+ * @param typeMask The type of window insets to apply. Defaults to [WindowInsetsCompat.Type.systemBars].
+ * @param block Lambda applied to update [MarginLayoutParams] using the accumulated insets.
+ */
 fun View.applyEdgeToEdgeInsets(
     typeMask: Int = WindowInsetsCompat.Type.systemBars(),
     block: MarginLayoutParams.(InsetsAccumulator) -> Unit
@@ -66,6 +75,11 @@ fun View.applyEdgeToEdgeInsets(
     }
 }
 
+/**
+ * Applies edge-to-edge system bar insets to the top padding of the view.
+ *
+ * @param typeMask The type of window insets to apply. Defaults to [WindowInsetsCompat.Type.systemBars].
+ */
 fun View.applyEdgeToEdgeTopPaddingInsets(
     typeMask: Int = WindowInsetsCompat.Type.systemBars(),
 ) {
@@ -82,6 +96,11 @@ fun View.applyEdgeToEdgeTopPaddingInsets(
     }
 }
 
+/**
+ * Applies edge-to-edge system bar insets to the bottom padding of the view.
+ *
+ * @param typeMask The type of window insets to apply. Defaults to [WindowInsetsCompat.Type.systemBars].
+ */
 fun View.applyEdgeToEdgeBottomPaddingInsets(
     typeMask: Int = WindowInsetsCompat.Type.systemBars(),
 ) {
@@ -98,6 +117,11 @@ fun View.applyEdgeToEdgeBottomPaddingInsets(
     }
 }
 
+/**
+ * Applies system bar insets to all margins (top, bottom, left, right) of the view.
+ *
+ * @param view The target view.
+ */
 fun applyEdgeToEdgeAllInsets(view: View) = view.applyEdgeToEdgeInsets { insets ->
     leftMargin = insets.left
     rightMargin = insets.right
@@ -105,18 +129,32 @@ fun applyEdgeToEdgeAllInsets(view: View) = view.applyEdgeToEdgeInsets { insets -
     bottomMargin = insets.bottom
 }
 
+/**
+ * Applies system bar insets to the top and horizontal margins of the view.
+ *
+ * @param view The target view.
+ */
 fun applyEdgeToEdgeTopInsets(view: View) = view.applyEdgeToEdgeInsets { insets ->
     leftMargin = insets.left
     rightMargin = insets.right
     topMargin = insets.top
 }
 
+/**
+ * Applies system bar insets to the bottom and horizontal margins of the view.
+ *
+ * @param view The target view.
+ */
 fun applyEdgeToEdgeBottomInsets(view: View) = view.applyEdgeToEdgeInsets { insets ->
     leftMargin = insets.left
     rightMargin = insets.right
     bottomMargin = insets.bottom
 }
 
+/**
+ * Holds both initial margin values and system bar insets, providing summed values
+ * for each side (top, bottom, left, right) to apply in layout updates.
+ */
 data class InsetsAccumulator(
     private val initialTop: Int,
     private val insetTop: Int,