Fully documented all Kotlin files and added TODOs to functions that need to be updated in some way

app/src/main/java/com/denizk0461/studip/viewmodel/CanteenViewModel.kt

@@ -8,18 +8,57 @@ import com.denizk0461.studip.model.DietaryPrefObject
 import com.denizk0461.studip.model.DietaryPreferences
 import com.denizk0461.studip.model.OfferDate
 
+/**
+ * View model for [com.denizk0461.studip.fragment.CanteenFragment]
+ *
+ * @param app   reference to the app
+ */
 class CanteenViewModel(app: Application) : TemplateViewModel(app) {
 
+    // Instantiate a parser, should the user want to refresh the canteen offers
     private val parser = StwParser()
 
+    /**
+     * Retrieves all Stud.IP events.
+     *
+     * @return all Stud.IP events exposed through a LiveData object
+     */
     val allOffers: LiveData<List<CanteenOffer>> = repo.allOffers
 
+    /**
+     * Retrieve the user's dietary preferences.
+     *
+     * @return dietary preferences
+     */
     fun getDietaryPrefs(): DietaryPrefObject = repo.getDietaryPrefsAsObj()
 
+    /**
+     * Retrieves all canteen offer date objects.
+     *
+     * @return a list of instances of canteen offer dates
+     */
     fun getDates(): List<OfferDate> = returnBlocking { repo.getDates() }
 
-    fun fetchOffers(onRefreshUpdate: (status: Int) -> Unit, onFinish: () -> Unit) { doAsync { parser.parse(onRefreshUpdate, onFinish) }}
+    // Fetch the canteen offers asynchronously. Updates will be provided through a LiveData object.
+    fun fetchOffers(onRefreshUpdate: (status: Int) -> Unit, onFinish: () -> Unit) {
+        doAsync { parser.parse(onRefreshUpdate, onFinish) }
+    }
 
-    fun setPreference(pref: DietaryPreferences, newValue: Boolean) { repo.setPreference(pref, newValue) }
+    /**
+     * Updates a given dietary preference to a new value.
+     *
+     * @param pref      preference to be updated
+     * @param newValue  value to set the preference to
+     */
+    fun setPreference(pref: DietaryPreferences, newValue: Boolean) {
+        repo.setPreference(pref, newValue)
+    }
+
+    /**
+     * Retrieves a single user-specified dietary preference.
+     *
+     * @param pref  the dietary preference that should be retrieved
+     * @return      whether the preference needs to be met
+     */
     fun getPreference(pref: DietaryPreferences): Boolean = repo.getPreference(pref)
 }

app/src/main/java/com/denizk0461/studip/viewmodel/EventViewModel.kt

@@ -4,10 +4,17 @@ import android.app.Application
 import androidx.lifecycle.LiveData
 import com.denizk0461.studip.model.StudIPEvent
 
+/**
+ * View model for [com.denizk0461.studip.fragment.EventFragment]
+ *
+ * @param app   reference to the app
+ */
 class EventViewModel(app: Application) : TemplateViewModel(app) {
 
+    /**
+     * Retrieves all Stud.IP events.
+     *
+     * @return all Stud.IP events exposed through a LiveData object
+     */
     val allEvents: LiveData<List<StudIPEvent>> = repo.allEvents
-
-    fun insertEvent(event: StudIPEvent) { repo.insertEvent(event) }
-    fun nukeEvents() { repo.nukeEvents() }
 }

app/src/main/java/com/denizk0461/studip/viewmodel/FetcherViewModel.kt

@@ -3,9 +3,22 @@ package com.denizk0461.studip.viewmodel
 import android.app.Application
 import com.denizk0461.studip.model.StudIPEvent
 
+/**
+ * View model for [com.denizk0461.studip.activity.FetcherActivity]
+ *
+ * @param app   reference to the app
+ */
 class FetcherViewModel(app: Application) : TemplateViewModel(app) {
 
-    fun insertEvent(event: StudIPEvent) { repo.insertEvent(event) }
+    /**
+     * Save a list of Stud.IP events to persistent storage asynchronously.
+     *
+     * @param events    list of events to be saved
+     */
     fun insertEvents(events: List<StudIPEvent>) { doAsync { repo.insertEvents(events) } }
+
+    /**
+     * Delete all Stud.IP events from the database asynchronously.
+     */
     fun nukeEvents() { doAsync { repo.nukeEvents() } }
 }

app/src/main/java/com/denizk0461/studip/viewmodel/TemplateViewModel.kt

@@ -4,21 +4,43 @@ import android.app.Application
 import androidx.lifecycle.AndroidViewModel
 import androidx.lifecycle.viewModelScope
 import com.denizk0461.studip.data.Dependencies
-import com.denizk0461.studip.db.EventRepository
+import com.denizk0461.studip.db.AppRepository
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.runBlocking
 
+/**
+ * View model super class providing common functionality. View model is used to provide an
+ * abstraction between the view classes and the data providers. All view models should inherit from
+ * this.
+ *
+ * @param app   reference to the app
+ */
 open class TemplateViewModel(app: Application) : AndroidViewModel(app) {
 
-    protected val repo: EventRepository = Dependencies.repo
+    // Reference to the app's repository for database transactions
+    protected val repo: AppRepository = Dependencies.repo
 
+    /**
+     * Execute a function asynchronously on the I/O thread. Be careful not to execute UI commands
+     * with this.
+     *
+     * @param function  the action that will be executed asynchronously
+     */
     fun doAsync(function: () -> Unit) {
         viewModelScope.launch(Dispatchers.IO) {
             function()
         }
     }
 
+    /**
+     * Execute a function that needs to be ran on an I/O thread and return a value. This is a simple
+     * but inefficient solution to retrieving data from the database without the need for a LiveData
+     * object, which should always be preferred.
+     *
+     * @param function  the action that will be executed on the I/O thread
+     * @return          any value returned by the executing function
+     */
     fun <T> returnBlocking(function: () -> T): T = runBlocking(Dispatchers.IO) {
         function()
     }