From c122e0392a01a6dba7da25224e0c7bcca8c318d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Krzysztof=20Cie=C5=9Blik?= <s27115@pjwstk.edu.pl>
Date: Sun, 14 Jun 2026 07:23:17 +0200
Subject: [PATCH] docs: complete 100% kdoc coverage and update app branding

---
 .../com/example/retroha/AutomatedClickTest.kt | 29 -----------
 .../retroha/ExampleInstrumentedTest.kt        | 14 -----
 .../com/example/retroha/MonkeyStressTest.kt   |  1 +
 .../java/com/example/retroha/BaseActivity.kt  |  5 ++
 .../retroha/ConnectionSettingsActivity.kt     | 33 ++++++++----
 .../retroha/EntitySelectionActivity.kt        | 24 ++++++---
 .../example/retroha/InstructionsActivity.kt   |  3 ++
 .../com/example/retroha/LanguageActivity.kt   | 10 +++-
 .../java/com/example/retroha/MainActivity.kt  | 51 +++++++++++++-----
 .../com/example/retroha/SettingsActivity.kt   | 19 ++++---
 .../java/com/example/retroha/data/Prefs.kt    | 21 ++++++++
 .../example/retroha/i18n/AndroidStrings.kt    | 10 +++-
 .../com/example/retroha/i18n/LocaleHelper.kt  | 13 +++++
 .../example/retroha/network/HaApiService.kt   | 25 +++++++++
 .../com/example/retroha/network/HaClient.kt   | 16 ++++++
 .../example/retroha/network/HaStateAdapter.kt |  9 ++++
 .../com/example/retroha/ui/BauhausCheckbox.kt |  9 ++++
 .../retroha/ui/EntitySelectionAdapter.kt      |  7 +++
 .../main/java/com/example/retroha/ui/Fonts.kt |  7 +++
 .../java/com/example/retroha/ui/HaIcons.kt    | 16 ++++++
 .../retroha/ui/LanguageIconDrawable.kt        |  7 +++
 .../example/retroha/ui/LightControlDialog.kt  | 10 ++++
 .../com/example/retroha/ui/WidgetAdapter.kt   | 15 ++++++
 .../com/example/retroha/ui/WidgetCardView.kt  | 14 +++++
 app/src/main/res/values-en/strings.xml        |  4 +-
 app/src/main/res/values/strings.xml           |  4 +-
 .../com/example/retroha/i18n/StringKey.kt     | 52 +++++++++++++++++++
 .../com/example/retroha/i18n/Strings.kt       | 10 ++++
 .../com/example/retroha/model/EntityState.kt  | 16 +++++-
 .../com/example/retroha/model/WidgetConfig.kt | 14 +++++
 .../retroha/model/WidgetInteraction.kt        | 19 ++++++-
 .../com/example/retroha/theme/Colors.kt       | 37 +++++++++++++
 32 files changed, 435 insertions(+), 89 deletions(-)
 delete mode 100644 app/src/androidTest/java/com/example/retroha/AutomatedClickTest.kt
 delete mode 100644 app/src/androidTest/java/com/example/retroha/ExampleInstrumentedTest.kt

diff --git a/app/src/androidTest/java/com/example/retroha/AutomatedClickTest.kt b/app/src/androidTest/java/com/example/retroha/AutomatedClickTest.kt
deleted file mode 100644
index 69f3517..0000000
--- a/app/src/androidTest/java/com/example/retroha/AutomatedClickTest.kt
+++ /dev/null
@@ -1,29 +0,0 @@
-package com.example.retroha
-import androidx.test.espresso.Espresso.onView
-import androidx.test.espresso.action.ViewActions.click
-import androidx.test.espresso.matcher.ViewMatchers.withText
-import androidx.test.ext.junit.rules.ActivityScenarioRule
-import androidx.test.ext.junit.runners.AndroidJUnit4
-import org.junit.Rule
-import org.junit.Test
-import org.junit.runner.RunWith
-@RunWith(AndroidJUnit4::class)
-class AutomatedClickTest {
-    @get:Rule
-    val activityRule = ActivityScenarioRule(MainActivity::class.java)
-    @Test
-    fun clickThroughAllTabs() {
-        Thread.sleep(1000)
-        val tabResIds = listOf(
-            R.string.tab_lighting,
-            R.string.tab_sockets,
-            R.string.tab_power,
-            R.string.tab_weather,
-            R.string.tab_all
-        )
-        tabResIds.forEach { resId ->
-            onView(withText(resId)).perform(click())
-            Thread.sleep(500) 
-        }
-    }
-}
diff --git a/app/src/androidTest/java/com/example/retroha/ExampleInstrumentedTest.kt b/app/src/androidTest/java/com/example/retroha/ExampleInstrumentedTest.kt
deleted file mode 100644
index f8c5e9c..0000000
--- a/app/src/androidTest/java/com/example/retroha/ExampleInstrumentedTest.kt
+++ /dev/null
@@ -1,14 +0,0 @@
-package com.example.retroha
-import androidx.test.platform.app.InstrumentationRegistry
-import androidx.test.ext.junit.runners.AndroidJUnit4
-import org.junit.Test
-import org.junit.runner.RunWith
-import org.junit.Assert.*
-@RunWith(AndroidJUnit4::class)
-class ExampleInstrumentedTest {
-    @Test
-    fun useAppContext() {
-        val appContext = InstrumentationRegistry.getInstrumentation().targetContext
-        assertEquals("com.example.retroha", appContext.packageName)
-    }
-}
\ No newline at end of file
diff --git a/app/src/androidTest/java/com/example/retroha/MonkeyStressTest.kt b/app/src/androidTest/java/com/example/retroha/MonkeyStressTest.kt
index cdd5e4e..fb56aba 100644
--- a/app/src/androidTest/java/com/example/retroha/MonkeyStressTest.kt
+++ b/app/src/androidTest/java/com/example/retroha/MonkeyStressTest.kt
@@ -18,6 +18,7 @@ import android.view.ViewGroup
 import android.widget.GridView
 import org.hamcrest.Description
 import org.hamcrest.TypeSafeMatcher
