Skip to content

Commit c75cbe0

Browse files
laramcdlaramcd
committed
added missing documentation
1 parent 41cbf35 commit c75cbe0

4 files changed

Lines changed: 108 additions & 4 deletions

File tree

‎app/src/main/java/com/nlinterface/activities/GroceryListActivity.kt‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,12 @@ class GroceryListActivity : AppCompatActivity(), GroceryListCallback {
193193

194194
}
195195

196+
/**
197+
* Deletes a grocery item from the grocery list given the name of the item. If it does not
198+
* exist, state that out loud.
199+
*
200+
* @param groceryItemName: String, the name of the Grocery Item to be deleted.
201+
*/
196202
private fun deleteGroceryItem(groceryItemName: String) {
197203

198204
val groceryItem = findGroceryItemByName(groceryItemName)
@@ -206,6 +212,12 @@ class GroceryListActivity : AppCompatActivity(), GroceryListCallback {
206212
}
207213
}
208214

215+
/**
216+
* Given the name, return the corresponding Grocery Item.
217+
*
218+
* @param groceryItemName: String, the name of the desired Grocery Item
219+
* @return the found Grocery Item or null if it does not exists
220+
*/
209221
private fun findGroceryItemByName(groceryItemName: String): GroceryItem? {
210222
return groceryItemList.find { it.itemName.lowercase() == groceryItemName }
211223
}
@@ -350,12 +362,25 @@ class GroceryListActivity : AppCompatActivity(), GroceryListCallback {
350362

351363
}
352364

365+
/**
366+
* Requests a response from the user by reading out the question and activating voice control
367+
* once the question has been read fully.
368+
*
369+
* @param question: String, the question to ask the user
370+
*/
353371
private suspend fun requestResponse(question: String) {
354372
viewModel.sayAndAwait(question)
355373
viewModel.setSpeechRecognitionListener(STTInputType.ANSWER)
356374
viewModel.handleSpeechBegin()
357375
}
358376

