feat: Instructions for manual enabling of permission

[PLNech]

Feature

Flow for manual enabling of recording permission.

• Implementation in app, with default UI:

override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    if (Voice.isRecordPermissionWithResults(requestCode, grantResults)) {
        when {
            Voice.isPermissionGranted(grantResults) -> showVoiceDialog()
            Voice.shouldExplainPermission(this) -> Voice.showPermissionRationale(getPermissionView(), this)
            else -> Voice.showPermissionManualInstructions(getPermissionView())
        }
    }
}

• Users can customize the rationale's message/CTA (whyAllow, buttonAllow), and the manual instructions' message/CTA/instructions (whyEnable, buttonEnable, howEnable)
• If one wants a different UI, they can call Voice.openAppSettings() from their own UI logic

Questions

• As showPermissionRationale and showPermissionManualInstructions have two overloads for String and StringRes parameters, default arguments caused an Overload resolution ambiguity. The solution I found was a third overload with the minimum amount of arguments, but let me know if you have a better approach!

• WDYT of refactoring all those as Activity.* extension methods? I feel it improves DX by allowing this.showX() instead of Voice.showX(this), but might pollute the scope/prevent discoverability (for example with Activity.openAppSettings()). @q-litzler what's your take on this?

• Documenting overloads results in duplicated documentation. Is there a way to avoid that or is it a necessary evil? 🤔

[q-litzler]

As discussed, let's offer only one method for showPermissionManualInstructions as a clearer way to present our helpers method.

This looks good. To answer your question, I'm in favour of using function extensions rather that an Object with static methods. It is the idiomatic way to add functionalities to a class in Kotlin.

I don't see any solutions for duplicated documentation.