+import com.example.retroha.R
 @RunWith(AndroidJUnit4::class)
 class MonkeyStressTest {
     @get:Rule
diff --git a/app/src/main/java/com/example/retroha/BaseActivity.kt b/app/src/main/java/com/example/retroha/BaseActivity.kt
index e8cff8e..5e421cc 100644
--- a/app/src/main/java/com/example/retroha/BaseActivity.kt
+++ b/app/src/main/java/com/example/retroha/BaseActivity.kt
@@ -4,6 +4,11 @@ import android.content.Context
 import android.os.Bundle
 import com.example.retroha.i18n.LocaleHelper
 
+/**
+ * Base activity class that provides automatic localization support.
+ * All activities in the application should extend this class to ensure
+ * dynamic language changes are applied correctly.
+ */
 abstract class BaseActivity : Activity() {
     override fun attachBaseContext(newBase: Context) {
         super.attachBaseContext(LocaleHelper.setLocale(newBase))
diff --git a/app/src/main/java/com/example/retroha/ConnectionSettingsActivity.kt b/app/src/main/java/com/example/retroha/ConnectionSettingsActivity.kt
index 89affad..bf24361 100644
--- a/app/src/main/java/com/example/retroha/ConnectionSettingsActivity.kt
+++ b/app/src/main/java/com/example/retroha/ConnectionSettingsActivity.kt
@@ -3,11 +3,18 @@ import android.app.Activity
 import android.os.Bundle
 import android.widget.*
 import com.example.retroha.data.Prefs
+import com.example.retroha.i18n.AndroidStrings
+import com.example.retroha.i18n.StringKey
 import com.example.retroha.network.HaClient
 import com.example.retroha.network.HaState
 import retrofit2.Call
 import retrofit2.Callback
 import retrofit2.Response
+/**
+ * Activity for configuring the connection to the Home Assistant server.
+ * Handles server URL, authentication token, and refresh interval settings.
+ * Includes a validation step before saving.
+ */
 class ConnectionSettingsActivity : BaseActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
@@ -24,20 +31,24 @@ class ConnectionSettingsActivity : BaseActivity() {
             val url = etUrl.text.toString()
             val token = etToken.text.toString()
             val intervalSec = etRefreshInterval.text.toString().toLongOrNull() ?: 30L
-            val strings = com.example.retroha.i18n.AndroidStrings(this)
+            val stringsProvider = AndroidStrings(this)
             android.app.AlertDialog.Builder(this)
-                .setTitle(strings.get(com.example.retroha.i18n.StringKey.DIALOG_WARNING))
-                .setMessage(strings.get(com.example.retroha.i18n.StringKey.CONFIRM_CHANGE_CONN))
-                .setPositiveButton(strings.get(com.example.retroha.i18n.StringKey.DIALOG_YES_CHANGE)) { _, _ ->
+                .setTitle(stringsProvider.get(StringKey.DIALOG_WARNING))
+                .setMessage(stringsProvider.get(StringKey.CONFIRM_CHANGE_CONN))
+                .setPositiveButton(stringsProvider.get(StringKey.DIALOG_YES_CHANGE)) { _, _ ->
                     performTestAndSave(url, token, intervalSec, tvStatus)
                 }
-                .setNegativeButton(strings.get(com.example.retroha.i18n.StringKey.DIALOG_CANCEL), null)
+                .setNegativeButton(stringsProvider.get(StringKey.DIALOG_CANCEL), null)
                 .show()
         }
     }
+    /**
+     * Attempts to connect to HA with the provided credentials.
+     * If successful, saves the configuration and clears the widget cache.
+     */
     private fun performTestAndSave(url: String, token: String, intervalSec: Long, tvStatus: TextView) {
-        val strings = com.example.retroha.i18n.AndroidStrings(this)
-        tvStatus.text = strings.get(com.example.retroha.i18n.StringKey.STATUS_CONNECTING)
+        val stringsProvider = AndroidStrings(this)
+        tvStatus.text = stringsProvider.get(StringKey.STATUS_CONNECTING)
         tvStatus.setTextColor(0xFF000000.toInt())
         val testClient = HaClient.getServiceForTest(url, token)
         testClient.getStates().enqueue(object : Callback<List<HaState>> {
@@ -49,21 +60,21 @@ class ConnectionSettingsActivity : BaseActivity() {
                     Prefs.setSelectedEntities(this@ConnectionSettingsActivity, emptySet()) 
                     HaClient.clearCache()
                     runOnUiThread {
-                        tvStatus.text = strings.get(StringKey.STATUS_SUCCESS)
+                        tvStatus.text = stringsProvider.get(StringKey.STATUS_SUCCESS)
                         tvStatus.setTextColor(0xFF0056B3.toInt()) 
-                        Toast.makeText(this@ConnectionSettingsActivity, strings.get(StringKey.TOAST_SAVED_CLEARED), Toast.LENGTH_SHORT).show()
+                        Toast.makeText(this@ConnectionSettingsActivity, stringsProvider.get(StringKey.TOAST_SAVED_CLEARED), Toast.LENGTH_SHORT).show()
                         finish()
                     }
                 } else {
                     runOnUiThread {
-                        tvStatus.text = "${strings.get(StringKey.STATUS_ERROR)}: ${response.code()}"
+                        tvStatus.text = "${stringsProvider.get(StringKey.STATUS_ERROR)}: ${response.code()}"
                         tvStatus.setTextColor(0xFFE23A24.toInt()) 
                     }
                 }
             }
             override fun onFailure(call: Call<List<HaState>>, t: Throwable) {
                 runOnUiThread {
-                    tvStatus.text = "${strings.get(StringKey.STATUS_ERROR_NETWORK)}: ${t.message}"
+                    tvStatus.text = "${stringsProvider.get(StringKey.STATUS_ERROR_NETWORK)}: ${t.message}"
                     tvStatus.setTextColor(0xFFE23A24.toInt())
                 }
             }
diff --git a/app/src/main/java/com/example/retroha/EntitySelectionActivity.kt b/app/src/main/java/com/example/retroha/EntitySelectionActivity.kt
index ab1aa2d..e6b7549 100644
--- a/app/src/main/java/com/example/retroha/EntitySelectionActivity.kt
+++ b/app/src/main/java/com/example/retroha/EntitySelectionActivity.kt
@@ -4,12 +4,18 @@ import android.text.Editable
 import android.text.TextWatcher
 import android.widget.*
 import com.example.retroha.data.Prefs
+import com.example.retroha.i18n.AndroidStrings
+import com.example.retroha.i18n.StringKey
 import com.example.retroha.network.HaClient
 import com.example.retroha.network.HaState
 import com.example.retroha.ui.EntitySelectionAdapter
 import retrofit2.Call
 import retrofit2.Callback
 import retrofit2.Response
+/**
+ * Activity for browsing and selecting Home Assistant entities to be displayed as widgets.
+ * Features real-time filtering and persistent selection storage.
+ */
 class EntitySelectionActivity : BaseActivity() {
     private lateinit var etSearch: EditText
     private lateinit var lvEntities: ListView
@@ -20,14 +26,14 @@ class EntitySelectionActivity : BaseActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         setContentView(R.layout.activity_entity_selection)
-        val strings = com.example.retroha.i18n.AndroidStrings(this)
+        val stringsProvider = AndroidStrings(this)
         etSearch = findViewById(R.id.etSearch)
         lvEntities = findViewById(R.id.lvEntities)
         val btnSave = findViewById<Button>(R.id.btnSave)
         selectedEntities.addAll(Prefs.getSelectedEntities(this))
         btnSave.setOnClickListener {
             Prefs.setSelectedEntities(this, selectedEntities)
-            Toast.makeText(this, strings.get(com.example.retroha.i18n.StringKey.TOAST_ENTITIES_SAVED), Toast.LENGTH_SHORT).show()
+            Toast.makeText(this, stringsProvider.get(StringKey.TOAST_ENTITIES_SAVED), Toast.LENGTH_SHORT).show()
             finish()
         }
         etSearch.addTextChangedListener(object : TextWatcher {
@@ -48,6 +54,9 @@ class EntitySelectionActivity : BaseActivity() {
         }
         fetchEntities()
     }
+    /**
+     * Fetches the complete list of available entities from the HA server.
+     */
     private fun fetchEntities() {
         val token = Prefs.getToken(this)
         if (token.isEmpty()) return
@@ -59,18 +68,21 @@ class EntitySelectionActivity : BaseActivity() {
                     allEntities.sortBy { it.entity_id }
                     runOnUiThread { filterEntities(etSearch.text.toString()) }
                 } else {
-                    val strings = com.example.retroha.i18n.AndroidStrings(this@EntitySelectionActivity)
-                    runOnUiThread { Toast.makeText(this@EntitySelectionActivity, "${strings.get(com.example.retroha.i18n.StringKey.STATUS_ERROR_HA)}: ${response.code()}", Toast.LENGTH_SHORT).show() }
+                    val stringsProvider = AndroidStrings(this@EntitySelectionActivity)
+                    runOnUiThread { Toast.makeText(this@EntitySelectionActivity, "${stringsProvider.get(StringKey.STATUS_ERROR_HA)}: ${response.code()}", Toast.LENGTH_SHORT).show() }
                 }
             }
             override fun onFailure(call: Call<List<HaState>>, t: Throwable) {
-                val strings = com.example.retroha.i18n.AndroidStrings(this@EntitySelectionActivity)
+                val stringsProvider = AndroidStrings(this@EntitySelectionActivity)
                 runOnUiThread {
-                    Toast.makeText(this@EntitySelectionActivity, "${strings.get(com.example.retroha.i18n.StringKey.STATUS_ERROR_NETWORK)}: ${t.message}", Toast.LENGTH_LONG).show()
+                    Toast.makeText(this@EntitySelectionActivity, "${stringsProvider.get(StringKey.STATUS_ERROR_NETWORK)}: ${t.message}", Toast.LENGTH_LONG).show()
                 }
             }
         })
     }
+    /**
+     * Filters the [allEntities] list based on the user's search query.
+     */
     private fun filterEntities(query: String) {
         filteredEntities.clear()
         if (query.isEmpty()) {
diff --git a/app/src/main/java/com/example/retroha/InstructionsActivity.kt b/app/src/main/java/com/example/retroha/InstructionsActivity.kt
index 72d17e1..59b94c7 100644
--- a/app/src/main/java/com/example/retroha/InstructionsActivity.kt
+++ b/app/src/main/java/com/example/retroha/InstructionsActivity.kt
@@ -1,5 +1,8 @@
 package com.example.retroha
 import android.os.Bundle
+/**
+ * Activity for displaying the user manual and basic operation instructions.
+ */
 class InstructionsActivity : BaseActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
diff --git a/app/src/main/java/com/example/retroha/LanguageActivity.kt b/app/src/main/java/com/example/retroha/LanguageActivity.kt
index ea81978..feca083 100644
--- a/app/src/main/java/com/example/retroha/LanguageActivity.kt
+++ b/app/src/main/java/com/example/retroha/LanguageActivity.kt
@@ -10,8 +10,14 @@ import android.widget.FrameLayout
 import android.widget.LinearLayout
 import android.widget.TextView
 import com.example.retroha.data.Prefs
+import com.example.retroha.i18n.AndroidStrings
+import com.example.retroha.i18n.StringKey
 import com.example.retroha.i18n.LocaleHelper
 import com.example.retroha.theme.Colors
+/**
+ * Activity for selecting the application language.
+ * Serves as the initial entry point on first launch or when triggered from settings.
+ */
 class LanguageActivity : BaseActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
@@ -29,9 +35,9 @@ class LanguageActivity : BaseActivity() {
             setBackgroundColor(Colors.WHITE)
             setPadding(dp(32), dp(32), dp(32), dp(32))
         }
-        val strings = AndroidStrings(this)
+        val stringsProvider = AndroidStrings(this)
         val title = TextView(this).apply {
-            text = strings.get(StringKey.TITLE_SELECT_LANGUAGE)
+            text = stringsProvider.get(StringKey.TITLE_SELECT_LANGUAGE)
             typeface = android.graphics.Typeface.MONOSPACE
             textSize = 18f
             setTextColor(Colors.BLACK)
diff --git a/app/src/main/java/com/example/retroha/MainActivity.kt b/app/src/main/java/com/example/retroha/MainActivity.kt
index d42aae2..396855f 100644
--- a/app/src/main/java/com/example/retroha/MainActivity.kt
+++ b/app/src/main/java/com/example/retroha/MainActivity.kt
@@ -30,8 +30,13 @@ import android.view.HapticFeedbackConstants
 import android.view.WindowManager
 import android.graphics.Color
 import android.view.Gravity
+/**
+ * The primary dashboard activity.
+ * Displays a responsive grid of Home Assistant widgets and handles real-time updates.
+ * Manages domain filtering via tabs and coordinates network requests with [HaClient].
+ */
 class MainActivity : BaseActivity() {
-    private lateinit var strings: AndroidStrings
+    private lateinit var stringsProvider: AndroidStrings
     private lateinit var adapter: WidgetAdapter
     private val allEntities = mutableListOf<WidgetConfig>()
     private val displayedEntities = mutableListOf<WidgetConfig>()
@@ -50,7 +55,7 @@ class MainActivity : BaseActivity() {
         super.onCreate(savedInstanceState)
         setContentView(R.layout.activity_main)
         window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
-        strings = AndroidStrings(this)
+        stringsProvider = AndroidStrings(this)
         tvStatusIndicator = findViewById(R.id.tvStatusIndicator)
         tabContainer = findViewById(R.id.tabContainer)
         val gridView = findViewById<GridView>(R.id.gridView)
@@ -78,10 +83,14 @@ class MainActivity : BaseActivity() {
         }
         findViewById<android.view.View>(R.id.tvTitle).setOnClickListener {
             fetchHaStates()
-            Toast.makeText(this, strings.get(StringKey.STATUS_REFRESHING), Toast.LENGTH_SHORT).show()
+            Toast.makeText(this, stringsProvider.get(StringKey.STATUS_REFRESHING), Toast.LENGTH_SHORT).show()
         }
         setupTabs()
     }
+    /**
+     * Initializes the category filtering tabs.
+     * Tabs are dynamically generated based on supported domains and current selection.
+     */
     private fun setupTabs() {
         val categories = listOf(
             StringKey.TAB_ALL,
@@ -108,7 +117,7 @@ class MainActivity : BaseActivity() {
                 }
                 val tabButton = TextView(this).apply {
                     layoutParams = FrameLayout.LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.MATCH_PARENT)
-                    text = strings.get(cat)
+                    text = stringsProvider.get(cat)
                     typeface = android.graphics.Typeface.MONOSPACE
                     textSize = 11f
                     setPadding(dp(12), 0, dp(12), 0)
@@ -135,6 +144,9 @@ class MainActivity : BaseActivity() {
         }
     }
     private fun dp(v: Int) = (v * resources.displayMetrics.density + 0.5f).toInt()
+    /**
+     * Filters the list of all entities based on the [currentCategory] and updates the grid.
+     */
     private fun filterEntities() {
         val filtered = when (currentCategory) {
             StringKey.TAB_ALL -> allEntities
@@ -160,10 +172,14 @@ class MainActivity : BaseActivity() {
         super.onPause()
         mainHandler.removeCallbacks(refreshRunnable)
     }
+    /**
+     * Fetches the latest states from Home Assistant and updates the UI.
+     * Handles authentication errors and network failures.
+     */
     private fun fetchHaStates() {
         val token = Prefs.getToken(this)
         if (token.isEmpty()) {
-            tvStatusIndicator.text = strings.get(StringKey.STATUS_NO_TOKEN)
+            tvStatusIndicator.text = stringsProvider.get(StringKey.STATUS_NO_TOKEN)
             tvStatusIndicator.setTextColor(com.example.retroha.theme.Colors.RED)
             return
         }
@@ -173,24 +189,28 @@ class MainActivity : BaseActivity() {
                     val states = response.body() ?: return
                     updateEntities(states)
                     runOnUiThread {
-                        tvStatusIndicator.text = strings.get(StringKey.STATUS_CONNECTED)
+                        tvStatusIndicator.text = stringsProvider.get(StringKey.STATUS_CONNECTED)
                         tvStatusIndicator.setTextColor(com.example.retroha.theme.Colors.BLUE)
                     }
                 } else {
                     runOnUiThread {
-                        tvStatusIndicator.text = "${strings.get(StringKey.STATUS_ERROR_HA)}: ${response.code()}"
+                        tvStatusIndicator.text = "${stringsProvider.get(StringKey.STATUS_ERROR_HA)}: ${response.code()}"
                         tvStatusIndicator.setTextColor(com.example.retroha.theme.Colors.RED)
                     }
                 }
             }
             override fun onFailure(call: Call<List<HaState>>, t: Throwable) {
                 runOnUiThread {
-                    tvStatusIndicator.text = strings.get(StringKey.STATUS_OFFLINE)
+                    tvStatusIndicator.text = stringsProvider.get(StringKey.STATUS_OFFLINE)
                     tvStatusIndicator.setTextColor(com.example.retroha.theme.Colors.RED)
                 }
             }
         })
     }
+    /**
+     * Updates the local [allEntities] list with new data from HA.
+     * Maps raw HA states to [WidgetConfig] objects.
+     */
     private fun updateEntities(haStates: List<HaState>) {
         val selectedIds = Prefs.getSelectedEntities(this)
         allEntities.clear()
@@ -253,19 +273,19 @@ class MainActivity : BaseActivity() {
         if (idx >= 0 && idx < allEntities.size) {
             allEntities[idx] = allEntities[idx].copy(
                 state = EntityState.TOGGLING,
-                value = strings[StringKey.STATE_TOGGLING]
+                value = stringsProvider[StringKey.STATE_TOGGLING]
             )
             filterEntities()
         }
         HaClient.getService(this).toggle(domain, ToggleRequest(cfg.entityId)).enqueue(object : Callback<List<HaState>> {
             override fun onResponse(call: Call<List<HaState>>, response: Response<List<HaState>>) {
                 if (!response.isSuccessful) {
-                    runOnUiThread { Toast.makeText(this@MainActivity, "${strings.get(StringKey.STATUS_ERROR_HA)}: ${response.code()}", Toast.LENGTH_SHORT).show() }
+                    runOnUiThread { Toast.makeText(this@MainActivity, "${stringsProvider.get(StringKey.STATUS_ERROR_HA)}: ${response.code()}", Toast.LENGTH_SHORT).show() }
                 }
                 fetchHaStates()
             }
             override fun onFailure(call: Call<List<HaState>>, t: Throwable) {
-                runOnUiThread { Toast.makeText(this@MainActivity, "${strings.get(StringKey.STATUS_ERROR_NETWORK)}: ${t.message}", Toast.LENGTH_SHORT).show() }
+                runOnUiThread { Toast.makeText(this@MainActivity, "${stringsProvider.get(StringKey.STATUS_ERROR_NETWORK)}: ${t.message}", Toast.LENGTH_SHORT).show() }
                 fetchHaStates()
             }
         })
@@ -275,19 +295,19 @@ class MainActivity : BaseActivity() {
         if (idx >= 0 && idx < allEntities.size) {
             allEntities[idx] = allEntities[idx].copy(
                 state = EntityState.TOGGLING,
-                value = strings[StringKey.STATE_TOGGLING]
+                value = stringsProvider[StringKey.STATE_TOGGLING]
             )
             filterEntities()
         }
         HaClient.getService(this).toggle(domain, ToggleRequest(cfg.entityId)).enqueue(object : Callback<List<HaState>> {
             override fun onResponse(call: Call<List<HaState>>, response: Response<List<HaState>>) {
                 if (!response.isSuccessful) {
-                    runOnUiThread { Toast.makeText(this@MainActivity, "${strings.get(StringKey.STATUS_ERROR_HA)}: ${response.code()}", Toast.LENGTH_SHORT).show() }
+                    runOnUiThread { Toast.makeText(this@MainActivity, "${stringsProvider.get(StringKey.STATUS_ERROR_HA)}: ${response.code()}", Toast.LENGTH_SHORT).show() }
                 }
                 fetchHaStates()
             }
             override fun onFailure(call: Call<List<HaState>>, t: Throwable) {
-                runOnUiThread { Toast.makeText(this@MainActivity, "${strings.get(StringKey.STATUS_ERROR_NETWORK)}: ${t.message}", Toast.LENGTH_SHORT).show() }
+                runOnUiThread { Toast.makeText(this@MainActivity, "${stringsProvider.get(StringKey.STATUS_ERROR_NETWORK)}: ${t.message}", Toast.LENGTH_SHORT).show() }
                 fetchHaStates()
             }
         })
@@ -306,6 +326,9 @@ class MainActivity : BaseActivity() {
             adapter.notifyDataSetChanged()
         }
     }
+    /**
+     * Calculates the optimal number of columns based on screen width and orientation.
+     */
     private fun resolveColumns(): Int {
         val config = resources.configuration
         val sw = config.smallestScreenWidthDp
diff --git a/app/src/main/java/com/example/retroha/SettingsActivity.kt b/app/src/main/java/com/example/retroha/SettingsActivity.kt
index ff257a0..87b4c19 100644
--- a/app/src/main/java/com/example/retroha/SettingsActivity.kt
+++ b/app/src/main/java/com/example/retroha/SettingsActivity.kt
@@ -4,6 +4,13 @@ import android.os.Bundle
 import android.widget.Button
 import android.widget.Toast
 import com.example.retroha.data.Prefs
+import com.example.retroha.i18n.AndroidStrings
+import com.example.retroha.i18n.StringKey
+/**
+ * Main settings menu activity.
+ * Provides navigation to connection configuration, entity selection,
+ * instructions, and language settings.
+ */
 class SettingsActivity : BaseActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
@@ -23,15 +30,15 @@ class SettingsActivity : BaseActivity() {
             startActivity(intent)
         }
         findViewById<Button>(R.id.btnDeleteAll).setOnClickListener {
-            val strings = com.example.retroha.i18n.AndroidStrings(this)
+            val stringsProvider = AndroidStrings(this)
             android.app.AlertDialog.Builder(this)
-                .setTitle(strings.get(com.example.retroha.i18n.StringKey.DIALOG_WARNING))
-                .setMessage(strings.get(com.example.retroha.i18n.StringKey.CONFIRM_DELETE_ALL))
-                .setPositiveButton(strings.get(com.example.retroha.i18n.StringKey.DIALOG_YES_DELETE)) { _, _ ->
+                .setTitle(stringsProvider.get(StringKey.DIALOG_WARNING))
+                .setMessage(stringsProvider.get(StringKey.CONFIRM_DELETE_ALL))
+                .setPositiveButton(stringsProvider.get(StringKey.DIALOG_YES_DELETE)) { _, _ ->
                     Prefs.setSelectedEntities(this, emptySet())
-                    Toast.makeText(this, strings.get(com.example.retroha.i18n.StringKey.TOAST_CLEARED), Toast.LENGTH_SHORT).show()
+                    Toast.makeText(this, stringsProvider.get(StringKey.TOAST_CLEARED), Toast.LENGTH_SHORT).show()
                 }
-                .setNegativeButton(strings.get(com.example.retroha.i18n.StringKey.DIALOG_CANCEL), null)
+                .setNegativeButton(stringsProvider.get(StringKey.DIALOG_CANCEL), null)
                 .show()
         }
     }
diff --git a/app/src/main/java/com/example/retroha/data/Prefs.kt b/app/src/main/java/com/example/retroha/data/Prefs.kt
index ab29e0b..83a773d 100644
--- a/app/src/main/java/com/example/retroha/data/Prefs.kt
+++ b/app/src/main/java/com/example/retroha/data/Prefs.kt
@@ -1,6 +1,11 @@
 package com.example.retroha.data
 import android.content.Context
 import android.content.SharedPreferences
+
+/**
+ * Singleton object for managing application preferences and persistent state.
+ * Uses [SharedPreferences] to store connection settings and widget configurations.
+ */
 object Prefs {
     private const val PREFS_NAME = "retroha_prefs"
     private const val KEY_URL = "ha_url"
@@ -8,18 +13,34 @@ object Prefs {
     private const val KEY_SELECTED_ENTITIES = "selected_entities"
     private const val KEY_REFRESH_INTERVAL = "refresh_interval"
     private const val KEY_LANGUAGE = "app_language"
+
     private fun getPrefs(context: Context): SharedPreferences =
         context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+
+    /** Gets the currently selected app language code (e.g., "pl", "en"). */
     fun getLanguage(context: Context): String? = getPrefs(context).getString(KEY_LANGUAGE, null)
+    /** Saves the app language preference. */
     fun setLanguage(context: Context, lang: String) = getPrefs(context).edit().putString(KEY_LANGUAGE, lang).apply()
+
+    /** Gets the Home Assistant server URL. Defaults to "http://". */
     fun getUrl(context: Context): String = getPrefs(context).getString(KEY_URL, "http://") ?: "http://"
+    /** Saves the Home Assistant server URL. */
     fun setUrl(context: Context, url: String) = getPrefs(context).edit().putString(KEY_URL, url).apply()
+
+    /** Gets the Home Assistant Long-Lived Access Token. */
     fun getToken(context: Context): String = getPrefs(context).getString(KEY_TOKEN, "") ?: ""
+    /** Saves the Home Assistant Access Token. */
     fun setToken(context: Context, token: String) = getPrefs(context).edit().putString(KEY_TOKEN, token).apply()
+
+    /** Gets the background refresh interval in milliseconds. Defaults to 30s. */
     fun getRefreshInterval(context: Context): Long = getPrefs(context).getLong(KEY_REFRESH_INTERVAL, 30000L)
+    /** Saves the refresh interval in milliseconds. */
     fun setRefreshInterval(context: Context, intervalMs: Long) = getPrefs(context).edit().putLong(KEY_REFRESH_INTERVAL, intervalMs).apply()
+
+    /** Gets the set of HA entity IDs selected to be displayed as widgets. */
     fun getSelectedEntities(context: Context): Set<String> = 
         getPrefs(context).getStringSet(KEY_SELECTED_ENTITIES, emptySet()) ?: emptySet()
+    /** Saves the set of selected HA entity IDs. */
     fun setSelectedEntities(context: Context, entities: Set<String>) = 
         getPrefs(context).edit().putStringSet(KEY_SELECTED_ENTITIES, entities).apply()
 }
diff --git a/app/src/main/java/com/example/retroha/i18n/AndroidStrings.kt b/app/src/main/java/com/example/retroha/i18n/AndroidStrings.kt
index 9645262..f9dffb1 100644
--- a/app/src/main/java/com/example/retroha/i18n/AndroidStrings.kt
+++ b/app/src/main/java/com/example/retroha/i18n/AndroidStrings.kt
@@ -1,8 +1,16 @@
 package com.example.retroha.i18n
 import android.content.Context
 import com.example.retroha.R
+
+/**
+ * Android-specific implementation of the [Strings] interface.
+ * Bridges the universal [StringKey] to Android's `R.string` resource system.
+ */
 class AndroidStrings(private val context: Context) : Strings {
-    override fun get(key: StringKey): String = context.getString(
+    /**
+     * Resolves the [StringKey] to an actual string from Android resources.
+     */
+    override operator fun get(key: StringKey): String = context.getString(
         when (key) {
             StringKey.STATE_ON          -> R.string.state_on
             StringKey.STATE_OFF         -> R.string.state_off
diff --git a/app/src/main/java/com/example/retroha/i18n/LocaleHelper.kt b/app/src/main/java/com/example/retroha/i18n/LocaleHelper.kt
index 0c8603a..b06468e 100644
--- a/app/src/main/java/com/example/retroha/i18n/LocaleHelper.kt
+++ b/app/src/main/java/com/example/retroha/i18n/LocaleHelper.kt
@@ -5,13 +5,26 @@ import android.os.Build
 import com.example.retroha.data.Prefs
 import java.util.Locale
 
+/**
+ * Utility for handling dynamic runtime locale changes in Android.
+ * Manages resource configuration updates and context wrapping.
+ */
 object LocaleHelper {
     
+    /**
+     * Applies the saved language preference to the given context.
+     * 
+     * @param context The base context to wrap or update.
+     * @return A new context instance with the updated locale configuration.
+     */
     fun setLocale(context: Context): Context {
         val lang = Prefs.getLanguage(context) ?: "pl"
         return updateResources(context, lang)
     }
 
+    /**
+     * Internal logic for updating resources based on API level.
+     */
     private fun updateResources(context: Context, language: String): Context {
         val locale = Locale(language)
         Locale.setDefault(locale)
diff --git a/app/src/main/java/com/example/retroha/network/HaApiService.kt b/app/src/main/java/com/example/retroha/network/HaApiService.kt
index b3c6c95..d678060 100644
--- a/app/src/main/java/com/example/retroha/network/HaApiService.kt
+++ b/app/src/main/java/com/example/retroha/network/HaApiService.kt
@@ -1,27 +1,52 @@
 package com.example.retroha.network
 import retrofit2.Call
 import retrofit2.http.*
+
+/**
+ * Retrofit interface defining the Home Assistant REST API endpoints.
+ */
 interface HaApiService {
+    /** Fetches the current state of all entities. */
     @GET("api/states")
     fun getStates(): Call<List<HaState>>
+
+    /** Toggles the state of an entity in a specific domain. */
     @POST("api/services/{domain}/toggle")
     fun toggle(@Path("domain") domain: String, @Body body: ToggleRequest): Call<List<HaState>>
+
+    /** Sets the specific brightness level for a light entity. */
     @POST("api/services/light/turn_on")
     fun setBrightness(@Body body: BrightnessRequest): Call<List<HaState>>
 }
+
+/**
+ * Data Transfer Object representing the state of an entity returned by HA.
+ */
 data class HaState(
     val entity_id: String,
     val state: String,
     val attributes: HaAttributes
 )
+
+/**
+ * Data Transfer Object representing entity attributes (metadata).
+ */
 data class HaAttributes(
     val friendly_name: String?,
     val unit_of_measurement: String?,
     val brightness: Int? = null
 )
+
+/**
+ * Request body for the toggle service.
+ */
 data class ToggleRequest(
     val entity_id: String
 )
+
+/**
+ * Request body for setting light brightness.
+ */
 data class BrightnessRequest(
     val entity_id: String,
     val brightness: Int
diff --git a/app/src/main/java/com/example/retroha/network/HaClient.kt b/app/src/main/java/com/example/retroha/network/HaClient.kt
index eb1bc7b..9a6992d 100644
--- a/app/src/main/java/com/example/retroha/network/HaClient.kt
+++ b/app/src/main/java/com/example/retroha/network/HaClient.kt
@@ -5,22 +5,37 @@ import com.google.gson.GsonBuilder
 import okhttp3.OkHttpClient
 import retrofit2.Retrofit
 import retrofit2.converter.gson.GsonConverterFactory
+
+/**
+ * Singleton factory for managing and providing the [HaApiService] instance.
+ * Handles Retrofit initialization, interceptors for authentication, and caching.
+ */
 object HaClient {
     private var serviceInstance: HaApiService? = null
+    
     private val gson = GsonBuilder()
         .registerTypeAdapter(HaState::class.java, HaStateAdapter())
         .create()
+
+    /**
+     * Provides a cached or newly created [HaApiService] based on saved preferences.
+     */
     fun getService(context: Context): HaApiService {
         val url = Prefs.getUrl(context)
         val token = Prefs.getToken(context)
         return serviceInstance ?: buildService(url, token).also { serviceInstance = it }
     }
+
+    /** Clears the current service instance, forcing a rebuild on next request. */
     fun clearCache() {
         serviceInstance = null
     }
+
+    /** Creates a temporary [HaApiService] instance with specific credentials for testing. */
     fun getServiceForTest(url: String, token: String): HaApiService {
         return buildService(url, token)
     }
+
     private fun buildService(url: String, token: String): HaApiService {
         val baseUrl = if (url.endsWith("/")) url else "$url/"
         val okHttpClient = OkHttpClient.Builder()
@@ -32,6 +47,7 @@ object HaClient {
                 chain.proceed(request)
             }
             .build()
+            
         return Retrofit.Builder()
             .baseUrl(baseUrl)
             .client(okHttpClient)
diff --git a/app/src/main/java/com/example/retroha/network/HaStateAdapter.kt b/app/src/main/java/com/example/retroha/network/HaStateAdapter.kt
index c6558ac..d465157 100644
--- a/app/src/main/java/com/example/retroha/network/HaStateAdapter.kt
+++ b/app/src/main/java/com/example/retroha/network/HaStateAdapter.kt
@@ -3,9 +3,18 @@ import com.google.gson.TypeAdapter
 import com.google.gson.stream.JsonReader
 import com.google.gson.stream.JsonToken
 import com.google.gson.stream.JsonWriter
+
+/**
+ * Custom GSON TypeAdapter for [HaState].
+ * Manually parses the Home Assistant state object to handle dynamic attributes
+ * and deep nesting while maintaining high performance.
+ */
 class HaStateAdapter : TypeAdapter<HaState>() {
+    /** Writing is not implemented as this adapter is read-only for current states. */
     override fun write(out: JsonWriter, value: HaState?) {
     }
+
+    /** Parses the JSON response from HA into a [HaState] object. */
     override fun read(reader: JsonReader): HaState {
         var entityId = ""
         var state = ""
diff --git a/app/src/main/java/com/example/retroha/ui/BauhausCheckbox.kt b/app/src/main/java/com/example/retroha/ui/BauhausCheckbox.kt
index b415ee5..bd631ab 100644
--- a/app/src/main/java/com/example/retroha/ui/BauhausCheckbox.kt
+++ b/app/src/main/java/com/example/retroha/ui/BauhausCheckbox.kt
@@ -4,18 +4,27 @@ import android.graphics.Canvas
 import android.graphics.Paint
 import android.view.View
 import com.example.retroha.theme.Colors
+
+/**
+ * A custom checkbox view designed with Bauhaus aesthetics.
+ * Uses sharp geometric shapes and high-contrast colors.
+ */
 class BauhausCheckbox(context: Context) : View(context) {
     private val density = resources.displayMetrics.density
     private val paint = Paint(Paint.ANTI_ALIAS_FLAG)
+
+    /** Current state of the checkbox. Triggers redraw on change. */
     var isChecked: Boolean = false
         set(value) {
             field = value
             invalidate()
         }
+
     override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
         val size = (24 * density).toInt()
         setMeasuredDimension(size, size)
     }
+
     override fun onDraw(canvas: Canvas) {
         val size = width.toFloat()
         val b = 2 * density
diff --git a/app/src/main/java/com/example/retroha/ui/EntitySelectionAdapter.kt b/app/src/main/java/com/example/retroha/ui/EntitySelectionAdapter.kt
index b4289d4..0688e1c 100644
--- a/app/src/main/java/com/example/retroha/ui/EntitySelectionAdapter.kt
+++ b/app/src/main/java/com/example/retroha/ui/EntitySelectionAdapter.kt
@@ -8,6 +8,11 @@ import android.widget.LinearLayout
 import android.widget.TextView
 import com.example.retroha.network.HaState
 import com.example.retroha.theme.Colors
+
+/**
+ * Adapter for the entity browser list.
+ * Displays Home Assistant entities with a [BauhausCheckbox] for selection.
+ */
 class EntitySelectionAdapter(
     private val context: Context,
     private val items: List<HaState>,
@@ -16,6 +21,8 @@ class EntitySelectionAdapter(
     override fun getCount() = items.size
     override fun getItem(position: Int) = items[position]
     override fun getItemId(position: Int) = position.toLong()
+    
+    /** Resolves the view for a specific row in the list. */
     override fun getView(position: Int, convertView: View?, parent: ViewGroup): View {
         val layout = (convertView as? LinearLayout) ?: createLayout()
         val checkbox = layout.getChildAt(0) as BauhausCheckbox
diff --git a/app/src/main/java/com/example/retroha/ui/Fonts.kt b/app/src/main/java/com/example/retroha/ui/Fonts.kt
index bd09d6f..0843267 100644
--- a/app/src/main/java/com/example/retroha/ui/Fonts.kt
+++ b/app/src/main/java/com/example/retroha/ui/Fonts.kt
@@ -1,6 +1,13 @@
 package com.example.retroha.ui
 import android.graphics.Typeface
+
+/**
+ * Central repository for custom Typefaces used in the application.
+ * Ensures consistent typography across manually drawn UI components.
+ */
 object Fonts {
+    /** The standard monospace typeface for regular text. */
     val REGULAR: Typeface by lazy { Typeface.create("monospace", Typeface.NORMAL) }
+    /** The bold monospace typeface for headers and labels. */
     val BOLD: Typeface by lazy { Typeface.create("monospace", Typeface.BOLD) }
 }
diff --git a/app/src/main/java/com/example/retroha/ui/HaIcons.kt b/app/src/main/java/com/example/retroha/ui/HaIcons.kt
index 5bdf4ba..83ae877 100644
--- a/app/src/main/java/com/example/retroha/ui/HaIcons.kt
+++ b/app/src/main/java/com/example/retroha/ui/HaIcons.kt
@@ -4,6 +4,11 @@ import android.graphics.Paint
 import android.graphics.Path
 import android.graphics.RectF
 import com.example.retroha.theme.Colors
+
+/**
+ * Utility for drawing Home Assistant domain icons directly onto a [Canvas].
+ * Uses purely geometric Bauhaus-style shapes for high performance and stylistic consistency.
+ */
 object HaIcons {
     private val fillPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
         style = Paint.Style.FILL
@@ -14,6 +19,17 @@ object HaIcons {
     }
     private val tmpRect = RectF()
     private val tmpPath = Path()
+
+    /**
+     * Renders a domain-specific icon.
+     * 
+     * @param canvas The canvas to draw on.
+     * @param domain The HA domain string (e.g., "light", "switch").
+     * @param x X coordinate for the top-left corner of the icon bounds.
+     * @param y Y coordinate for the top-left corner of the icon bounds.
+     * @param size Diameter/Side length of the square icon area.
+     * @param color The color to use for rendering.
+     */
     fun draw(canvas: Canvas, domain: String, x: Float, y: Float, size: Float, color: Int) {
         fillPaint.color = color
         strokePaint.color = color
diff --git a/app/src/main/java/com/example/retroha/ui/LanguageIconDrawable.kt b/app/src/main/java/com/example/retroha/ui/LanguageIconDrawable.kt
index 50ce66e..f37b4e4 100644
--- a/app/src/main/java/com/example/retroha/ui/LanguageIconDrawable.kt
+++ b/app/src/main/java/com/example/retroha/ui/LanguageIconDrawable.kt
@@ -5,6 +5,13 @@ import android.graphics.Paint
 import android.graphics.PixelFormat
 import android.graphics.drawable.Drawable
 import com.example.retroha.theme.Colors
+
+/**
+ * A custom [Drawable] representing a simplified globe icon.
+ * Used in the UI to indicate language settings.
+ * 
+ * @param sizePx The intrinsic size of the drawable in pixels.
+ */
 class LanguageIconDrawable(private val sizePx: Int) : Drawable() {
     private val paint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
         style = Paint.Style.STROKE
diff --git a/app/src/main/java/com/example/retroha/ui/LightControlDialog.kt b/app/src/main/java/com/example/retroha/ui/LightControlDialog.kt
index 4085177..9da0b7f 100644
--- a/app/src/main/java/com/example/retroha/ui/LightControlDialog.kt
+++ b/app/src/main/java/com/example/retroha/ui/LightControlDialog.kt
@@ -15,6 +15,16 @@ import android.widget.LinearLayout
 import android.widget.SeekBar
 import android.widget.TextView
 import com.example.retroha.theme.Colors
+
+/**
+ * A custom dialog for controlling the brightness of a light entity.
+ * Features a minimalist Bauhaus design and automatic updates on slider release.
+ * 
+ * @param context The activity context.
+ * @param entityName Friendly name of the light to display.
+ * @param initialBrightness The brightness level (0-255) when the dialog is opened.
+ * @param onBrightnessChanged Callback triggered when the user finishes adjusting the slider.
+ */
 class LightControlDialog(
     context: Context,
     private val entityName: String,
diff --git a/app/src/main/java/com/example/retroha/ui/WidgetAdapter.kt b/app/src/main/java/com/example/retroha/ui/WidgetAdapter.kt
index c9ee3ad..1295ef7 100644
--- a/app/src/main/java/com/example/retroha/ui/WidgetAdapter.kt
+++ b/app/src/main/java/com/example/retroha/ui/WidgetAdapter.kt
@@ -4,22 +4,37 @@ import android.view.View
 import android.view.ViewGroup
 import android.widget.BaseAdapter
 import com.example.retroha.model.WidgetConfig
+
+/**
+ * Adapter for the main dashboard grid.
+ * Manages the lifecycle and data binding for [WidgetCardView] instances.
+ */
 class WidgetAdapter(
     private val context: Context,
     initialItems: List<WidgetConfig>
 ) : BaseAdapter() {
     private val items = mutableListOf<WidgetConfig>().apply { addAll(initialItems) }
+
+    /** Callback for short clicks (toggle/execute action). */
     var onToggle: ((WidgetConfig) -> Unit)? = null
+    /** Callback for long clicks (more info / brightness dialog). */
     var onLongToggle: ((WidgetConfig) -> Unit)? = null
+
+    /**
+     * Updates the list of items displayed in the grid.
+     */
     fun updateItems(newItems: List<WidgetConfig>) {
         items.clear()
         items.addAll(newItems)
         notifyDataSetChanged()
     }
+
     override fun getCount() = items.size
     override fun getItem(position: Int) = items[position]
     override fun getItemId(position: Int) = items[position].id
     override fun hasStableIds() = true
+    
+    /** Provides or recycles a [WidgetCardView] for the grid. */
     override fun getView(position: Int, convertView: View?, parent: ViewGroup): View {
         val card = convertView as? WidgetCardView ?: WidgetCardView(context).also { 
             it.onToggle = onToggle
diff --git a/app/src/main/java/com/example/retroha/ui/WidgetCardView.kt b/app/src/main/java/com/example/retroha/ui/WidgetCardView.kt
index ef42940..2d4aa10 100644
--- a/app/src/main/java/com/example/retroha/ui/WidgetCardView.kt
+++ b/app/src/main/java/com/example/retroha/ui/WidgetCardView.kt
@@ -17,6 +17,11 @@ import com.example.retroha.model.WidgetConfig
 import com.example.retroha.model.WidgetInteraction
 import com.example.retroha.model.toWidgetInteraction
 import com.example.retroha.theme.Colors
+/**
+ * A highly optimized custom [View] that renders a single Home Assistant entity card.
+ * Part of the "Bauhaus Canvas" engine, it avoids XML overhead by manually drawing everything.
+ * Supports state-based coloring, pulsing animations for transitions, and haptic feedback.
+ */
 class WidgetCardView(context: Context) : View(context) {
     private val density = resources.displayMetrics.density
     private val borderPx     = dp(2)
@@ -41,7 +46,10 @@ class WidgetCardView(context: Context) : View(context) {
         color = Colors.GRAY_MID; textSize = sp(10); typeface = Fonts.REGULAR
     }
     private val pulseInterpolator = DecelerateInterpolator()
+
+    /** Callback for short clicks (toggle/execute action). */
     var onToggle: ((WidgetConfig) -> Unit)? = null
+    /** Callback for long clicks (more info / brightness dialog). */
     var onLongToggle: ((WidgetConfig) -> Unit)? = null
     private var config: WidgetConfig? = null
     private var currentInteraction: WidgetInteraction = WidgetInteraction.READ_ONLY
@@ -74,6 +82,12 @@ class WidgetCardView(context: Context) : View(context) {
         updateExecIconPath(w - shadowPx)
         rebuildLayoutsIfNeeded(w)
     }
+    /**
+     * Binds new data to the widget and updates the visual state.
+     * Triggers layout recalculation if text content or view width has changed.
+     * 
+     * @param cfg The new configuration data for this widget.
+     */
     fun bind(cfg: WidgetConfig) {
         config = cfg
         currentInteraction = cfg.domain.toWidgetInteraction()
diff --git a/app/src/main/res/values-en/strings.xml b/app/src/main/res/values-en/strings.xml
index 6e33656..0c837b3 100644
--- a/app/src/main/res/values-en/strings.xml
+++ b/app/src/main/res/values-en/strings.xml
@@ -1,6 +1,6 @@
 <resources>
     <string name="app_name">RetroHA</string>
-    <string name="app_title">HA_PANEL</string>
+    <string name="app_title">RetroHA</string>
     <string name="state_on">ON</string>
     <string name="state_off">OFF</string>
     <string name="state_unavailable">UNAVAILABLE</string>
@@ -18,7 +18,7 @@
     <string name="instruction_1">1. CLICK TILE TO TOGGLE (ON/OFF).</string>
     <string name="instruction_2">2. LONG PRESS LIGHT TILE TO OPEN BRIGHTNESS MENU.</string>
     <string name="instruction_3">3. USE TABS AT TOP TO FILTER DEVICES.</string>
-    <string name="instruction_4">4. CLICK \'HA_PANEL\' TITLE TO FORCE REFRESH.</string>
+    <string name="instruction_4">4. CLICK \'RetroHA\' TITLE TO FORCE REFRESH.</string>
     <string name="instruction_5">5. CONNECTION CHANGE CLEARS WIDGET LIST.</string>
     <string name="label_url">URL ADDRESS</string>
     <string name="label_token">ACCESS TOKEN</string>
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index bbd3922..9d80947 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -1,6 +1,6 @@
 <resources>
     <string name="app_name">RetroHA</string>
-    <string name="app_title">HA_PANEL</string>
+    <string name="app_title">RetroHA</string>
     <string name="state_on">WŁ.</string>
     <string name="state_off">WYŁ.</string>
     <string name="state_unavailable">NIEOSIĄGALNE</string>
@@ -18,7 +18,7 @@
     <string name="instruction_1">1. KLIKNIJ KAFELEK, ABY PRZEŁĄCZYĆ (ON/OFF).</string>
     <string name="instruction_2">2. PRZYTRZYMAJ KAFELEK ŚWIATŁA, ABY OTWORZYĆ MENU JASNOŚCI.</string>
     <string name="instruction_3">3. UŻYWAJ ZAKŁADEK NA GÓRZE DO FILTROWANIA URZĄDZEŃ.</string>
-    <string name="instruction_4">4. KLIKNIJ TYTUŁ \'HA_PANEL\', ABY WYMUSIĆ ODŚWIEŻENIE.</string>
+    <string name="instruction_4">4. KLIKNIJ TYTUŁ \'RetroHA\', ABY WYMUSIĆ ODŚWIEŻENIE.</string>
     <string name="instruction_5">5. ZMIANA POŁĄCZENIA CZYŚCI LISTĘ WIDŻETÓW.</string>
     <string name="label_url">ADRES URL</string>
     <string name="label_token">TOKEN DOSTĘPU</string>
diff --git a/shared/src/main/kotlin/com/example/retroha/i18n/StringKey.kt b/shared/src/main/kotlin/com/example/retroha/i18n/StringKey.kt
index 9816b05..6a1f723 100644
--- a/shared/src/main/kotlin/com/example/retroha/i18n/StringKey.kt
+++ b/shared/src/main/kotlin/com/example/retroha/i18n/StringKey.kt
@@ -1,50 +1,102 @@
 package com.example.retroha.i18n
+
+/**
+ * Universal identifiers for translatable strings used across the application.
+ * Each key maps to a localized string in the platform-specific implementation.
+ */
 enum class StringKey {
+    /** Label for 'ON' state. */
     STATE_ON,
+    /** Label for 'OFF' state. */
     STATE_OFF,
+    /** Label for 'UNAVAILABLE' state. */
     STATE_UNAVAILABLE,
+    /** Label for transitioning state. */
     STATE_TOGGLING,
+    /** Button text for Settings. */
     BTN_SETTINGS,
+    /** Placeholder toast for adding widgets. */
     TOAST_WIDGET_ADD,
+    /** Tab label: All. */
     TAB_ALL,
+    /** Tab label: Lighting. */
     TAB_LIGHTING,
+    /** Tab label: Sockets. */
     TAB_SOCKETS,
+    /** Tab label: Power. */
     TAB_POWER,
+    /** Tab label: Weather. */
     TAB_WEATHER,
+    /** Title for entity selection screen. */
     TITLE_SETTINGS,
+    /** Title for connection configuration screen. */
     TITLE_CONNECTION,
+    /** Title for user manual screen. */
     TITLE_INSTRUCTIONS,
+    /** Instruction line 1. */
     INSTRUCTION_1,
+    /** Instruction line 2. */
     INSTRUCTION_2,
+    /** Instruction line 3. */
     INSTRUCTION_3,
+    /** Instruction line 4. */
     INSTRUCTION_4,
+    /** Instruction line 5. */
     INSTRUCTION_5,
+    /** Input label for URL. */
     LABEL_URL,
+    /** Input label for Access Token. */
     LABEL_TOKEN,
+    /** Input label for refresh interval. */
     LABEL_REFRESH,
+    /** Button text for testing and saving connection. */
     BTN_TEST_SAVE,
+    /** Button text for deleting all widgets. */
     BTN_DELETE_ALL,
+    /** Button text for saving selected entities. */
     BTN_SAVE_SELECTED,
+    /** Button text for language change. */
     BTN_CHANGE_LANG,
+    /** Status: Connecting. */
     STATUS_CONNECTING,
+    /** Status: Successfully connected / Online. */
     STATUS_CONNECTED,
+    /** Status: Offline. */
     STATUS_OFFLINE,
+    /** Status error: Home Assistant reported an error. */
     STATUS_ERROR_HA,
+    /** Status error: Authentication token missing. */
     STATUS_NO_TOKEN,
+    /** Title for language selection screen. */
     TITLE_SELECT_LANGUAGE,
+    /** Toast: Refreshing data. */
     STATUS_REFRESHING,
+    /** Status: Success message. */
     STATUS_SUCCESS,
+    /** Toast: Configuration saved and widgets cleared. */
     TOAST_SAVED_CLEARED,
+    /** General error status. */
     STATUS_ERROR,
+    /** Network connection error status. */
     STATUS_ERROR_NETWORK,
+    /** Confirmation message for mass deletion. */
     CONFIRM_DELETE_ALL,
+    /** Warning message for connection change. */
     CONFIRM_CHANGE_CONN,
+    /** Label for brightness level. */
     DIALOG_BRIGHTNESS,
+    /** Dialog button: Set/Apply. */
     DIALOG_SET,
+    /** Dialog button: Cancel. */
     DIALOG_CANCEL,
+    /** Dialog title: Warning. */
     DIALOG_WARNING,
+    /** Dialog button: Confirm connection change. */
     DIALOG_YES_CHANGE,
+    /** Dialog button: Confirm deletion. */
     DIALOG_YES_DELETE,
+    /** Toast: Cache/Dashboard cleared. */
     TOAST_CLEARED,
+    /** Toast: Selected entities saved. */
     TOAST_ENTITIES_SAVED
 }
diff --git a/shared/src/main/kotlin/com/example/retroha/i18n/Strings.kt b/shared/src/main/kotlin/com/example/retroha/i18n/Strings.kt
index fc6786c..4c1f278 100644
--- a/shared/src/main/kotlin/com/example/retroha/i18n/Strings.kt
+++ b/shared/src/main/kotlin/com/example/retroha/i18n/Strings.kt
@@ -1,4 +1,14 @@
 package com.example.retroha.i18n
+
+/**
+ * Interface defining the contract for retrieving localized strings.
+ * This allows the business logic to remain platform-independent.
+ */
 interface Strings {
+    /**
+     * Retrieves a localized string for the given key.
+     * @param key The universal string identifier.
+     * @return The localized text for the current application language.
+     */
     operator fun get(key: StringKey): String
 }
diff --git a/shared/src/main/kotlin/com/example/retroha/model/EntityState.kt b/shared/src/main/kotlin/com/example/retroha/model/EntityState.kt
index f225c5a..946f039 100644
--- a/shared/src/main/kotlin/com/example/retroha/model/EntityState.kt
+++ b/shared/src/main/kotlin/com/example/retroha/model/EntityState.kt
@@ -1,2 +1,16 @@
 package com.example.retroha.model
-enum class EntityState { ON, OFF, UNAVAILABLE, TOGGLING }
+
+/**
+ * Represents the fundamental visual and logical states of a Home Assistant entity.
+ * Used by the UI layer to determine colors and animations.
+ */
+enum class EntityState {
+    /** Entity is active (e.g., light is on, switch is closed). */
+    ON,
+    /** Entity is inactive (e.g., light is off, switch is open). */
+    OFF,
+    /** Entity is disconnected or its state cannot be determined. */
+    UNAVAILABLE,
+    /** Entity is currently transitioning between states (e.g., command sent but not confirmed). */
+    TOGGLING
+}
diff --git a/shared/src/main/kotlin/com/example/retroha/model/WidgetConfig.kt b/shared/src/main/kotlin/com/example/retroha/model/WidgetConfig.kt
index 72e50ca..218ba9b 100644
--- a/shared/src/main/kotlin/com/example/retroha/model/WidgetConfig.kt
+++ b/shared/src/main/kotlin/com/example/retroha/model/WidgetConfig.kt
@@ -1,4 +1,18 @@
 package com.example.retroha.model
+
+/**
+ * Data configuration class for a UI widget.
+ * Holds all necessary information to render a Home Assistant entity on the dashboard.
+ *
+ * @property id Unique local identifier for the widget instance.
+ * @property entityId The full Home Assistant entity ID (e.g., "light.living_room").
+ * @property label The display name shown on the card top section.
+ * @property value The primary state value or measurement (e.g., "ON", "21.5°C").
+ * @property secondary Subtitle or additional info (e.g., battery level, wattage).
+ * @property domain The HA domain (light, switch, sensor, etc.) used for icon selection.
+ * @property state Current logical state for UI coloring and animations.
+ * @property brightness Optional brightness value (0-255) for light-domain entities.
+ */
 data class WidgetConfig(
     val id: Long,
     val entityId: String,
diff --git a/shared/src/main/kotlin/com/example/retroha/model/WidgetInteraction.kt b/shared/src/main/kotlin/com/example/retroha/model/WidgetInteraction.kt
index 8bba283..682eb90 100644
--- a/shared/src/main/kotlin/com/example/retroha/model/WidgetInteraction.kt
+++ b/shared/src/main/kotlin/com/example/retroha/model/WidgetInteraction.kt
@@ -1,5 +1,22 @@
 package com.example.retroha.model
-enum class WidgetInteraction { TOGGLE, EXECUTE, READ_ONLY }
+
+/**
+ * Defines the type of user interaction supported by a widget.
+ */
+enum class WidgetInteraction { 
+    /** Supports switching between ON and OFF states. */
+    TOGGLE, 
+    /** Supports one-shot execution (e.g., triggering a script). */
+    EXECUTE, 
+    /** Information only, no user interaction allowed. */
+    READ_ONLY 
+}
+
+/**
+ * Maps a Home Assistant domain string to its appropriate [WidgetInteraction] type.
+ * 
+ * @return The interaction type (TOGGLE, EXECUTE, or READ_ONLY) based on the domain logic.
+ */
 fun String.toWidgetInteraction(): WidgetInteraction = when (this) {
     "light",
     "switch",
diff --git a/shared/src/main/kotlin/com/example/retroha/theme/Colors.kt b/shared/src/main/kotlin/com/example/retroha/theme/Colors.kt
index 96233e9..67d2bae 100644
--- a/shared/src/main/kotlin/com/example/retroha/theme/Colors.kt
+++ b/shared/src/main/kotlin/com/example/retroha/theme/Colors.kt
@@ -1,28 +1,65 @@
 package com.example.retroha.theme
+
+/**
+ * Bauhaus-inspired color palette for the application.
+ * All colors are defined as ARGB integers.
+ */
 object Colors {
+    /** Pure black for borders, shadows, and text. */
     const val BLACK  = 0xFF000000.toInt()
+    /** Pure white for backgrounds and default states. */
     const val WHITE  = 0xFFFFFFFF.toInt()
+    /** Bauhaus red. Used for scripts and high-priority states. */
     const val RED    = 0xFFE23A24.toInt()
+    /** Bauhaus yellow. Used for active (ON) highlights. */
     const val YELLOW = 0xFFFAD02C.toInt()
+    /** Bauhaus blue. Used for switches and interactive elements. */
     const val BLUE   = 0xFF0056B3.toInt()
+    /** Bauhaus orange. Used for light-domain entities. */
     const val ORANGE = 0xFFF4801A.toInt()
+    /** Bauhaus green. Secondary status color. */
     const val GREEN  = 0xFF2D7D46.toInt()
+    /** Bauhaus violet. Used for sensors and measurements. */
     const val VIOLET = 0xFF6B3FA0.toInt()
+    
+    /** Light gray for background elements. */
     const val GRAY_LIGHT = 0xFFCCCCCC.toInt()
+    /** Mid gray for disabled borders. */
     const val GRAY_MID   = 0xFF888888.toInt()
+    /** Dark gray for default category stripes. */
     const val GRAY_DARK  = 0xFF444444.toInt()
+
+    // Semantic status colors
+    /** Card background color when entity is ON. */
     const val STATUS_ON          = YELLOW      
+    /** Card background color when entity is OFF. */
     const val STATUS_OFF         = WHITE       
+    /** Card background color when entity is unavailable. */
     const val STATUS_UNAVAILABLE = GRAY_LIGHT  
+    /** Card background color during state transition. */
     const val STATUS_TOGGLING    = WHITE       
+
+    // Semantic border colors
+    /** Default card border color. */
     const val BORDER_DEFAULT     = BLACK
+    /** Border color during state transition. */
     const val BORDER_TOGGLING    = BLUE
+    /** Border color when entity is unavailable. */
     const val BORDER_UNAVAILABLE = GRAY_MID
+
+    // Domain-specific side stripes
+    /** Accent stripe for light domain. */
     const val STRIPE_LIGHT         = ORANGE  
+    /** Accent stripe for switch domain. */
     const val STRIPE_SWITCH        = BLUE
+    /** Accent stripe for sensor domain. */
     const val STRIPE_SENSOR        = VIOLET
+    /** Accent stripe for binary_sensor domain. */
     const val STRIPE_BINARY_SENSOR = VIOLET
+    /** Accent stripe for script domain. */
     const val STRIPE_SCRIPT        = RED
+    /** Accent stripe for automation domain. */
     const val STRIPE_AUTOMATION    = RED
+    /** Default accent stripe for unknown domains. */
     const val STRIPE_DEFAULT       = GRAY_DARK  
 }