377+
/**
378+
* Called once the STT system returns a response by the user. Depending on the previous command
379+
* and the given response, the action is executed.
380+
*
381+
* @param command: String, the command preceding the response
382+
* @param response: String, the response given by the user
383+
*/
359384
private fun executeItemCommand(command: String, response: String) {
360385

361386
if (response != resources.getString(R.string.cancel)) {
@@ -386,6 +411,13 @@ class GroceryListActivity : AppCompatActivity(), GroceryListCallback {
386411
}
387412
}
388413

414+
/**
415+
* Requests the ViewModel to add a new Grocery Item to the cart by name. If no Grocery Item
416+
* exists for an input item name, this is stated. If the item is already in the cart, this, too,
417+
* is stated.
418+
*
419+
* @param itemName: String, the name of the item to be added to the cart
420+
*/
389421
private fun addItemToCart(itemName: String) {
390422

391423
val groceryItem = findGroceryItemByName(itemName)
@@ -406,6 +438,13 @@ class GroceryListActivity : AppCompatActivity(), GroceryListCallback {
406438

407439
}
408440

441+
/**
442+
* Requests the ViewModel to remove a new Grocery Item from the cart by name. If no Grocery Item
443+
* exists for an input item name, this is stated. If the item is already not in the cart, this,
444+
* too, is stated.
445+
*
446+
* @param itemName: String, the name of the item to be removed from the cart
447+
*/
409448
private fun removeItemFromCart(itemName: String) {
410449
val groceryItem = findGroceryItemByName(itemName)
411450

@@ -424,6 +463,12 @@ class GroceryListActivity : AppCompatActivity(), GroceryListCallback {
424463
}
425464
}
426465

466+
/**
467+
* Checks and states whether an item is on the list by name. If the item is on the list, also
468+
* states if it is in the cart.
469+
*
470+
* @param itemName: String, the item name to check the list for
471+
*/
427472
private fun checkItemOnList(itemName: String) {
428473

429474
val groceryItem = findGroceryItemByName(itemName)

‎app/src/main/java/com/nlinterface/activities/MainActivity.kt‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,6 @@ class MainActivity : AppCompatActivity() {
165165

166166
}
167167

168-
169168
/**
170169
* Handles Navigation commands of the format "go to X". If the command is valid, navigate to
171170
* the desired activity.

‎app/src/main/java/com/nlinterface/activities/PlaceDetailsActivity.kt‎

Lines changed: 57 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -218,12 +218,25 @@ class PlaceDetailsActivity : AppCompatActivity(), PlaceDetailsItemCallback {
218218

219219
}
220220

221+
/**
222+
* Requests a response from the user by reading out the question and activating voice control
223+
* once the question has been read fully.
224+
*
225+
* @param question: String, the question to ask the user
226+
*/
221227
private suspend fun requestResponse(question: String) {
222228
viewModel.sayAndAwait(question)
223229
viewModel.setSpeechRecognitionListener(STTInputType.ANSWER)
224230
viewModel.handleSpeechBegin()
225231
}
226232

233+
/**
234+
* Called when the user has given a response to an item quesion.Depending on the previous
235+
* command and the given response, the action is executed.
236+
*
237+
* @param command: String, the command preceding the response
238+
* @param response: String, the response given by the user
239+
*/
227240
private fun executeItemCommand(command: String, response: String) {
228241

229242
if (response != resources.getString(R.string.cancel)) {
@@ -252,6 +265,13 @@ class PlaceDetailsActivity : AppCompatActivity(), PlaceDetailsItemCallback {
252265

253266
}
254267

268+
/**
269+
* Requests the ViewModel to add a new Place Details Item to the favorites by name. If no
270+
* Place Details Item exists for the given item name, this is stated. If the item is already a
271+
* favorite, this, too is stated.
272+
*
273+
* @param storeName: String, the name of the item to be added to favorites
274+
*/
255275
private fun addToFavorites(storeName: String) {
256276

257277
val placeDetailsItem = findPlaceByName(storeName)
@@ -272,6 +292,13 @@ class PlaceDetailsActivity : AppCompatActivity(), PlaceDetailsItemCallback {
272292

273293
}
274294

295+
/**
296+
* Requests the ViewModel to remove a Place Details Item from the favorites by name. If no
297+
* Place Details Item exists for the given item name, this is stated. If the item is not a
298+
* favorite, this, too is stated.
299+
*
300+
* @param storeName: String, the name of the item to be removed from favorites
301+
*/
275302
private fun removeFromFavorites(storeName: String) {
276303

277304
Log.println(Log.DEBUG, "rmFav", "1")
@@ -298,6 +325,11 @@ class PlaceDetailsActivity : AppCompatActivity(), PlaceDetailsItemCallback {
298325

299326
}
300327

328+
/**
329+
* Handles voice commands for which a list of place detail items must be read out loud.
330+
*
331+
* @param command: String, the command given by the user
332+
*/
301333
private fun executeListCommand(command: String) {
302334

303335
Log.println(Log.DEBUG, "exec", command)
@@ -331,6 +363,10 @@ class PlaceDetailsActivity : AppCompatActivity(), PlaceDetailsItemCallback {
331363

332364
}
333365

366+
/**
367+
* Reads today's Opening Hours for a given store name out loud. If the store name does not
368+
* correspond to a place details item on the list, state this.
369+
*/
334370
private fun stateOpeningHours(storeName: String) {
335371

336372
val placeDetailsItem = findPlaceByName(storeName)
@@ -351,6 +387,11 @@ class PlaceDetailsActivity : AppCompatActivity(), PlaceDetailsItemCallback {
351387

352388
}
353389

390+
/**
391+
* Checks whether a store is currently open, based on its opening Hours and the current time.
392+
*
393+
* @param openingHours: List<String> the opening hours of a store
394+
*/
354395
private fun isOpen(openingHours: List<String>): Boolean {
355396

356397
val dayOfWeek = Math.floorMod(Calendar.getInstance().get(Calendar.DAY_OF_WEEK) - 2, 7)
@@ -517,20 +558,33 @@ class PlaceDetailsActivity : AppCompatActivity(), PlaceDetailsItemCallback {
517558

518559
}
519560

520-
private fun deletePlaceDetailsItem(response: String) {
561+
/**
562+
* Checks if the desired Place Details Item exist in the list and deletes it. If it does not
563+
* exist, states this.
564+
*
565+
* @param itemName: name to be deleted
566+
*/
567+
private fun deletePlaceDetailsItem(itemName: String) {
521568

522-
val placeDetailsItem = findPlaceByName(response)
569+
val placeDetailsItem = findPlaceByName(itemName)
523570

524571
if (placeDetailsItem != null) {
525572
deletePlaceDetailsItem(placeDetailsItem, placeDetailsItemList.indexOf(placeDetailsItem))
526573
} else {
527574
viewModel.say(
528-
resources.getString(R.string.STORENAME_is_not_on_the_list, response)
575+
resources.getString(R.string.STORENAME_is_not_on_the_list, itemName)
529576
)
530577
}
531578

532579
}
533580

581+
/**
582+
* Searches the list for a Place Detail Item by its name.
583+
*
584+
* @param storeName: String, the name of the place to be deleted
585+
*
586+
* @return The Place Details Item if it exists, else null
587+
*/
534588
private fun findPlaceByName(storeName: String): PlaceDetailsItem? {
535589
return placeDetailsItemList.find { it.storeName.lowercase() == storeName }
536590
}

‎app/src/main/java/com/nlinterface/utility/utils.kt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,12 @@ fun getLocaleType(): LocaleType {
6565

6666
}
6767

68+
/**
69+
* Handles navigation to next activity.
70+
*
71+
* @param context
72+
* @param activity: ActivityType, Enum specifying the activity
73+
*/
6874
fun navToActivity(context: Context, activity: ActivityType) {
6975

7076
when (activity) {

0 commit comments

Comments
 (0)